User-Defined Functions in API Reference Docs and Agent Consumption

User-defined functions in API reference docs are more than capabilities described for developers. They are the schema-level contracts that agents use to find tools, build calls, and ask for execution. Their definitions therefore shape runtime behavior directly. Making an API agent-ready starts with the precision of that contract.

What user-defined functions actually are in the context of agent systems

A user-defined function exposed through a function-calling or tool-use API binds a natural-language intent to a deterministic execution path. The model receives a user prompt and a catalog of declared tools, selects a tool, and returns a structured call with typed arguments. It does not execute the function itself. The application handles execution and feeds the result back, leaving the model in the role of intent router.

What, precisely, makes this a contract? In this arrangement, the JSON Schema definition is the model’s representation of the function. The declaration establishes which arguments the model can supply and how those arguments must be structured. Unlike a human developer reading reference docs, the model has no separate way to look at the code.

The four schema fields that govern whether an agent calls a function correctly

Four components give that interface its working shape. The name is the exact string the model returns when selecting a tool, so it must be stable and unambiguous across the catalog. The description supplies the natural-language signal for deciding when to call it. These fields serve different purposes. A recognizable name identifies the function, while its description establishes the conditions under which selection is appropriate.

The parameters or input_schema component defines the arguments through JSON Schema, including their types, formats, and constraints. An enum, for example, can restrict a parameter to “celsius” or “fahrenheit”, making a third option invalid under the schema. The required array names the parameters that must always be supplied. Omission from that array permits omission from the call, even when the application needs the field. None of these components is decorative, but the description has a distinct burden because argument correctness helps only after the model chooses the appropriate function.

Why the description field is doing more work than most API authors realize

The description is a decision trigger. A human reader can make sense of a short explanation through what they know about the domain, the docs around it, and trial and error. At selection time, the model instead depends on the tool description supplied to it. That difference creates a genuine design tension. Text that feels economical to an experienced developer may leave an agent without the distinctions needed to choose correctly.

Consider a description that says “processes a refund”. Which customer does it apply to, under what conditions, and with what side effects? Those questions expose decisions that the description leaves unresolved and that the model may answer by invention. The practical standard is to write for a developer who has never seen the system, stating when to call, when not to call, and what the function will and will not do. Whether that level of explicitness also makes the best human-facing reference remains an open design question.

The five failure modes that follow from schema gaps

Schema gaps produce a useful taxonomy of failures. Invalid JSON arguments arise when a generated call fails validation because its shape was not constrained tightly enough. Hallucinated tool names occur when the model invents a function, often because the available names or descriptions did not make clear what the tools could do. Missing required parameters form a separate class. Here, the declaration either left a field unmarked as mandatory or failed to make clear why it was needed.

Mis-typed parameters are the fourth class, with strings passed where integers are expected or the other way around. Underspecified types and conversational format hints leave room for those errors. The fifth class is prompt injection into destructive tools, where weak constraints let a hijacked model ask for an action with serious consequences. A refund to the wrong customer shows what can go wrong during execution. Making a call syntactically valid can fix a malformed value, but it leaves that risk in place.

Unconstrained strings expose the distinction especially clearly. A customer_id without an enum or pattern constraint gives the model no schema-level reason to reject an invented but plausible-looking identifier. A pattern can constrain its form without establishing that the customer exists. Application-layer validation remains the required backstop. The taxonomy helps teams look for a specific gap instead of treating every failed call as a model error they could not predict.

Schema constraints that eliminate whole failure classes at definition time

A prose warning is weaker than a declared constraint. Describing a field as “a date” leaves its representation open, while “ISO 8601 date string (YYYY-MM-DD) in Nepal Time (NPT)” gives a precise format instruction. Machine-readable types and format constraints move that precision into the contract itself. The distinction is between advice and validation. Text can guide generation, but the resulting argument must satisfy an enforced constraint to be acceptable.

When there is a finite set of values, enum is stronger still because it lists every option that is allowed. Under schema enforcement, an unlisted value cannot pass as valid for that parameter. A complete required array closes a different gap by making indispensable fields discussed in prose mandatory. These choices prevent whole classes of malformed calls before execution, though they do not replace validation of customer identity or safeguards for destructive actions. Does this make the schema longer and harder to maintain? It can, but that maintenance cost replaces the work of debugging ambiguity after it has become runtime behavior.

How function count and catalog organization affect agent selection accuracy

A large catalog puts the model in a crowded option space at every inference step, increasing the rate at which it chooses the wrong tool. Catalog organization is therefore a documentation variable in its own right. At this scale, each function must be clear and distinguishable from the other available functions.

Names such as create_customer and register_user can each appear descriptive in isolation while leaving their relationship unclear in the same catalog. Naming discipline must account for that neighborhood. For large tool sets, grouping related functions and using two-step routing narrows the selection task. A routing function first chooses a domain, after which the application loads the smaller domain-specific set. This structure belongs in schema design rather than in surrounding prose that the model may never receive.

How OpenAPI specifications become the source an agent actually reads

For teams maintaining OpenAPI, much of the operative documentation already has a machine-readable home. When the specification supplies the tool definitions, operationId becomes the tool name, while summary and description become the tool description. Path, query, and header parameters, together with requestBody, become inputSchema properties. The mapping makes existing field quality consequential. An explanation confined to a tutorial or changelog does not enter that contract unless a separate mechanism surfaces it.

Fern’s API design guide describes the fern diff CLI command as a way to detect breaking changes before deployment by comparing API definitions. That precision protects the interfaces on which both human and agent integrations depend. Cash App exposes /llms.txt and /llms-full.txt discovery artifacts together with Markdown page versions. Stripe’s AI integration docs provide guidance for using LLMs in integration workflows and installing its MCP server. These examples show complementary ways to make documentation available, without making discovery artifacts interchangeable with executable tool definitions.

What the OpenAPI-to-MCP mapping changes about how functions are invoked

OpenAPI specifies the interface, while MCP supplies a protocol through which an agent can call tools at runtime. In an OpenAPI-to-MCP bridge, operationId, descriptions, and parameters map to the tool name, tool description, and inputSchema. The generated server validates arguments against the schema, performs the HTTP request, and returns the response.

The GitHub projects conorbranagan/mcp-openapi and ivo-toby/mcp-openapi-server build this bridge, making OpenAPI-defined services available as tools that can be filtered by tag, operation type, or explicit tool list. For teams choosing an approach, function calling against a static specification works well for a single agent with a small tool set that stays the same. MCP is useful when more than one client needs the same tools, the catalog grows, or tools must change at runtime. MCP Gateways extend this model to catalogued APIs with scoped credentials and per-call policies. The additional runtime machinery does not remove the need for precise descriptions and constraints, because it still invokes the interface those definitions express.

The llms.txt convention as a discovery layer on top of structured schemas

The llms.txt convention addresses finding documentation. Its proposal is a Markdown file at /llms.txt at the site root, pointing AI systems toward the most important documentation. Cash App’s approach illustrates the separation between discovery indexes, readable Markdown content, and structured definitions for execution. Finding the right page cannot repair an ambiguous parameter declaration.

Anthropic’s engineering guidance notes that LLM-friendly documentation is commonly available in flat llms.txt files on official documentation sites. The guidance also emphasizes supplying documentation for the libraries, APIs, and SDKs that tools depend on. A meaningful share of sites use the format, though it is far from universal, and sites with more documentation use it more often because it suits IDE agents and coding assistants. How broadly the convention should be treated as a standard discovery mechanism remains unresolved. For teams serving those consumers, it is a useful addition, but not a universal fix or a substitute for schema precision.

Why documentation that drifts from the live API breaks agent pipelines faster than it breaks human workflows

A stale schema continues to authorize yesterday’s calls. A human developer encountering a deprecated parameter can inspect an error, consult the changelog, and adjust. An agent working from the unchanged definition will continue treating that parameter as valid. Because agents re-read the schema at invocation time, repetition does not supply the accumulated intuition that helps a developer compensate for drift. The mismatch can produce an unclear page, silent failures or wrong executions.

The same guide identifies internal usage as an underappreciated casualty of documentation drift, since internal teams also lose confidence when the reference no longer reflects behavior. Internal agents face the same divergence between declared and actual interfaces. More than 70% of organizations report that their documentation becomes outdated within weeks of release. The structural response is to move documentation from a post-shipping task into delivery. When API changes and reference updates happen on separate cycles, the agent’s execution contract can be out of date before its next call.

What teams building agent-facing APIs should audit in their existing reference docs

Teams checking that gap should start the audit with descriptions before taking on a full rewrite of the documentation. Does each function explain when to call it, when not to call it, and what it will not do? Next comes constraint coverage, including finite string values expressed as enums and explicit formats for dates, numbers, and identifiers. Required fields deserve a separate pass. The audit checks whether required reflects everything needed for safe execution or a conservative declaration designed to avoid validation errors.

The audit then moves from individual functions to the catalog and its supporting infrastructure. Are names distinguishable in context, and is selection reliable with the current function count, or does the catalog need routing? Beyond selection, are schemas and reference docs updated together when behavior changes? For IDE agents and coding assistants, a final discovery question is whether llms.txt or an equivalent points to the relevant material. This progression measures the distance from existing reference docs to a usable execution contract, with searchable documentation, automatic integration into agent workflows, and updates synchronized with product changes providing its ongoing support.