Spoonacular

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

The description discloses key behavioral traits beyond the annotations: it probes LLMs, returns per-model scores with confidence/signals/raw_response plus a combined view. It notes that Anthropic calls require a BYO key and incur cost. No contradiction with annotations exists; annotations already mark it as read-only and idempotent.

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 concise, using three sentences to cover purpose, usage nuances (default model, API key), and return structure. Every sentence adds essential information without redundancy or fluff.

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 has 4 parameters (1 required) and no output schema, the description fully covers input semantics, optional parameters, and return format (per-model object + combined view). It also provides context for use cases, making it complete for an AI agent to understand and invoke 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%, so baseline is 3. The description adds value by explaining the default model (Workers AI) and that _apiKey enables Anthropic probing, which supplements the schema's existing parameter descriptions. This extra context improves understanding beyond the schema alone.

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 clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. This specific verb+resource combination distinguishes it from sibling tools like 'scan_competitor_ai_presence', which may have a different focus. The purpose 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?

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains when to use Anthropic (requires _apiKey) and the default model. However, it does not explicitly state when not to use this tool or compare it to alternatives among siblings.

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, openWorldHint, idempotentHint. The description adds context: routes questions to appropriate tools, returns structured answers with citation URIs, works on all tiers, and is a single fast call. Does not disclose potential limitations like source freshness or rate limits, but given the annotations, this is adequate.

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 most critical instruction, then expands with details, comparisons, and examples. Every sentence is informative and earns its place. No redundancy or fluff.

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 complex tool with many sources and aliases, the description thoroughly covers its capabilities, usage context, and relationships with siblings. Although there is no output schema, the description explains the return format (structured answer with citation URIs), making it contextually complete.

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 adds value through examples but does not significantly elaborate on parameter semantics beyond what the schema provides (the 'question' parameter and its aliases). No additional constraints or formats are described.

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 clearly states the tool answers factual questions using structured data from 4,774 tools and 1,242 sources. It specifies that it should be preferred over web search and provides concrete examples, making the purpose unmistakable.

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?

Extensive guidance: explicitly says 'PREFER OVER WEB SEARCH', advises starting here for most questions, and details when to use alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad/multi-part questions). Includes example queries and contrasts with sibling 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral detail: it makes an extra LLM call, uses only tool results to extract answers, and explicitly lists refusal reasons (not_in_source, no_tool_match, etc.), covering failure modes beyond 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 front-loaded with the core concept ('Hallucination-resistant answer mode'), well-structured, and every sentence serves a purpose: stating the method, usage guidance, cost tradeoff, and return format.

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 complexity, the description fully covers the tool's behavior, return format (including refusal reasons), and context for use. No output schema exists, but the return structure is detailed in 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% with all aliases documented. The description only reiterates that aliases are accepted, which is already in the schema. No additional parameter meaning is provided.

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 clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from its sibling 'ask_pipeworx' by noting the extra LLM call cost and specific use cases.

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 advises use when answers will be quoted, cited, or acted on, and the agent must not invent facts (e.g., financial verdicts, legal claims). Also states to prefer 'ask_pipeworx' for casual lookups, providing clear when-to-use and when-not-to-use 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?

The description extensively details behavioral traits beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits, illiquidity warnings, resolution-rule risk parsing. Annotations (readOnly, idempotent) are complemented, not contradicted.

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 comprehensive but lengthy. It front-loads the core purpose and includes structured sections (classifiers, fan-out examples, response shapes, safety notes). Could be more concise, but the detail is justified by the tool's complexity.

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?

No output schema exists, so the description fully shoulders the burden of explaining return shapes. It covers result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Complete for an AI agent.

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%, but the description adds significant meaning: explains 'market' accepts slug, URL, or question text; 'depth' (quick vs thorough) and default; 'include_raw' describes summarized vs full payloads with size estimates. Examples in schema reinforce understanding.

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 clearly states the tool 'researches a Polymarket bet' by 'pulling relevant Pipeworx data'. It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). Distinguishes from sibling tools like polymarket_edges by focusing on holistic research.

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 use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, no explicit when-not-to-use or alternatives among siblings, though implied by context and extensive fan-out descriptions.

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 (readOnlyHint, idempotentHint, etc.), the description details the specific data sources and handling for each entity type (e.g., off-calendar fiscal years for companies, FAERS counts for drugs). It also notes results are sorted by primary metric. No contradiction with 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 relatively long but each sentence adds value, front-loading the core purpose with examples, then detailing data sources and behavior. It is structured logically but could be slightly more concise without losing clarity.

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 100% schema coverage and no output schema, the description adequately explains the return format (paired data + citation URIs), sorting behavior, and the types of data retrieved. It also notes the performance advantage over sequential lookups, providing complete context for tool selection and use.

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%, but the description adds substantial context: examples of proper values (e.g., 'AAPL','MSFT' for companies), clarifies min/max items, explains the enum choices for type, and describes what each type returns. This extends beyond the schema's basic descriptions.

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 clearly states it performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with specific examples like 'Compare X and Y' and 'X vs Y'. It distinguishes itself from sequential single-pack lookups and explains what data is pulled for each type (company: SEC EDGAR/XBRL financials; drug: FAERS, FDA, trial counts).

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive on when to use this tool. It also quantifies the benefit by stating it replaces 8-15 sequential lookups.

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, idempotentHint, and no destructive behavior. The description adds the 'using Spoonacular' context and an example, but does not disclose additional behavioral traits like rate limits or failure modes.

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 extremely concise: two sentences with no wasted words. The core purpose is front-loaded, and the example adds clarity 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?

For a simple conversion tool with an output schema, the description fully covers what the tool does, what it requires, and what it returns. No gaps are apparent.

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 0% schema description coverage, the description compensates by naming all required parameters and providing an example (1 cup flour -> 125 grams), which clarifies the meaning of ingredientName, sourceAmount, sourceUnit, and targetUnit.

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 clearly states the verb 'convert' and specifies the resource: a cooking measurement amount for a specific ingredient. It distinguishes itself from sibling tools which are mostly unrelated to unit conversion.

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 lists the required parameters and gives an example, implying when to use it. It does not explicitly state when not to use or mention alternatives, but the context is clear enough.

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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical context: account requirement (free vs paid), parallel decomposition, findings packet with gaps array, 15-60s response time, and that it never invents answers. No contradictions with 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?

Front-loaded with critical requirement (ACCOUNT REQUIRED) and alternative. Well-structured but somewhat verbose; every sentence adds value, though some details could be more terse. Still efficient for the complexity.

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 no output schema and high tool complexity, the description is remarkably complete: covers input semantics, account tiers, parallel processing, response format (findings with citations), gap handling, timing, and clear alternatives. No missing critical information.

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 covers both parameters (question, depth) with full descriptions; enum for depth mentions values. Description reinforces by explaining depth levels (quick=3, standard=5, thorough=8) and clarifies that broad questions are expected. Schema coverage is 100%, so description adds moderate value.

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?

Description clearly states the tool performs multi-source research across 1242 structured data sources, decomposing questions into facets and routing to tools in parallel. It distinguishes from ask_pipeworx (single lookup) and explicitly notes it is not open-web search.

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?

Provides explicit when-to-use (broad/multi-part structured data questions) and when-not-to-use (breaking/current news). Also includes account requirement and alternative (ask_pipeworx) if not signed in, covering prerequisites and fallback options.

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 idempotentHint=true. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond 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 fairly concise given the amount of information conveyed. It front-loads the purpose and then lists supported domains. Every sentence adds value, though it could be slightly shorter.

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?

Without an output schema, the description explains precisely what is returned (top-N tools with names, descriptions, and schemas). The parameter set is fully documented, and the scope is adequately covered for a discovery 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 the schema already documents all parameters. The description reinforces that 'query' is a natural language description, but does not add significant new 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 explicitly states 'Find tools by describing the data or task' and enumerates many specific use cases (SEC filings, financials, FDA drugs, etc.), clearly distinguishing it from sibling tools that perform specific actions rather than discovery.

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?

Directly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides explicit when-to-use guidance and implies it's for exploration, not direct data retrieval.

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 behavioral details beyond annotations: parallelism, soft-failure for patents (USPTO sunset), fallback chains, and return field structure. Annotations already indicate read-only, open-world, idempotent, non-destructive, so no contradictions.

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?

Description is detailed but well-structured with example queries up front and organized output list. Every sentence adds value, though length could be slightly reduced without losing content.

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?

No output schema exists, so description adequately explains return fields (CIK, filings, fundamentals, patents, news, LEI). Covers limitations, source details, and fallbacks, making it complete for a complex 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 covers 100% of parameters. Description adds context: type limited to 'company', value accepts ticker or CIK but not names, and cross-reference to resolve_entity. Enhances semantic understanding.

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 clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and outputs. It distinguishes from siblings like compare_entities and resolve_entity.

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 advises ALWAYS PREFER over chaining single-pack lookups for holistic views, and states names not supported—use resolve_entity first. Provides clear when-to-use and when-not-to-use 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 provide destructiveHint=true and idempotentHint=true. The description adds useful context about clearing sensitive data, but does not introduce new behavioral traits beyond what annotations 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?

Two sentences, front-loaded with purpose, no wasted words.

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 tool with good annotations, the description fully covers purpose, usage, and relationship to siblings.

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 description does not add meaning beyond the schema's parameter description. With 100% schema coverage, baseline is 3.

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 clearly states the verb 'Delete' and the resource 'a previously stored memory'. It also distinguishes from siblings by mentioning pairing with remember and recall.

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 when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with siblings for 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?

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds value by detailing the process: fetching the page, extracting content, and emitting llms.txt format, which informs the agent about network calls and output structure.

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 concise (4 sentences), front-loaded with the core action, and every sentence adds value. No redundant or vague phrases.

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 (2 params, no output schema, annotations covering safety), the description fully covers purpose, process, output, and use cases. An agent has sufficient context to select and invoke the tool 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 description coverage is 100%, so the schema already documents both parameters. The description does not add new meaning beyond what the schema provides, resulting in a baseline score of 3.

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 clearly states the verb 'Generate' and resource 'llms.txt file for any URL', and explains the process and output. It effectively distinguishes this tool from siblings like ai_visibility_check by focusing on file generation rather than visibility checking.

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 explicitly lists use cases (client site indexing, personal projects, competitor auditing), providing clear context for when to use. However, it does not mention when not to use or suggest sibling 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?

Annotations already indicate read-only and idempotent; description adds what data is returned (name, category, units, nutrition) and the role of amount/unit, enriching transparency.

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 sentences, front-loaded with purpose, then returns and prerequisite. No fluff or repetition.

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 output schema exists, description covers all needed context: purpose, parameters, return categories, and prerequisite. Complete for a fetch-by-id 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?

With 0% schema coverage, description explains that amount and unit are used for nutrition data, and id is numeric, adding necessary 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?

Description uses specific verb 'Fetch' and resource 'ingredient details', and distinguishes itself from sibling 'ingredient_search' by stating it returns details and that the id comes from search.

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 prerequisite (use ingredient_search first) and what it returns, but lacks explicit when-not-to-use or alternative tools beyond the prerequisite.

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 a read-only, idempotent, non-destructive operation, but the description adds no extra behavioral context (e.g., pagination, rate limits, or data source specifics) beyond what the annotations provide.

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?

While extremely short (2 words), the description is under-specified and does not convey useful information, making it an example of under-specification rather than efficient conciseness.

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 has 4 parameters with no descriptions, an output schema but no explanation, and a vague description, it fails to provide the necessary context for correct invocation.

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 0% schema description coverage and no parameter explanations in the description, the agent receives no guidance on how to use the 4 parameters (sort, query, number, intolerances) effectively.

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 'Ingredient search.' is essentially a tautology of the tool name, providing no additional detail about what the tool does or how it differs from sibling tools like product_search or recipe_search.

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?

No guidance is given on when to use this tool versus alternatives such as product_search or recipe_search, leaving the agent without context for appropriate 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 provide readOnlyHint, idempotentHint, and destructiveHint=false, so the description need not repeat safety. It adds value by detailing the return fields and clarifying that only active subscriptions are listed by default. A small gap is not explicitly mentioning the include_inactive parameter, but the schema covers that.

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 sentences: the first describes what the tool does and what it returns, the second provides usage context. No fluff, every sentence is informative and earns its place.

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 optional parameter, no output schema, annotations covering safety), the description is complete. It specifies return fields, default behavior, and usage context. No additional information is needed for an agent to use this tool 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 description coverage is 100% (the schema describes the include_inactive parameter). The description adds meaning by implying the default behavior (active only), which helps the agent understand the parameter's effect without reading 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 clearly states the verb 'List' and resource 'subscriptions', specifies the scope 'caller's active subscriptions', and lists return fields (id, type, params, etc.). The usage hint distinguishes it from sibling tools like subscribe and unsubscribe by saying 'review before adding more or to find an id to cancel'.

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 says when to use: 'before adding more or to find an id to cancel'. This provides clear context and differentiates from the sibling tools subscribe and unsubscribe, which are for creating and removing subscriptions.

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, idempotentHint=true, so the description adds marginal value. It states the output includes meals with recipe ids, titles, images, and nutrition summary, which is useful but does not cover other behavioral aspects like rate limits, idempotency guarantees, or any side effects. No contradictions with 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 sentence that efficiently covers the tool's purpose and key parameters. It is front-loaded with the main action. However, it could be slightly restructured to pair parameters with their intended role more clearly.

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 presence of an output schema (not shown), the description reasonably summarizes return fields. However, all 4 parameters are optional, which is not addressed; the description implies timeFrame is given but is not required. No mention of default values or behavior when parameters are omitted. This leaves gaps for an agent.

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 0%, but the description compensates well by explaining the purpose of each parameter: timeFrame (day or week), targetCalories, diet (with examples like vegetarian/vegan/paleo), and exclude (comma-separated). It provides examples in the schema but could be more explicit about allowed diet values and default behavior.

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 clearly states it generates a meal plan for a given timeFrame (day or week) with parameters like targetCalories, diet, exclude. However, it does not explicitly differentiate from the sibling 'meal_plan_week', which may serve a similar purpose. The verb 'generate' and resource 'Spoonacular meal plan' are specific.

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 no guidance on when to use this tool versus alternatives like 'meal_plan_week'. There is no mention of prerequisites, scenarios where it is best suited, or when to avoid it. The sibling list contains a similar-named tool, creating potential confusion without differentiation.

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?

The description says 'generate,' which could imply creation, but annotations indicate readOnlyHint=true, making it a safe read. The description adds no behavioral context beyond annotations (e.g., no mention of side effects, auth, or rate limits).

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 concise, fitting into one sentence that covers purpose and output. It is front-loaded but slightly run-on, yet no unnecessary words.

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 optional parameters, an output schema, and annotations, the description is adequate but lacks parameter details and sibling differentiation. It covers the basic purpose and return structure.

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 0% schema description coverage, the description only lists parameter names (targetCalories, diet, exclude) without explaining allowed values, formats, or constraints. No added meaning beyond the schema's property names.

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 clearly states the tool generates a 7-day meal plan with specific parameters (targetCalories, diet, exclude). It specifies the resource and verb, but does not differentiate from the sibling tool 'meal_plan_generate'.

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 gives the purpose and parameters but does not explicitly state when to use this tool versus alternatives like 'meal_plan_generate'. No exclusions or preconditions are mentioned.

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 (which are all false), the description discloses key behavioral traits: rate limit of 5 per identifier per day, free usage, that the team reads digests daily, and that feedback affects the roadmap. This provides valuable operational context without contradicting 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 concise and well-structured: a clear opening sentence, followed by usage guidance and behavioral notes. Every sentence adds value without redundancy. It is front-loaded with the main purpose and uses efficient language.

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 (no output schema, 3 parameters, 2 required), the description is complete. It covers purpose, when to use, behavioral details, and parameter semantics. No gaps remain for effective usage by an AI agent.

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%, but the description adds meaningful value beyond the schema: it rephrases the enum choices for 'type', gives concrete advice on message content (be specific, 1-2 sentences, 2000 chars max), and explains the 'context' parameter's purpose. This enhances understanding of parameter usage.

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 clearly states the tool's purpose: to send feedback to the Pipeworx team about bugs, feature requests, data gaps, or praise. It uses specific verbs (tell, broken, missing, needs to exist) and distinguishes itself from sibling tools, none of which serve a feedback function.

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 explicitly tells when to use the tool: for bugs, missing features, data gaps, or praise. It also provides guidance on what not to do (don't paste the end-user's prompt) and mentions rate limits and quota. This provides clear context for appropriate use.

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?

The description adds significant behavioral context beyond the annotations: it explains the data source ('derived from CF analytics-engine'), privacy (no PII), result structure ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This fully complements the annotations (readOnlyHint, openWorldHint, etc.) without contradiction.

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 concise and well-structured. It starts with a strong lead sentence, followed by a bullet-like list of use cases, and ends with technical details. Every sentence adds value, with no wasted words.

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?

Despite lacking an output schema, the description clearly states what the tool returns ('top tools, top packs, and total call volume'). It also covers caching, data source, and privacy. For a simple read-only aggregation tool, this is complete and leaves no essential questions unanswered.

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 single parameter 'window' has a schema description and enum, but the description adds valuable semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately, exceeding the schema's baseline.

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 clearly states the tool's purpose: returns trending data (top tools, packs, and call volume) based on what other AI agents are using. It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume'), and distinguishes from sibling tools by focusing on aggregate trends rather than specific queries.

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 three concrete use cases (discovering hot data sources, confirming canonical choice, aligning use cases). While it does not explicitly say when not to use it or name alternatives, the use cases are practical and guide the agent effectively.

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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context: scanning top markets, performing partition checks, semantic Jaccard filtering, partition placeholder filtering, and fill check against live order book (including realizable_edge_pp ≤ 0 meaning no trade). This exceeds the annotation scope and reveals important behavioral traits.

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 a one-line purpose and then explains modes and features. It is somewhat long but every sentence adds useful context (modes, semantic anchor, partition filter, fill check). Could tighten some technical details, but overall well-structured.

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 complexity and lack of output schema, the description adequately explains the response structure (opportunities[], partition_check, fill check details) and references polymarket_fill_risk for custom sizing. It does not cover error cases or empty results, but for a research tool with open-world dependency, it is complete enough.

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% with clear parameter descriptions. The tool description goes further by explaining what each mode does in detail, including recommended usage, algorithms (date-axis/threshold-axis ordering, partition_check), and the fill check. This adds significant value 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk. The verb 'Find' and resource 'arbitrage opportunities' are specific.

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 explicit guidance on when to use each argument: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It also notes using polymarket_fill_risk for custom sizing. However, it does not explicitly state when not to use this tool (e.g., lack of market data or no arbitrage likely), which would earn 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?

The description extensively covers behavioral traits: caching (1h at KV level), model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation, slippage, Kelly sizing, and diagnostics. This adds significant value beyond annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false) and no contradictions.

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 dense yet well-structured, with clear sections for purpose, model families, knobs, and response layout. Every sentence provides necessary detail without redundancy, making it effective despite length.

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 complexity, lack of output schema, and zero required parameters, the description thoroughly covers purpose, usage, parameters, response structure, diagnostics, and even caching. It is self-contained for an agent to understand and use 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?

All 9 parameters have schema descriptions, but the tool description adds rich context and practical guidance (e.g., 'Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven'). This goes beyond the schema alone.

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 explicitly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and identifies the resource (Polymarket markets), clearly distinguishing from siblings like 'polymarket_arbitrage' and 'polymarket_kalshi_spread'.

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 is tailored for 'what should I bet on today', giving clear use context. It details filtering knobs for tradeable edges but does not explicitly state when not to use this tool or compare it directly to siblings. However, the use case is well-defined.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description confirms this by describing snapshot reading and trend computation. It adds behavioral context: data gaps explained, decay from daily closes (not intraday), snapshot TTL, and the derivation of trend/decay metrics.

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, followed by details of response fields and limitations. While dense, every sentence contributes value. Slightly verbose but acceptable for the complexity of 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?

Despite lacking an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and key computed fields (trend, decay_pp_per_day). It also covers limitations (snapshot TTL, gaps). Complete for a complex data query 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?

Input schema covers 100% of parameters with descriptions. The description echoes schema defaults (days=14, window='1wk') and adds a 'max 30' clamp consistent with schema's 'clamp 2-30', but does not add substantial new meaning 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?

The description states a specific verb ('answers') and resource ('edge persistence and decay telemetry'), clearly distinguishing it from related sibling tools like polymarket_edges, polymarket_arbitrage, etc. It provides a concrete example of what the tool determines ('how long has this edge existed and is it shrinking?').

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 implies when to use this tool (for historical edge persistence analysis) vs. alternatives (e.g., polymarket_edges for raw snapshots). It mentions limits (history TTL, gaps) but does not explicitly state when not to use it or name alternative 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations, such as explaining the verdict system (clean|degraded|cannot_fill), the impact of thin books on capturability of theoretical overround, and the risk of partial basket fills leading to unhedged directional positions. No contradiction with 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 thorough but somewhat verbose. It is well-structured with clear sections (SINGLE-MARKET, BASKET) and bullet points for return values. Every sentence provides useful information, but it could be slightly more concise. The front-loading is good, with the core purpose stated first.

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 complexity of the tool (two modes, multiple return fields including verdict, per-leg detail, thin legs, etc.), no output schema, and 4 parameters fully described in the schema, the description is comprehensive. It explains return values for both modes, the risk of partial fills, forced directional risk, and the clamping behavior of size_usd. An agent has sufficient information to use the tool 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 description coverage is 100% (all four parameters have descriptions in the schema). The description adds meaning beyond the schema by explaining the difference between single-market and basket modes, how size_usd is interpreted differently (max spend vs target proceeds vs settlement notional), and the default behavior of side in basket mode. This adds value, so a 4 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?

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly contrasts with siblings polymarket_arbitrage and polymarket_edges by stating when to use this tool before those.

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 explicitly states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also explains the risks of partial fills and unhedged directional positions, providing clear context on when not to proceed.

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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing behavioral traits: how compatibility_warning fires in two cases, temporal_alignment meaning, skipped_cross_type counters, and conditions for meaningful spreads. No contradiction with 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 well-structured and front-loaded: purpose, modes, response fields, then safety details. Every sentence serves a purpose, and the length is justified by the complexity of 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?

Without an output schema, the description thoroughly covers what the agent can expect: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It is complete for a cross-venue spread analysis 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 coverage is 100%, and the description adds significant value by listing the allowed topic values, explaining the explicit parameters, and providing examples. It clarifies the relationship between topic and the explicit parameters.

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 opening sentence clearly defines the tool's purpose as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. The two modes (topic shortcuts and explicit parameters) are explicitly described, distinguishing it from sibling tools like polymarket_arbitrage.

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 explicit usage guidelines: it explains the two modes and when to use each, and warns that most pre-mapped topics currently return compatibility warnings and are not tradeable. This helps the agent decide when to use the tool and sets expectations.

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 cover safety (readOnlyHint, destructiveHint) and idempotency. Description adds value by listing returned fields (title, UPC, brand, etc.). No contradictions.

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 concise sentences: first states purpose, second lists contents. No redundant 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?

Adequate for a simple lookup tool with output schema. Lacks error handling info, but not critical given low complexity and annotation richness.

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 (id). Description mentions it as 'Spoonacular numeric id' and schema provides example. Adds some meaning beyond schema, but no details on constraints or format.

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?

Clear verb 'Fetch details' with specific resource 'branded grocery product' and scope 'by Spoonacular numeric id'. Distinguishes from siblings like product_search.

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?

Implied usage when you have the product ID, but no explicit when-to-use vs alternatives (e.g., product_search, ingredient_information). Lacks exclusions or context for selection.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. Description adds no further behavioral context (e.g., pagination, auth, rate limits). Minimal extra value.

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?

Extremely concise at three words, but under-specified for a tool with 5 parameters and numerous siblings. Fails to provide necessary detail, sacrificing completeness for brevity.

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?

Despite having an output schema, the description is completely inadequate given the tool's complexity (5 params, need to distinguish from >20 siblings). Lacks parameter semantics, usage guidelines, and behavioral context.

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 has 0% coverage with no descriptions for any of the 5 parameters. Description does not mention or explain any parameter, leaving the agent without guidance on how to use query, number, offset, maxCalories, minCalories.

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?

Description states 'Branded product search', indicating search for branded products, but does not differentiate from sibling tools like ingredient_search or product_information. Vague scope.

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?

No guidance on when to use this tool vs alternatives. Sibling tools include recipe_search and ingredient_search, but description does not specify use cases or 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 indicate read-only and idempotent behavior; description adds scoping details (by identifier) and clarifies that omitting key lists all keys, without contradicting 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?

Three sentences with no fluff; first sentence captures core purpose, remaining sentences provide usage context and scope.

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?

Adequately covers purpose, usage, scope, and sibling relationships for a simple tool with one optional parameter; minor omission of behavior for missing key is acceptable given no output schema.

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 3; description adds concrete examples of key contents (ticker, address, notes) and reiterates that omitting key lists all keys, adding value beyond 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 clearly states the verb (retrieve or list) and the resource (saved values/keys), and distinguishes from sibling tools 'remember' and 'forget'.

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 mentions when to use (look up stored context) and provides examples, but does not explicitly state when not to use alternatives beyond referring to 'remember' and 'forget'.

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 mark the tool as read-only and idempotent. The description adds behavioral detail: setting mark_read:true flags events as read, affecting subsequent calls. This explains a side effect beyond what annotations provide, without contradiction.

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 concise (4 sentences, ~80 words) and front-loaded with the core purpose. Every sentence adds useful information—no filler, no repetition of schema data. Highly efficient.

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?

The description covers the main functionality (retrieval, filtering, mark_read effect) and even provides an alternative access method. It lacks explanation of the 'unread_only' parameter's effect beyond the schema, but the schema covers it. Overall, it is complete for a tool with good annotations and schema coverage.

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 schema already describes all parameters (100% coverage). The description adds value by giving an example type ('sec_8k') and explaining the consequence of mark_read (next call shows only newer ones). This clarifies usage beyond the schema's technical descriptions.

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 starts with a clear action verb 'Pull' and specifies the resource 'fired events from your subscription feed'. It details what each event carries (source, citation_uri, payload) and mentions filtering options. This effectively distinguishes the tool from siblings like 'list_subscriptions' which serve a different purpose.

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 states that polling works and provides an alternative HTTP endpoint for scripts/dashboards, giving context on when to use the tool programmatically vs. directly. However, it does not explicitly compare to sibling tools or state when not to use it.

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, open-world, and idempotent behavior. The description adds value by detailing the fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and the return structure including citation URIs. This is good transparency but could further clarify rate limit 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 description is relatively long but well-organized with example queries upfront, followed by behavior details and a clear alternative pointer. It could be slightly more concise by grouping examples, but it's not overly verbose.

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 complexity (multiple sources, fallback, soft-fail) and lack of output schema, the description covers the key behavioral aspects and return structure (grouped changes, count, citation URIs). However, precise field details of the changes object are not specified, which leaves some ambiguity.

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%. The description goes beyond by explaining the 'since' parameter's ISO date and relative shorthand syntax with examples ('7d', '30d', '3m', '1y'), and clarifies that 'value' accepts tickers or CIK numbers. This provides meaningful addition.

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 clearly states it provides a change feed for a company in the last N days/weeks/months, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool entity_profile by explicitly saying when to use that instead.

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 numerous example queries (e.g., 'What's new with X', 'latest on Y') illustrating when to use the tool. It also explicitly states when not to use it and points to entity_profile as an alternative for static profiles.

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 and idempotent. Description adds that response varies with includeNutrition, but doesn't disclose other behavioral details like authentication or rate limits. It aligns with 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?

Single sentence with front-loaded purpose, listing return fields efficiently. No fluff.

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?

Output schema exists for returns, so description suffices. Covers key return fields. Might lack mention of error handling or limits, but overall adequate for a simple fetch.

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 0%, so description must compensate. It explains 'numeric id' and 'includeNutrition' as optional nutrition, but lacks details on id format (e.g., integer) or default value for the boolean.

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 clearly states the verb 'Fetch' and the resource 'full details for a Spoonacular recipe by numeric id'. It lists specific return fields, distinguishing it from sibling tools like recipe_summary or recipe_ingredients.

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?

No explicit guidance on when to use this over alternatives. While the description implies it's for full details, it doesn't contrast with siblings or state when not to use.

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, openWorldHint, idempotentHint, destructiveHint. Description adds specific return fields and cost unit (US cents), providing useful behavioral context beyond 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?

Two sentences: first states purpose, second details returns. No wasted words, front-loaded.

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 simplicity (one required param, no nested objects, output schema present), the description provides sufficient context for an agent to use the tool 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 0%, so description must add meaning. It clarifies that the id parameter is the Spoonacular recipe id. However, it does not explain format or constraints beyond the schema's example. Marginally helpful.

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?

Description clearly states the tool fetches ingredient list for a Spoonacular recipe by id, and lists the returned fields. This distinguishes it from siblings like recipe_information or recipe_nutrition.

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?

Implied usage: provide a recipe id. However, no explicit guidance on when to use this vs sibling tools (e.g., recipe_information, recipe_nutrition). Agent would need to infer from the description.

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, openWorldHint, idempotentHint, destructiveHint false. The description adds value by specifying the exact return fields (calories, macros, per-nutrient values with %DV), which goes beyond the annotation-provided safety profile.

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 sentences with no superfluous words. The purpose is front-loaded, and every word adds value. It is appropriately sized for a simple 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 low complexity (one parameter), existence of an output schema, and annotations covering read-only/idempotent behavior, the description is fully adequate. No gaps remain.

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 0%, so the description must explain the parameter. It clearly states 'by `id`' indicating the parameter is a recipe ID, adding meaning beyond the bare schema type 'number'.

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 clearly states the verb ('Fetch'), resource ('full nutrition breakdown'), and scope ('by `id`'). It differentiates from siblings like recipe_ingredients and recipe_summary by specifying the exact data returned (calories, macros, per-nutrient values with %DV).

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 implies usage for nutrition data but does not explicitly state when to use this tool versus alternatives (e.g., recipe_summary, recipe_ingredients). No exclusion or when-not-to-use guidance is provided.

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, openWorldHint, idempotentHint, and destructiveHint, covering safety. Description adds behavioral context about output structure (per-ingredient price in cents, total cost per serving) beyond annotations, but does not contradict 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?

Two sentences with no waste. Action verb and resource are front-loaded. Every sentence adds 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?

Output schema exists (context signals indicate true), so return values are covered. Description adds critical context about units (US cents) and scope (per serving). No missing information for a simple fetch 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 coverage is 0%, but description mentions the 'id' parameter as a recipe ID and provides an example. While minimal, it adds meaning to the required parameter. More detail on parameter format or constraints would improve score.

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?

Description clearly states the tool fetches estimated ingredient cost breakdown for a recipe by ID, specifying return of per-ingredient price in US cents and total cost per serving. This distinguishes it from sibling tools like recipe_information or recipe_ingredients.

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?

Description implies usage when cost breakdown is needed, but does not explicitly state when to use this tool versus alternatives (e.g., recipe_nutrition for nutrition data, recipe_ingredients for ingredient list). No when-not criteria provided.

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, idempotent, non-destructive behavior. The description adds value by specifying that returns include full recipe details (ingredients, instructions), which is useful beyond the structured 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?

Two sentences, front-loaded with the primary action, covering the essential features without any extraneous text. Highly efficient.

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?

The description is complete for a simple random selection tool, covering optional filters, output content, and leveraging the output schema for return values. No gaps remain.

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 0% schema description coverage, the description effectively explains both parameters: tags as comma-separated filter and number as count of results, using concrete examples. This fully compensates for the lack of schema descriptions.

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 clearly states the tool fetches random recipes with optional filters by tags and number, distinguishing it from sibling tools like recipe_search which retrieves specific recipes by query.

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 explains when to use (for random recipes) and the optional parameters, but does not explicitly mention when not to use or provide direct comparisons with alternatives. However, the context is clear for an agent.

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?

The description is consistent with annotations (readOnlyHint, idempotentHint, destructiveHint=false) but adds no additional behavioral context beyond what annotations provide. It does not mention rate limits, error conditions, or query constraints.

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 two sentences: the first states the action and filter types, the second lists return fields. It is front-loaded with the purpose and free of extraneous information. Every sentence earns its place.

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 complexity and many sibling recipe tools, the description could be more complete by explaining typical use cases or how it differs from recipe_information. However, since an output schema exists, the description need not detail return values. It adequately sets context for a search 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?

The input schema has no defined properties (only examples), making schema description coverage trivial. The description compensates by listing typical query parameters (query, cuisine, diet, etc.), adding meaning beyond the empty schema. With 0 formal parameters, description carries the burden and does so well.

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 clearly states the verb 'Search', the resource 'Spoonacular recipes', and the specific output fields (recipe id, title, image, ready-in minutes). It distinguishes from sibling tools like product_search or ingredient_search.

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 mentions 'complex filters' implying its use for filtered searches, but does not explicitly state when to use this tool over alternatives like recipe_information or recipe_summary. No exclusions or when-not-to-use guidance provided.

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, so the safety profile is clear. The description adds that the tool returns specific fields but does not elaborate on rate limits, authentication, or any side effects. It is consistent with 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?

Two sentences, front-loaded with the action. Every sentence contributes necessary information (source, input, output fields). No superfluous text.

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 (2 params, output schema exists), the description is reasonably complete. It covers input, output fields, and behavior. Minor gap: no mention of default value for 'number' or error conditions, but not critical.

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 0%, so the description carries the full burden. It explains that 'id' is the recipe identifier and 'number' controls the count of similar recipes returned, adding meaning beyond the bare schema. The description also indicates that 'number' is optional (up to that many).

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 clearly states the action ('Fetch Spoonacular recipes similar to a given recipe by id'), the resource ('recipes similar'), and the returned fields ('title, image URL, ready time, and servings'). It distinguishes from sibling tools like recipe_search or recipe_information.

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 implies usage context (finding similar recipes) but does not explicitly state when to use this tool versus alternatives like recipe_search or recipe_random. No when-not or exclusion criteria are provided.

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 provide `readOnlyHint: true` and `destructiveHint: false`, so the safety profile is clear. The description adds that the output includes title and a 1-2 sentence description, which is helpful but not beyond what annotations cover.

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, well-structured sentence that conveys all necessary information without redundancy. Every word serves a purpose.

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 simple tool (one parameter, output schema present), the description fully covers the input, output format, and purpose. No further detail is needed.

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 description mentions 'by `id`' and the schema includes an example, but with 0% schema description coverage, more parameter guidance (e.g., valid range or source) would strengthen semantics. However, the single parameter is self-explanatory given the tool name.

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 clearly states the verb 'Fetch', the resource 'short human-readable summary paragraph', and the identification method 'by `id`'. It distinguishes from sibling tools like `recipe_information` or `recipe_ingredients` by specifying a concise summary output.

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 implies use when a quick overview is needed, but lacks explicit guidance on when to choose this tool over alternatives such as `recipe_information` for full details or `recipe_ingredients` for ingredient lists.

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, idempotentHint, and destructiveHint false. The description adds the list of returned taste dimensions and normalization option. It does not disclose error handling or data freshness, but annotations cover the safety profile adequately.

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 sentences with no wasted words. The action verb 'Fetch' is front-loaded, and all necessary information is presented concisely.

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 low complexity (2 params) and presence of an output schema, the description adequately covers what the tool returns. It could mention the output shape (e.g., object keys) but the output schema presumably handles that.

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 0% schema description coverage, the description fully explains both parameters: id as the recipe identifier and normalize as an option to scale scores 0–100. This compensates effectively for the missing schema descriptions.

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 clearly states 'Fetch taste profile scores' – a specific verb and resource. It explicitly lists the tastes returned, distinguishing it from sibling tools like recipe_information or recipe_nutrition that deliver different data.

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?

No guidance on when to use this tool versus the many recipe siblings (e.g., recipe_information, recipe_summary). The only usage hint is the optional normalize parameter, but no context for selection.

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 (idempotentHint=true, destructiveHint=false), the description reveals key behavioral traits: persistence differences between authenticated (persistent) and anonymous (24-hour) sessions, and scope by identifier. No contradictions.

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 concise (4 sentences), front-loaded with the main purpose, and efficiently structures usage guidelines, behavior details, and paired tools without redundancy.

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 key-value store with full schema coverage and no output schema, the description covers all necessary aspects: purpose, when to use, persistence behavior, and related tools. Missing return value details are acceptable given simplicity.

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% (both parameters described with examples). The description adds minimal extra meaning beyond schema—reinforcing key-value pair storage and identifier scoping—but does not introduce new constraints or clarifications.

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 uses a specific verb 'Save data' and identifies the resource as memory that is reusable across conversations/sessions. It distinguishes from sibling tools 'recall' and 'forget' by explicitly naming them as paired operations.

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 explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference, research subject) and states that it pairs with 'recall' for retrieval and 'forget' for deletion, covering 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context such as cascading internal lookups, auto-disambiguation, and citation URI returns, which go beyond 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 well-structured with an introductory phrase, clear purpose, and organized details for each type. It is informative but slightly verbose; however, every sentence provides necessary context.

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 complexity of two entity types and multiple input formats, the description fully covers what the tool does, its outputs, and its efficiency benefits. Without an output schema, it adequately explains return values for each type, leaving no gaps.

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 schema covers both parameters fully (100% coverage). The description enhances understanding by giving concrete examples for each type (e.g., ticker, CIK, name for company), explaining auto-disambiguation, and specifying output details, adding value 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 clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific examples for both supported types (company and drug) and details what each returns, distinguishing it from sibling 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?

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke the tool. It mentions that it replaces 2-3 manual lookups, though it does not explicitly list alternatives or when not to use it.

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?

The description adds behavioral context beyond annotations: probes each entity with ai_visibility_check, ranks, returns scores/confidence/signal density. Annotations already indicate read-only, idempotent, non-destructive. No contradictions.

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 two sentences plus a usage quote. It is front-loaded with the core function and uses minimal, effective language. Every sentence adds 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers the process, use case, and outcome. Complete for the tool's complexity.

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 baseline is 3. The description does not add extra parameter meaning beyond what the schema already provides. It mentions the probing mechanism but that is not parameter-specific.

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 clearly states the tool compares AI visibility across multiple entities side-by-side. It specifies it probes each entity, ranks by score, and surfaces most/least recognized. This distinguishes it from the sibling ai_visibility_check which is for single entities.

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 explicitly says 'Useful for competitive AI-marketing audits' and implies comparing brands. It does not explicitly mention when not to use or alternatives, but the sibling context provides differentiation. Slight lack of exclusion criteria.

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, idempotent, non-destructive, and open world. The description adds rich behavioral context: composite call fanning out to two services, partial failures listing sources_failed, bundlephobia's first measurement delay (5-30s), and the specific fields returned. No contradictions with 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 dense but well-structured, front-loading the core purpose. Every sentence adds useful information, though it could be slightly more concise without sacrificing clarity. It remains readable.

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 complexity (composite call, multiple data sources, potential timeouts, and no output schema), the description thoroughly covers return fields, failure modes, and ecosystem limitations. It provides all necessary context for an agent to use 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% with descriptions. The description adds value by noting scoped package acceptance and default version behavior, which are not in schema descriptions. However, the additional info is minimal beyond 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 clearly states the tool performs a composite check for adding an npm package, combining deps.dev and bundlephobia data. It specifies the ecosystem (NPM) and distinguishes from siblings that might handle other ecosystems or single-source checks.

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 says when to use: for questions about safety, popularity, size, or cost of adding a package. It also mentions alternatives for other ecosystems (PyPI, Maven, etc.) and notes that bundlephobia may time out gracefully. This provides clear guidance on tool selection and expectations.

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 (readOnlyHint, idempotentHint, etc.), the description reveals the underlying model (BGE-base-en), chunking method (500-char overlapping windows), character cap (200K with truncation flag), and output details (offsets, similarity scores). Full behavioral disclosure.

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?

Every sentence earns its place; the description is front-loaded with the key use case. Slightly longer than necessary but without fluff.

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?

Despite no output schema, the description fully describes return format (top-N passages, character offsets, similarity scores) and handles edge cases (truncation). Complete for an AI agent to invoke 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%, but the description adds context: max 200K chars for text, example queries for query, and range/default for limit. This enriches parameter understanding beyond schema types.

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 clearly states it performs semantic search inside a fetched record, specifies return type (passages with offsets and scores), and distinguishes from siblings like ask_pipeworx and ask_pipeworx_grounded by noting the pairing and use case.

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 says when to use: 'when the record is too big to cram into the prompt', and gives a concrete alternative/companion tool (ask_pipeworx_grounded). This helps the agent decide between 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 are already clear (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds valuable behaviors: requires OAuth, rate limits on SMS (10/day), webhook auto-disable after 10 failures, and that webhook secret is returned only once. No contradictions.

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 well-structured: purpose first, then prerequisites, type examples, and delivery details. Every sentence adds value, and the length is justified by the complexity of the tool. No wasted words.

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?

The description covers return value (subscription id), prerequisites, rate limits, and error conditions. However, it only elaborates on three of the five enum values for 'type', leaving 'patent_grant' and 'clinical_trial' to the schema alone. Given no output schema, the description is still thorough but not perfectly complete for all supported types.

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%, but the description adds significant detail: concrete examples for each type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'), explains delivery channel specifics (SMS cap, webhook HMAC signing), and clarifies the 'params' structure 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 clearly states the tool creates a 'proactive monitoring subscription' to a live-data event stream and returns the subscription id. It uses a specific verb ('create') and resource ('subscription'), and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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 explicitly requires a Pipeworx OAuth account and lists supported subscription types with examples. It does not explicitly state when not to use the tool, but the context of subscriptions and delivery channels implies appropriate usage. Alternatives like listing or reading alerts are not compared, but the sibling set includes those for differentiation.

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, idempotent, non-destructive, and open-world traits. The description significantly adds beyond these: it reveals that the tool returns category-bucketed examples drawn from a live catalog of thousands of tools, and that it teaches how to call meta-tools. No contradictions with 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 somewhat lengthy but every sentence adds value. It is front-loaded with common user queries and quickly establishes the tool's purpose. No fluff, but could be slightly tighter; still highly efficient.

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 tool with no output schema, the description fully explains what to expect: category-bucketed examples with tool shapes. It covers the use case for new users and the optional `topic` focusing. The description is complete and leaves no ambiguity about its behavior.

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 covers the single parameter `topic` with 100% coverage. The description adds valuable context: lists valid focus areas as examples, explains that omitting gives a full spread, and reinforces the argument's purpose. This goes beyond a simple schema description.

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 clearly states the tool as the onboarding entry point for agents to discover what Pipeworx can answer. It lists explicit trigger phrases and specifies the output: category-bucketed example questions with exact tool and argument shapes. This distinguishes it from siblings like ask_pipeworx or discover_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?

The description explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass `topic` versus no arguments. While it doesn't explicitly state when not to use it, the guidance is clear and targeted, earning a 4.

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?

The description discloses that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts,' adding value beyond annotations. No contradiction with 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 two sentences, front-loading the action and then adding key constraints and behavioral nuance. No unnecessary words.

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 has one required parameter and no output schema, the description covers purpose, ownership, and soft-delete behavior. It is fully adequate for the tool's simplicity.

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 parameter 'id' is already fully described in the schema. The description references it as 'Subscription id (uuid) returned by subscribe,' which aligns with but does not significantly extend 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 clearly states 'Cancel a subscription by id,' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use this tool. While it doesn't list alternatives directly, the constraint is clearly communicated.

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 readOnly, openWorld, idempotent, non-destructive. Description adds context on return values (verdict, citation, delta) and the consolidation of multiple calls, providing transparency beyond 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 detailed yet efficiently structured, front-loaded with usage examples and clear purpose. Some redundancy in listing examples could be trimmed, but overall concise.

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 no output schema, the description fully explains return values (verdict, structured form, citation, delta). It covers purpose, usage, supported domains, and behavioral aspects, making it complete for agent invocation.

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% with a description for the 'claim' parameter. The description reinforces with examples and context, adding value by explaining the parameter's role and natural-language format.

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 clearly identifies the tool's core function as natural-language claim verification using authoritative sources, with specific examples like 'fact check' and 'verify the claim that...'. It distinguishes itself by mentioning it replaces multiple sequential calls, differentiating from sibling 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?

Explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct'. It specifies supported claim types (company-financial) but does not explicitly state when not to use or mention alternative tools for other claim types.

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, idempotentHint, destructiveHint. Description adds return fields but no additional behavioral traits like rate limits or auth.

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 concise sentences with front-loaded key information. No redundancy or superfluous content.

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 only 2 parameters and output schema exists, description adequately covers return fields (name, price, description) and usage context.

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 0%, but description compensates by defining 'food' as dish/ingredient with examples, and 'maxPrice' as optional filter.

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?

Description clearly states the action 'Fetch wine pairing suggestions' and the resource 'food dish or ingredient', distinguishing it from sibling tools like wine_recommendation by specifying 'pairing suggestions'.

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?

Description implies when to use (for a food dish/ingredient) with examples, but lacks explicit guidance on when not to use or 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?

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds value by specifying that it returns product name, price, average rating, and description, which are not covered by the annotations. No contradiction with 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 extremely concise, using two sentences to convey the entire tool purpose and functionality. Essential information is front-loaded in the first 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?

Given the tool's simplicity and the existence of an output schema, the description adequately covers the tool's purpose, parameters, and return fields. It lacks details like price format or maximum count, but is mostly complete for an agent to use effectively.

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 0% schema description coverage, the description partially compensates by explaining that minRating, price, and number are optional filters. However, it lacks specifics such as the format for the price parameter (string) or constraints on the number parameter, leaving some ambiguity.

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 clearly states the tool fetches specific wine product recommendations based on a wine type name. It uses a specific verb "fetch" and identifies the resource as wine product recommendations, distinguishing it from sibling tools like wine_pairing.

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 does not provide any guidance on when to use this tool versus alternatives such as wine_pairing or other search tools. No explicit when-to-use or when-not-to-use information is given, leaving the agent without context for selection.

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