Agent Data Tools: AI text and media

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

Goes well past the annotations (readOnly/openWorld/non-idempotent) to disclose pricing ($0.01/call, failed calls free), payment paths (x402 USDC or card key), a legal restriction on storing/resale/training, and the failure mode ('Says so when the sources do not answer it'). The non-idempotent, charged-per-call economics are surfaced explicitly, which is exactly the context annotations cannot carry.

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 capability and output format before terms and pricing, and nearly every clause carries decision-relevant information. Minor redundancy: 'each call is charged, so repeats are not free' restates the earlier price line and the readOnly safety claim is largely covered by the annotations.

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?

With no output schema, the description carries the full return-value burden and does: citations format, source list contents, and the negative case when sources are insufficient. Cost, licensing, and safety are all present — an agent has everything needed to call it correctly.

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 100% and the single parameter already documents the 400-character limit, so the schema does the heavy lifting. The description adds only an example question string, which illustrates shape but not semantics beyond 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 ('Answer a question from the live web') and enumerates the internal pipeline (Brave search, top pages read, Llama 4 Scout synthesis) plus the output shape (inline [n] citations, source list). Clearly separable from siblings that return raw text or raw search results.

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?

'Use when an agent needs a current, sourced answer rather than raw search results' gives an explicit selection rule, and the worked example (q=What is the x402 payment protocol?) anchors it. It stops short of naming specific sibling alternatives such as ai_fact_check or ai_chat, so an agent must infer the boundary itself.

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

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

Adds real context beyond the annotations: cost ($0.002/call, first 25 free, failed calls free), that repeats are charged — which explains the idempotentHint=false annotation — and that it reads/computes only. It stops short of describing the response shape or latency, but the pricing and charge semantics are the non-obvious behaviors an agent needs.

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 capability, then routing, then pricing, in a tight paragraph. It is dense but nearly every clause carries distinct information; the pricing clause is slightly run-on but earns its space given the non-idempotent billing behavior.

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 an 8-parameter, no-output-schema tool, the description covers model identity, limits, alternatives, cost and side-effect profile. The only real gap is what a successful call returns (answer string plus optional tool_calls) when tools/messages params are used.

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 100% and each of the 8 parameters is documented in-schema with limits and defaults. The description only restates the system prompt, token cap and temperature, adding no syntactic or interaction detail beyond the schema, so the baseline 3 applies.

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 ('Send a prompt, get an answer') with the exact backing model named, plus its size characteristics. It distinguishes itself from ai_chat_large and generic /v1/chat/completions endpoints in the same breath, so an agent can select it without opening any schema.

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?

Explicit when-to-use list (drafting, reasoning steps, Q&A, quick LLM calls without a provider account) and explicit routing to alternatives: harder reasoning → ai_chat_large, other open models → /v1/chat/completions. Includes a concrete example invocation.

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

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

Annotations already cover safety (readOnly, non-destructive, openWorld, non-idempotent), and the description adds the economically critical context they cannot: $0.01 per call via x402 USDC or card key, failed calls free, and that repeated identical calls are still billed. That cost-on-repeat disclosure is exactly the kind of behavioral fact that changes agent strategy.

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?

Model choice, cost and usage guidance are front-loaded in a compact block, and almost every clause earns its place. Minor bloat from the redundant 'Same call as /ai/chat with a stronger model' repetition and a stray double period in the example.

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?

With no output schema, the description covers models, limits, price and the read-only nature of the operation, which is what an agent needs before calling. It stops short of describing the response shape (e.g. whether raw text or a JSON envelope with usage/cost is returned), a small gap for a text-generation endpoint.

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 description coverage is 100%, so all five parameters are already documented in structured fields. The description restates the optional system prompt, the 1,024 output-token ceiling and adjustable temperature, and adds only the useful nugget that llama-3.3-70b is the default model. That meets the baseline but does not meaningfully exceed 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?

The description opens with a concrete verb and resource (send a prompt, get an answer) and names the exact backing models including the default. It explicitly positions itself against the sibling ai_chat as the same call with a stronger model, so an agent can distinguish the two without opening either schema.

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?

It states the selection condition clearly: use when the 8B model is not enough, for reasoning, drafting and Q&A, and names ai_chat as the alternative for lighter work. A worked example (prompt=Explain x402 in one sentence) anchors the expected input shape.

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

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

Annotations already declare readOnly, non-idempotent, open-world, non-destructive, so the bar is lower; the description goes further by disclosing cost ($0.01/call), the free tier (first 25, failed calls free), and the payment paths (x402 USDC or card key /credits). 'Each call is charged, so repeats are not free' usefully explains the non-idempotent hint. 'Reads or computes only and changes nothing' repeats readOnlyHint rather than adding, but does not contradict it.

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 capability and input/output shape in the first sentence, with secondary use cases and billing in the second. The pricing sentence is dense but earns its place because cost drives re-call behavior; nothing is filler.

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 simple two-parameter tool with no output schema, the description covers what comes back (best label, reason, ranking), the cost model, and the side-effect profile. An agent has enough to decide whether to call it and what to expect in the response.

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 description coverage is 100% and both parameters are documented there, so the schema carries the semantics. The description restates the 2-20 label constraint, but adds no syntax detail (e.g. how commas inside labels are handled) or guidance on label design beyond what the schema already says.

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?

The description states a specific operation with its input shape (text plus 2-20 candidate labels) and output shape (best label, reason, ranking), which is far more than the title restated. It is implicitly distinguishable from siblings like ai_sentiment or ai_moderation because the caller supplies arbitrary labels, though no sibling is named explicitly.

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?

Concrete use cases are given: routing tickets, tagging content, intent detection, moderation queues. There is no explicit exclusion or comparison to overlapping siblings (ai_sentiment for polarity, ai_moderation for policy checks), so the agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes further by disclosing cost ($0.01/call), the free tier (first 25), that failed calls are free, and that repeats are billed — directly explaining the otherwise puzzling idempotentHint=false. It also states explicitly that nothing is modified, matching the annotations rather than contradicting them.

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?

Output spec is front-loaded, followed by use cases and then pricing/commercial terms, with no filler sentences. The pricing clause is dense with numbers but every element (price, free allowance, failure policy) affects whether an agent should call it.

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?

There is no output schema, and the description fully specifies the return artifact (1,024-dim vector), input limit, model, multilingual scope, cost model, and side-effect profile. An agent has everything needed to decide and to call correctly.

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?

With one parameter and 100% schema coverage, the schema already documents the field and its 4,000-character limit, so the baseline is 3. The description adds value with a worked example showing the parameter takes raw content to embed (not an instruction or query), which disambiguates how to populate it.

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?

The description states exactly what is produced (a 1,024-dimension vector from BAAI BGE-M3, up to 4,000 characters, 100+ languages), which is specific enough to distinguish it from sibling generation tools like ai_chat or ai_summarize_text. It conveys the resource and output shape rather than restating the name, though the operative verb ('embed') is left implicit.

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?

It gives concrete intended uses (semantic search, RAG retrieval, clustering, deduplication), which tells an agent when this tool is appropriate rather than ai_rerank or ai_classify. It stops short of explicit exclusions or naming the nearest alternative for near-duplicate tasks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, but the description adds genuinely new context: per-call pricing ($0.01 via x402 USDC or card key), the first-25-free allowance, that failed calls are free, and the practical consequence that repeats are not free. That explains the non-idempotent billing behavior in a way the annotations cannot. It still omits rate limits and output/response specifics.

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?

The capability, dimension, model and length limit are front-loaded, followed by use cases, an example, then pricing. A few phrases are redundant with the annotations ('Reads or computes only and changes nothing'), and the commercial details take more space than the technical guidance, but nothing is unparseable.

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?

With no output schema, the description correctly tells the agent what comes back: a 1,024-dimension vector. Pricing and safety are covered too. What is missing is practical invocation detail such as whether the vector is normalized or the response envelope, which matters for a RAG consumer building on it.

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 description coverage is 100% for the single 'text' parameter, so the schema already documents the character limit. The description adds little parameter-level meaning beyond restating 4,000 characters and noting 100+ language support, which is baseline for a one-parameter tool with a fully documented 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?

The description states a specific verb and resource (text embeddings, 1,024-dimension vector for up to 4,000 characters, BAAI BGE-M3, 100+ languages) and lists concrete use cases. It does not, however, differentiate itself from the sibling 'ai_embed' or explain how it differs from 'ai_rerank', so an agent must guess between two embedding-looking tools.

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?

It gives clear when-to-use contexts (semantic search, RAG retrieval, clustering, deduplication, similarity scoring) plus a worked example with a sample text value. There is no explicit exclusion or routing guidance relative to 'ai_embed', so the boundary with that sibling remains ambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, but the description adds meaningful context beyond them: per-call pricing ($0.01/call via x402 USDC or card key), first 25 free, failed calls free, and the fact that repeats are charged. It also states output behavior—null for missing fields—which is important for an extraction tool.

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?

The purpose is front-loaded in the first sentence, followed by usage, then pricing/safety information. Every sentence adds something useful, though the pricing/safety sentence is slightly dense and could be split for readability.

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 simple two-parameter extraction tool with no output schema, the description covers purpose, output shape, billing model, and safety profile. Combined with a fully described input schema and informative annotations, an agent has everything needed to decide when and how to call it.

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 100%, so the two parameters (text and fields) are fully documented in the schema with character limits and field-count constraints. The description only implies 'named fields' and does not add syntax or format details beyond what the schema already provides; baseline 3 is appropriate.

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 ('pull named fields out of unstructured text') and the return shape (JSON object with null for missing fields). This is clearly distinguishable from sibling tools like ai_classify, ai_summarize_text, or ai_answer, which transform text in other ways rather than extracting named fields.

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?

Gives a clear usage statement: 'Use to turn messy text into structured data for an agent,' with example source types (emails, invoices, listings, bios). It does not explicitly name alternative tools or exclusions (e.g., use ai_classify for categories), so it stops short of a 5.

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

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

With annotations present, the description still adds substantial context: pricing ($0.01/call via x402 USDC or card key), failed calls free, repeated calls charged (consistent with idempotentHint=false), and Brave API terms restricting reuse of results. It also discloses the verdict vocabulary and the output shape (explanation, [n] citations, sources).

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 what the tool does and returns, then caveats, then use case, then pricing. Dense but nearly every sentence carries operational information; the price/payment sentence is long but justified for an agent deciding whether to call.

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?

There is no output schema, and the description compensates by describing the return: a verdict from a fixed set (supported, contradicted, mixed, unverified), a short explanation, numbered citations, and the sources. Nothing an agent needs to decide or interpret the call is missing.

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 100% and there is only one parameter, so baseline is 3. The description adds an example claim ('The x402 protocol uses the HTTP 402 Payment Required status code.') that shows the expected granularity, going slightly beyond the schema's length constraint.

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 and resource (check a claim against the live web) and spells out the pipeline (Brave search, page reads, Llama 4 Scout verdict). No sibling tool in the list does fact verification, and the description makes that unique role obvious.

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?

Gives a concrete trigger: 'Use to screen a statement before an agent repeats or acts on it.' It also sets expectations with 'A model's reading of a few search results, not an editorial fact-check.' It doesn't name an alternative tool for cases where a plain answer (ai_answer) would suffice, so it stops short of explicit alternative routing.

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

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

Annotations already cover read-only, non-destructive, non-idempotent, and open-world behavior, but the description adds meaningful context about pricing, the free quota, failed-call billing, and repeat charges. It also restates read-only behavior, though without contradicting the annotations.

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?

The description is a single front-loaded paragraph with no irrelevant sections. The pricing and billing sentence is dense but still earns its place by clarifying cost behavior.

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 two-parameter tool with full schema coverage and no output schema, the description supplies purpose, return ordering, use cases, and billing details. Nothing critical for correct invocation appears to be missing.

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 description coverage is 100%, so both parameters are already well documented in the schema. The description does not add parameter-level meaning beyond the schema; 'most relevant first' describes return ordering rather than input semantics.

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?

The description states the extracted resource (keywords and key phrases) and its ordering (most relevant first), and the title adds the explicit extraction verb. It does not clearly distinguish this tool from nearby siblings such as ai_extract_json or ai_summarize_text.

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?

It gives useful use cases (tagging, SEO, search indexing, topic detection) but does not say when to choose this over alternatives or when not to use it. Usage is implied rather than explicitly routed.

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

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

Beyond the annotations (readOnly=true, openWorld=true, destructive=false), the description discloses pricing ($0.01/call via x402 USDC or card key), that failed calls are free, that repeat calls are charged, the 2,048 output-token ceiling, and that reasoning traces are stripped from the answer. That is exactly the extra context annotations cannot carry, and it is consistent with readOnlyHint.

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?

The model identity, access paths, cost and behavior are front-loaded in a dense but readable block, and every clause carries information. It is slightly run-on (the stray double period after the example, the trailing clause about repeats) but not padded.

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?

With no output schema, the description carries the return-value burden and does explain that the answer comes back without reasoning and is capped at 2,048 tokens, plus cost and payment paths. It does not describe the response envelope or error shapes, which is the remaining gap for a paid single-shot 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 description coverage is 100%, so prompt, system, maxTokens and temperature are already documented with limits and defaults. The description restates the prompt/system pairing and the output-token cap but adds no format or interaction detail (e.g., how temperature affects reasoning), so baseline 3 applies.

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?

The description names a specific verb ('Chat with') and a specific resource — DeepSeek R1 distilled into Qwen 32B — and explicitly separates it from generic siblings like ai_chat by saying 'Use when an agent wants this model by name.' It also names the equivalent API route ("deepseek-r1" on /v1/chat/completions), so the model identity is unambiguous.

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?

It gives a clear selection rule ('Use when an agent wants this model by name') and a concrete example call, which implicitly routes generic chat needs to the non-model-specific siblings. It doesn't explicitly name ai_chat as the fallback or state when not to use it, so it stops short of full alternative routing.

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

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

Goes well past the annotations: discloses per-call price ($0.01), payment rails (x402 USDC or card key), that failed calls are free, that repeats are charged and non-idempotent, and that no account/provider key is needed. That is exactly the cost/auth/failure context annotations cannot convey.

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-loads model identity and the core action, then layers pricing and payment detail efficiently. It is dense but nearly every clause carries information; minor noise like the stray double period in the example slightly hurts polish.

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?

With no output schema, the description does say what comes back (the answer, capped at 1,024 output tokens) and covers cost, auth, and failure handling for a paid external call. An agent has enough to invoke it correctly, though the response envelope shape is only loosely implied.

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 description coverage is 100%, so all four parameters (prompt, system, maxTokens, temperature) are already documented with limits and defaults. The description only restates the 1,024-token output cap and the optional system prompt, adding essentially nothing beyond the schema; baseline 3 applies.

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 (chat) and resource (OpenAI's open-weight gpt-oss-120b reasoning model), and pins the exact model name, which is the key differentiator against siblings like ai_model_gpt_oss_20b. It never explicitly contrasts itself with those siblings, so the differentiation is implicit rather than stated.

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?

"Use when an agent wants this model by name" plus a concrete example gives clear selection context, and the OpenAI-compatible endpoint note helps agents routing by model string. It stops short of naming alternatives (e.g., when to pick gpt_oss_20b or ai_chat instead), so there are no explicit exclusions.

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

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

Annotations already declare readOnly/openWorld/non-idempotent, and the description goes well beyond them: exact price ($0.002/call via x402 USDC or card key /credits), failed calls are free, each call is charged so retries cost money, no account or provider key required, and the 1,024 output-token ceiling. That is precisely the cost/auth/retry context an agent needs before invoking.

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-loads the model identity and access method, then pricing and safety in a tight sequence; nearly every sentence earns its place. Minor blemishes: the example 'prompt=Explain x402 in one sentence..' has a doubled period and is marginally decorative.

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 four-parameter chat tool with no output schema, the description covers what comes back (the answer, capped at 1,024 tokens), how to pay, that no key is needed, and that calls are billed individually. Nothing an agent needs to call it correctly is missing.

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 description coverage is 100%, so prompt, system, maxTokens and temperature are already documented with ranges and defaults. The description restates prompt/system and the token cap and adds a worked example, but adds no format or interaction semantics beyond the schema — baseline 3 applies.

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 (chat with OpenAI's gpt-oss-20b reasoning model) plus the access path (one paid HTTP call, or the OpenAI-compatible /v1/chat/completions as model "gpt-oss-20b"). It explicitly distinguishes itself from the generic ai_chat and from its size sibling gpt_oss_120b by naming the exact model and telling the agent to use it 'when an agent wants this model by name.'

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?

'Use when an agent wants this model by name' gives a clear selection condition versus the generic chat siblings, and the price note hints at cost trade-offs. It stops short of explicitly naming an alternative for when cost or the larger 120B model matters, so no exclusion is spelled out.

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

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

Adds substantial context the annotations cannot carry: price ($0.005/call), failed calls free, payment paths (x402 USDC or card key /credits), no account or provider key required, and the 1,024 output-token cap. The "reads or computes only and changes nothing" statement is consistent with readOnlyHint=true, and "repeats are not free" aligns with idempotentHint=false.

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 model identity and payment model, which are the deciding facts. Slightly run-on and marred by a doubled period in the example, but nearly every sentence carries distinct information.

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 4-parameter stateless chat tool with no output schema, the description covers cost, limits, auth, and the alternate endpoint, so an agent can call it correctly. The response format (plain answer text) is only implied by "get the answer."

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 100%, so the schema already defines prompt, system, maxTokens, and temperature with ranges and defaults. The description only echoes the prompt/system pair and the output token cap, adding no syntax or format detail beyond structured data — baseline 3 applies.

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 (chat with) plus the exact resource: Mistral Small 3.1 24B, with license and OpenAI-compatible alias. This makes it trivially distinguishable from sibling model tools like ai_model_qwen3_30b or ai_model_deepseek_r1.

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?

"Use when an agent wants this model by name" gives an explicit selection condition, and the /v1/chat/completions alias offers an alternative access path. It does not compare against the other ai_model_* siblings, so an agent choosing between models gets no comparative guidance.

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

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

Beyond the annotations, the description discloses pricing ($0.002/call), billing paths (x402 USDC or card key via /credits), that failed calls are free, that repeats cost money, that no account or provider key is needed, and that reasoning traces are stripped from the output. That is exactly the extra context annotations cannot express.

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 model identity and call shape, then cost and access details. It is a dense run-on with a slightly awkward example fragment ("Example: prompt=Explain x402 in one sentence.."), but nearly every clause carries useful information.

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 single-call inference tool with no output schema, the description covers cost, auth alternatives, output limits, what the response omits (reasoning), and side-effect-free behavior. An agent has everything needed to decide to call it and predict the charge.

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 100%, so the schema already documents prompt length, system prompt, maxTokens range/default, and temperature range. The description adds only the 1,024 output-token cap and an example prompt, which duplicates the schema's maxTokens note without adding format or tradeoff guidance (e.g. how temperature affects this model).

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?

The description names a specific verb (chat), a specific model (Alibaba Qwen3 30B-A3B MoE, Apache 2.0), and the exchange shape (send prompt + optional system prompt, get answer). This sharply distinguishes it from siblings like ai_model_gpt_oss_120b or ai_model_mistral_small that share the same pattern.

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?

"Use when an agent wants this model by name" gives an explicit selection rule against the other ai_model_* siblings, and the OpenAI-compatible alias note clarifies an alternate route. It stops short of saying when to prefer a sibling like ai_chat_large instead, but the routing intent is clear.

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

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

Beyond annotations, it discloses pricing ($0.005/call), payment paths (x402 USDC or card key), that failed calls are free, that repeats are charged, and that the tool only reads/computes and changes nothing. It also notes no account or provider key is required and that output is capped at 1,024 tokens.

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?

The description is front-loaded with the model identity and core action, and most sentences carry useful pricing or behavior context. It is slightly dense and includes minor redundancy around the token limit, but no major 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 paid, no-auth LLM call tool, the description covers identity, cost, payment, limits, safety profile, and endpoint alternative. With complete schema coverage and annotations, an agent has enough to call it correctly; an output schema is unnecessary for a familiar chat-completion response.

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 description coverage is 100%, so all four parameters are already self-documenting with types, defaults, and limits. The description adds only a brief mention of prompt/system and an example prompt, without extra semantics for maxTokens or temperature beyond what the schema provides.

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?

The description states a specific verb and resource — chat with Alibaba's Qwen2.5 Coder 32B code model through a paid HTTP call — and explicitly identifies the model by name. It also distinguishes this tool from generic chat siblings by saying to use it when an agent wants this model specifically.

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?

It gives a clear usage condition: 'Use when an agent wants this model by name,' and notes the OpenAI-compatible endpoint alternative. It does not explicitly compare against sibling tools like ai_chat or ai_model_qwen3_30b, so it falls short of full when/when-not guidance.

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

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

Adds substantial context beyond the annotations: pricing ($0.002/call via x402 USDC or card key), the first 25 free, failed calls free, and the key insight that repeats are charged — which explains why idempotentHint is false. It also confirms the read-only, no-side-effects nature and the 8,000-character ceiling.

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 purpose and taxonomy, then usage, then pricing. The final sentence is dense but each clause (free tier, failed-call billing, non-idempotency) carries decision-relevant information.

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 one-parameter tool with no output schema, the description covers what comes back (safe/unsafe plus named hazard categories) and the cost model. Only the response envelope/format remains unspecified, a minor gap.

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 100% and the single parameter is already documented in the schema. The description's 'Up to 8,000 characters' and the example repeat rather than extend that, so baseline 3 applies.

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 and resource ('Classify a text as safe or unsafe with Meta's Llama Guard 3'), names the exact hazard taxonomy and its size, and is clearly separable from siblings like ai_classify or ai_sentiment. The example input pins down the expected call shape.

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?

Gives concrete contexts ('screen user messages, model outputs or content before an agent posts or acts on it') and points to the alternate OpenAI-shaped endpoint at /v1/moderations. No explicit exclusion versus ai_classify, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, yet the description still adds real context: pricing model, free-tier terms, and that failed calls are free. 'Each call is charged, so repeats are not free' usefully reinforces the idempotentHint=false annotation. It doesn't describe latency or output length limits, so not 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?

The core purpose and output format are front-loaded in the first sentence, followed by usage and an example. The pricing/key sentence is dense but earns its place by warning the agent that calls are billed and non-idempotent.

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 two-parameter generation tool with no output schema, the description covers what comes back (Markdown headings and bullets), what goes in, and the cost model. Only the depth parameter's effect on output shape is left unexplained.

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 100%, so both parameters are already fully documented. The description's example clarifies what the 'text' value looks like in practice but adds nothing about the 'depth' parameter (1-3 heading levels), leaving it to the schema. Baseline 3 is appropriate.

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 and output artifact ('structured Markdown outline of headings and bullet points') plus the two input modes: a supplied text or a topic. It does not explicitly differentiate from near-siblings like ai_summarize_text or ai_rewrite, so it stops short of a 5.

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?

Gives concrete use cases ('plan articles, reports, talks and documentation') and a worked example, which is clear usage context. It never says when not to use it or names an alternative tool for overlapping tasks such as summarizing.

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

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

Goes well beyond the annotations by disclosing truncation limits (2,000 chars per doc, 40,000 total), the 50-document cap, the return shape (index, score, text, best first), and pricing ($0.002/call, first 25 free, failed calls free). It also resolves the idempotentHint=false annotation with a concrete reason: 'each call is charged, so repeats are not free'.

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-loads the core operation and stays to a single dense paragraph with no filler. The pricing clause is long but earns its place because it explains the non-idempotent charging behavior; a slight tightening would push this to a 5.

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?

There is no output schema, yet the description fully documents the return payload and ordering, plus limits, cost and side-effect profile. For a 3-parameter tool of this complexity, an agent has everything needed to call it and interpret results.

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 100%, so baseline is 3; the description still adds real meaning by specifying per-document and total character truncation and the semantics of top_n ('keeps only the best'). The documents parameter's input encoding is already in the schema, so no further lift is needed.

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?

Opens with a specific verb+resource+metric: 'Order up to 50 documents by how well each answers a query, with a relevance score from 0 to 1', and names the underlying model (BAAI bge-reranker-base, a cross-encoder). This clearly separates it from sibling embedding/chat tools like ai_embed and ai_chat.

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 states the use case: 'Use to pick what a model reads after search or vector retrieval', and points to a Cohere-style alternative endpoint at /v1/rerank. It does not spell out when NOT to rerank or contrast against sibling tools such as ai_embed, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and idempotentHint=false; the description reinforces the non-idempotency with an operational reason ('each call is charged, so repeats are not free'). It also discloses cost, billing paths (x402 USDC or card key /credits), the 25-free allowance, and that failed calls are free — real behavioral context annotations cannot express. Return-format detail is the only gap, and no output schema exists.

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?

Purpose, styles, use cases, example, then cost/safety in one tight block — front-loaded and free of filler. The pricing and billing clauses are dense but each carries distinct decision-relevant information.

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 simple 2-parameter transformation tool with annotations covering the safety profile and no output schema, nothing needed to invoke it correctly is missing: input shape, example, meaning-preservation guarantee, cost, and repeat-call behavior are all present.

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 description coverage is 100% (both params documented, enum listed, default professional stated), so the schema already carries parameter meaning. The description only repeats the style list and gives one sample text value; it adds no syntax or edge-case guidance beyond the schema, so baseline 3 applies.

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 (rewrite) and resource (text) plus the full set of target styles, and adds the invariant 'keeping the meaning and language.' This distinguishes it cleanly from siblings like ai_summarize_text, ai_translate, and ai_chat.

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?

Gives concrete usage contexts ('polish emails, replies, product copy and messages') and a worked input example, so an agent knows when this is the right call. It does not name an alternative or an explicit when-not case (e.g. shortening vs summarizing), so it stops short of 5.

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

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

Annotations already cover read-only/destructive semantics, but the description adds what they cannot: per-call cost ($0.01 via x402 USDC or card key), the 25-call free tier, failed calls free, and an explicit reason why idempotentHint=false matters ("each call is charged, so repeats are not free"). That cost-and-repeat guidance is decision-relevant information an agent would otherwise have to discover by spending money.

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?

Purpose is front-loaded, followed by use cases, example, pricing, and safety note — a sensible order. Minor blemishes: a doubled period in the example ("within minutes..") and a dense pricing clause that packs several facts into one sentence.

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?

With one parameter, no output schema, and annotations already declaring safety, the description covers language, cost, and side-effect profile; the return value is sketched (label + confidence). It could be slightly more explicit about the exact response shape, but nothing needed to call it correctly is missing.

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 100% and the single `text` parameter is already documented with its 4,000-character limit. The description reinforces the English-only constraint and supplies an example value, but adds no syntax or formatting detail beyond the schema — baseline 3 is appropriate.

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 and resource — predicts positive/negative sentiment of English text with a confidence score — plus the underlying model (DistilBERT fine-tuned on SST-2). An agent can immediately distinguish it from generic siblings like ai_classify or ai_moderation because the output is a fixed two-way label with a score.

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?

"Use to triage reviews, support messages, social posts and replies" gives concrete when-to-use scenarios. It stops short of naming alternatives or exclusions — e.g. that non-English input should be routed through ai_translate first, or that multi-label taxonomy work belongs to ai_classify.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false; the description reinforces this with "Reads or computes only and changes nothing" and explains that repeats are not free because each call is charged. It also adds auth and cost detail absent from the annotations (x402 USDC or card key at /credits, $0.01/call, first 25 free, failed calls free), which is genuinely useful for planning. It leaves out rate limits, behaviour on non-English input, and error handling.

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?

The core capability and model are front-loaded, then usage contexts, then pricing/auth, so the important information comes first. It is dense but almost every clause carries signal; the inline example is slightly clumsy (double period, literal `text=` fragment) and could be dropped without loss.

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 single-parameter, non-mutating inference tool with a fully documented schema, the description covers purpose, model, language, return shape, cost and auth. Missing details are secondary: confidence-score range, handling of inputs near or over the 4,000-character limit, and error behaviour.

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?

Only one parameter exists and schema description coverage is 100% ("English text, up to 4,000 characters"), so the baseline is 3. The description echoes the English constraint and supplies a sample text value, but adds no format, length, or input-validation nuance beyond 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 concrete verb and resource ("Sentiment analysis of text"), the exact output shape (positive or negative with a confidence score), the underlying model (DistilBERT fine-tuned on SST-2) and the language scope (English). It is far more specific than a restated title, but it never distinguishes itself from the sibling tool `ai_sentiment`, which appears to overlap entirely.

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?

Gives concrete use cases — reviews, support tickets, social posts, headlines, replies at scale, or as the scoring step of a monitoring agent — which tells an agent the intended context. It stops short of exclusions and does not tell the caller when to pick `ai_classify` or `ai_sentiment` instead.

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

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

Goes well beyond the annotations by disclosing the billing model ($0.01/call via x402 USDC or card key, failed calls free) and warning that repeats are not free, which explains the idempotentHint=false signal. It also confirms the read-only, side-effect-free nature and names the exact output format.

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?

The capability, limits, and cost are front-loaded in a tight three-sentence block with no filler, and the example is compact. The final sentence runs long by chaining side-effect, billing, and retry caveats together, but each clause carries information.

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 simple three-parameter tool with no output schema, the description covers input constraints, output format (MP3 base64), pricing, and safety. Minor gaps remain around response size limits and error behavior beyond 'failed calls free'.

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 100% and the schema already enumerates every language and voice name plus defaults, so the description only restates the 300-character limit and the 'pick a voice by name or leave the default' behavior. It adds no usage nuance (e.g. when to prefer one voice or language) beyond the structured data.

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 concrete verb and resource ('turn text into natural, human-sounding speech as an MP3 (base64)') and pins down the provider, languages, voice counts, and character limit. An agent can immediately tell this is the text-to-speech tool rather than a transcription or chat sibling.

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?

Gives explicit positive use cases (voice replies, narration, audio notes, accessibility, phone/chat bots) and an inline example call. It never states when not to use it or names an alternative such as transcribe for the reverse direction, so routing against siblings is left to inference.

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

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

Annotations already declare readOnly/destructive/idempotent, and the description adds genuinely new context beyond them: the 12,000-character ceiling, pricing ($0.01/call via x402 USDC or card key), 25 free calls, and that failed calls are free. The note that "each call is charged, so repeats are not free" usefully reinforces idempotentHint=false in operational terms.

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?

Two dense sentences that lead with what the tool does and what you get back, then pack limits, alternatives, and billing. The billing clause is somewhat crammed with semicolons, but each clause carries usable information for an agent deciding whether to call.

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 2-parameter tool with no output schema, the description covers return shape, input size limit, cost, and use cases. Minor gaps remain: it doesn't say whether oversized text is rejected or truncated, and doesn't clarify the overlap with ai_summarize_text.

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 description coverage is 100%, so the schema already documents both parameters including the 1-8 sentence range and default. The description repeats the 12,000-character limit (already in the schema) and never mentions the `sentences` parameter, so it adds no meaning beyond the structured data.

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 and resource ("Summarize text with an LLM") plus the exact output shape: "a short summary plus bullet key points." The alternative routing sentence refers to an HTTP endpoint "/summarize" rather than the sibling tool name ai_summarize_text, which leaves the differentiation slightly ambiguous even though the intent (URL input goes elsewhere) is clear.

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?

Gives concrete positive use cases ("long emails, articles, transcripts, meeting notes and tool outputs") and an explicit exclusion for web pages by URL. It does not address the obvious sibling ai_summarize_text, which appears to overlap heavily, so the when-not guidance is incomplete against the sibling list.

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

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

Annotations already indicate read-only, non-destructive, non-idempotent, open-world behavior, but the description adds critical operational details: cost per call, free failed calls, first 25 calls free, and that repeats are not free because each call is charged. It also reinforces that the tool only reads/computes and changes nothing.

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?

The description is front-loaded with purpose and usage, then adds pricing and safety context efficiently. It is slightly dense but every sentence is relevant to an agent deciding whether and how to call the tool.

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?

With no output schema, the description supplies the return shape (a few sentences plus bullet key points), usage boundaries, input limit, and cost/auth behavior. An agent has enough context to call it correctly and understand the main operational constraints.

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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description restates the 12,000-character input limit but does not add meaning beyond the schema for the sentences parameter.

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?

The description states a specific verb and resource: summarize up to 12,000 characters of supplied text into a few sentences plus bullet key points. It also distinguishes the URL case by directing agents to /summarize, making the tool's scope clear.

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?

It names concrete use cases (long emails, documents, transcripts, tool outputs) and explicitly routes web-page-by-URL work to the /summarize alternative. This is clear when-to-use guidance rather than implied context.

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

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

Well beyond the annotations: it discloses pricing ($0.01/call, first 25 free, failures free), the billing mechanism (x402 USDC or card key), the sentence-splitting behavior, and that a truncated result surfaces as an uncharged 502 rather than a false success. The 'repeats are not free' note is consistent with idempotentHint=false, and 'changes nothing' matches readOnlyHint=true.

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 capability and constraints, and every sentence carries information an agent can act on. It is dense to the point of being slightly overcrowded (pricing, payment rails, and failure semantics packed into one string), and 'Reads or computes only and changes nothing' largely restates the annotations.

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 3-parameter, no-output-schema tool with readOnly/openWorld annotations, the description covers limits, cost, failure behavior, and language codes thoroughly. The one gap is the return shape — with no output schema, it never says whether the response includes the detected source language alongside the translation.

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 100%, so the baseline is 3; the description adds real value by specifying ISO codes (en, sv, de, fr, es, zh, ja) and noting that uncommon languages fall back to Meta's M2M100. It also confirms source-language detection for the optional 'from' parameter, though it doesn't explain behavior when 'from' is supplied explicitly.

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?

The first sentence states a specific verb and resource ('Translate text into another language') plus the underlying model and automatic source detection. It is clearly distinguishable from sibling tools like ai_rewrite, ai_summarize_text, or the ai_model_* single-model endpoints.

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?

'Use to localise messages and documents' plus a concrete example (text=Payment received, to=sv) gives a clear use context. It stops short of naming when to prefer a sibling (e.g. ai_model_gpt_oss_20b for a free-form prompt) or any exclusion, so it is clear guidance without explicit alternatives.

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

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

Beyond the annotations it discloses billing ($0.01/call via x402 USDC or card key, first 25 free, failed calls free), that repeats are charged (consistent with idempotentHint=false), and the long-text handling that splits at sentence ends and verifies so a cut-off translation is never charged. These are exactly the cost and correctness traits an agent cannot get from structured fields.

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?

It is a single front-loaded paragraph that leads with the operation, then use cases, then cost. The parenthetical model names and pricing clauses make it dense, but each clause carries information an agent would otherwise lack.

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?

With no output schema and three simple parameters, the description covers cost, detection, input limits and long-text handling, which is nearly everything needed to call it correctly. It never states what the response contains (translated text, detected source language), which is the one remaining gap.

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 100%, so the schema already documents all three parameters; the description mainly restates that the target is an ISO code with a longer example list (en, sv, de, fr, es, zh, ja) and that the source is auto-detected. That adds marginal meaning but no format or validation detail beyond 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?

The description opens with a specific verb+resource ('Translate text between languages') and names the underlying models and detection behavior, so the agent knows exactly what the call does. It does not differentiate itself from the sibling ai_translate, which leaves ambiguity between two similarly named tools.

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?

It gives concrete when-to-use context ('localise messages, documents, product copy and support replies') plus a worked example (text=Payment received, to=sv), which is clear guidance. There are no exclusions or pointers to alternatives such as ai_translate, so routing between the two translation tools is left to inference.

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

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

Goes well past the annotations by disclosing the billing model (USD 0.01 per call, failed calls free), the practical consequence that retries are not free, and the exact return encoding (MP3 base64). That pricing detail also explains behaviorally why idempotentHint is false, which the annotation alone does not convey.

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 capability, then use cases, then example, then cost — a sensible order with little wasted text. Minor redundancy: 'Reads or computes only and changes nothing' repeats readOnlyHint/destructiveHint, and the voice counts partially duplicate the enum listing.

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?

With no output schema, the description still specifies the output shape (MP3 base64), the length limit, language/voice choice and defaults, and the cost model — everything needed to call it correctly and predict the result.

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 description coverage is 100%, including the full voice enum list and defaults, so the schema already carries most parameter meaning. The description adds only light framing: 40 English and 10 Spanish voices and 'pick a voice by name or keep the default,' which restates rather than extends 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?

Names a specific verb and resource (text to speech, text into MP3 base64 audio), the provider and model family (Deepgram Aura-2), the supported languages and voice counts, and the 300-character cap. An agent knows exactly what it gets back without opening the schema.

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?

Concrete use cases are listed (voice replies, narration, audio notes, IVR prompts, accessibility) plus a worked example call. It stops short of naming when NOT to use it or routing away from a sibling (e.g. ai_speech, transcribe), so the boundary with the rest of the ai_* family is left implicit.

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

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

Annotations already declare readOnly, openWorld and non-idempotent, and the description adds real context beyond them: $0.01 per call via x402 USDC or a card key, failed calls free, and an explicit warning that repeats are not free. It also documents accepted formats and the 3 MB cap, which is exactly the kind of operational detail an agent needs before spending money.

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 capability, then a compact run of facts about formats, use cases, pricing and safety — every sentence carries information. It is dense but reads as a single deliberate block rather than filler.

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?

With no output schema, the description still explains what comes back: a detailed description including visible text, or an answer to the question. Combined with format limits, price, failure policy and the read-only guarantee, nothing needed to invoke it correctly is missing.

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 description coverage is 100%, and the schema already documents the URL format, size cap, 300-character question limit and the default behavior. The description adds only the framing that the default is a detailed description including visible text; useful but not meaningfully beyond the schema, so baseline 3 applies.

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?

The first sentence states a specific verb and resource — a vision model answering about an image at a public URL — and spells out the two modes (detailed description vs. a targeted question). This clearly separates it from the text-only ai_* siblings and from the opaque 'image' tool.

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?

Concrete use cases are enumerated (alt text, OCR-style screenshot reading, chart reading, content checks), which gives the agent solid selection signal. It does not explicitly say when to choose a sibling instead, e.g. transcribe or ai_answer, so it falls just short of a 5.

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

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

It goes far beyond the annotations by providing technical context: model name (FLUX.1), output format (1024x1024 JPEG base64), price ($0.03), processing time ('a few seconds'), and explicitly stating its read-only, non-mutating nature.

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?

The definition is highly structured, leading with the core function, providing constraints in the middle, and ending with operational context (cost/safety) efficiently.

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?

Since no output schema is provided, the description is remarkably complete, detailing the input constraints, output format, cost, and behavioral guarantees (no state change).

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?

While the schema is complete, the description provides crucial semantic context for the 'steps' parameter, clarifying the default value (4) and the acceptable range (1-8).

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?

The tool is explicitly defined as performing 'Text-to-image generation' using the FLUX.1 model, clearly differentiating it from the list of text and language model siblings.

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?

The description provides specific use cases (illustrations, thumbnails, avatars, social media) which helps the agent decide if this tool is appropriate for a given user intent compared to other utilities.

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

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

Beyond the annotations it discloses latency ('a few seconds'), return encoding (base64 JPEG), pricing ($0.03/call via x402 USDC or card key), that failed calls are free, and that repeats are charged — consistent with idempotentHint=false. The 'reads or computes only and changes nothing' line restates readOnlyHint, but the pricing and cost-on-repeat details are substantive additions an agent could not infer.

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?

The value proposition and output format are front-loaded and every sentence carries information (cost, latency, example). It is a single dense block, and the closing 'reads or computes only and changes nothing' partly duplicates the annotations, so a little trimming is possible.

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 two-parameter generation tool with no output schema, the description covers what comes back (base64 JPEG, 1024x1024), how long it takes, what it costs, and what prompts work well. An agent has everything needed to call it correctly and budget for it.

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 100%, so the baseline is 3; the description nonetheless adds meaning by explaining that `steps` buys 'more detail' and that the prompt is a free-text description, plus a concrete example. It does not resolve the mismatch between the schema's unbounded integer maximum and the stated 1-8 range, which would have been useful.

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?

The description names a specific verb and resource ('Generate an image from a text prompt'), the underlying model (FLUX.1 schnell), and the exact output (1024x1024 JPEG as base64). Nothing in the sibling list (ai_speech, ai_tts, ai_translate, ai_answer) could be confused with it.

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?

It gives concrete use cases ('illustrations, thumbnails, mockups, avatars, product shots and social media images inside an agent workflow') and a worked example prompt, so an agent knows the intended context. It stops short of stating when NOT to use it or naming an alternative sibling such as `image`, which leaves a small ambiguity.

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

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

Goes well beyond the annotations by disclosing cost ($0.002/call, first 25 free, failed calls free), billing paths (x402 USDC or card key/credits), approximate latency ('a couple of seconds'), and the practical meaning of non-idempotency — repeats are charged. The 'reads or computes only and changes nothing' line is consistent with readOnlyHint/destructiveHint=false and corroborates it rather than contradicting it.

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?

Purpose is front-loaded in the first clause, but the text is a dense semicolon-chained run-on mixing capability, pricing, auth, and cost semantics. The example 'prompt=Explain x402 in one sentence..' has a stray double period and contributes little, and the billing detail could be tightened.

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?

With no output schema and 8 parameters, the description still covers model identity, token limits, latency, cost, auth, and OpenAI endpoint compatibility, which implies the response shape. It never describes the returned payload (choices/message structure or how tool_calls come back), a minor omission for a generation tool.

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 description coverage is 100%, so every parameter (tools, messages, system, maxTokens, temperature, tool_choice, response_format) is already documented in the schema. The description only echoes that messages/tools/JSON mode exist and restates the 1,024-token cap; the lone example adds no parameter semantics. Baseline 3 applies.

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 and resource (send a prompt / messages array, get a chat completion), names the underlying model (Meta's Llama 4 Scout), the output cap (1,024 tokens), and the OpenAI-compatible endpoint. It does not, however, distinguish itself from close siblings such as ai_chat, ai_chat_large, or llm_inference, so the agent must infer which one to pick.

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 lists when to use it: drafting, summaries, classification, reasoning steps, 'any quick LLM call without an AI provider account,' plus a concrete prompt example. There are no exclusions and no named alternative for longer context or other models, which is the main gap given ~30 sibling AI tools.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=true, and idempotent=false; the description reinforces this with 'reads or computes only and changes nothing' and explains that repeats are billed, which explains the non-idempotent hint. It adds genuinely useful operational context absent from the annotations: $0.01/call via x402 USDC or a card key, failed calls free, no provider account needed, and the OpenAI-compatible route. It does not describe the response payload shape, which matters slightly since there is no output schema.

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?

The key facts (models, cost, when to use) are front-loaded and the whole thing is a single dense block, but there is redundancy: 'Reads or computes only and changes nothing' restates readOnlyHint, and the example 'prompt=Explain x402 in one sentence..' carries a stray double period and little illustrative value.

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 five-parameter, single-call inference tool with no output schema, the description covers model choice, cost, payment paths, length limits, and safety profile adequately. The main residual gap is the return value shape (plain text answer vs. structured chat completion), which is only implied by 'get an answer'.

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 100%, so all five parameters already carry descriptions and enum values for model. The description only echoes the token cap ('up to 1,024 output tokens') and the optional system prompt, adding no format or tuning guidance beyond the schema. Baseline 3 applies.

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?

The description states a concrete verb and resource ('LLM inference with a large open model') and names the two exact models (Llama 3.3 70B Instruct, gpt-oss-120b) plus the compatible endpoint. It does not differentiate itself from close siblings such as ai_model_gpt_oss_120b, ai_chat_large, or ai_model_deepseek_r1, which an agent could easily confuse it with.

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?

'Use when a small model is not enough: reasoning, drafting, analysis and Q&A inside an agent workflow' gives a clear selection condition relative to small-model tools. It stops short of naming the alternative tools or stating when not to use it (e.g., when a sibling pinned to one specific model is preferable).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds pricing ($0.01/call), payment methods (x402 USDC or card key), and reinforces that repeats are charged despite being read-only. This extra context about cost and idempotency is valuable beyond the annotations, though it could go further on failure behavior.

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?

The description is front-loaded with the core purpose and return values, followed by practical details. Every sentence contributes value, though the inclusion of pricing and payment methods makes it slightly dense for a simple transcription tool.

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?

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: purpose, return values, input constraints, use cases, pricing, and idempotency. An agent has everything needed to invoke it correctly.

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?

The input schema has 100% description coverage for the single 'url' parameter, specifying it must be an absolute http(s) URL up to 5 MB. The description adds a concrete example URL and lists accepted audio formats (MP3, WAV, M4A, OGG), which provides useful meaning beyond 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?

The description states a specific verb ('Transcribe speech') and resource ('audio file at a public URL') and names the underlying model (Whisper large-v3-turbo). It clearly distinguishes from siblings like ai_chat or ai_translate by focusing on audio transcription, though it doesn't explicitly name an alternative tool (e.g., ai_speech) for comparison.

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?

The description provides clear usage contexts ('voice notes, podcast clips, meeting snippets and voice messages') and defines accepted formats and size limits. However, it lacks explicit when-not-to-use guidance or named alternatives for related tasks.

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