generate_text

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does meaningful work: it discloses billing against the deployment owner's credits, that only https links are accepted, and that links returned by this server are valid. It omits return shape, latency, and rate/limit behavior, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and cost, and every sentence carries information. The second half is one long run-on with stacked parenthetical examples, which costs some readability without adding waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param, no-annotation, no-output-schema tool it covers purpose, cost, model selection, and the media-input path. Remaining gaps are return format and failure behavior, which are secondary for a single-shot generation call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60%, so the schema documents model, system, and file_urls but leaves prompt and max_tokens bare. The description compensates by explaining what file_urls actually does (media the model reads, per-model capability) and pointing at list_models for valid model ids, adding real semantics over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (generate text) plus the concrete mechanism (AI Gateway language models) with an example model id. It is immediately distinguishable from siblings such as generate_image, generate_speech, and transcribe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to list_models for model discovery and explains the file_urls branch (use it when the model must read media). It does not state exclusions against siblings, but the text-generation scope is unambiguous from the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.