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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds important behavioral details: routes queries to 3,744 tools, fills arguments, and returns structured answers with citation URIs. 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 two paragraphs with key information front-loaded. The first sentence immediately states preference over web search. It is concise yet informative, though it could be slightly shorter by removing redundant examples, 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 complexity and the lack of an output schema, the description fully covers what the tool does, when to use it, examples, and what the user gets (structured answer with citations). 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?

All six parameters are aliases for the 'question' field, and the schema already documents these with clear descriptions and examples. The description adds the context that the question is in natural language and provides examples, but does not add significant meaning beyond what the schema provides. Schema coverage is 100%, so 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 explicitly states the tool's purpose: answering factual questions about real-world data using authoritative sources. It lists specific domains (SEC filings, FDA, etc.) and contrasts with web search, making the purpose crystal clear.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for the listed domains, provides example query patterns ('what is', 'look up', 'find'), and gives concrete examples. This leaves no ambiguity about when to use this tool versus alternatives like web search or sibling tools like 'deep_research' or 'entity_profile'.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it routes to correct tool, fills arguments, fetches data, extracts answer only from tool result, returns structured response with refusal reasons, and costs extra LLM call. 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?

Description is packed with crucial information and well-structured: purpose, mechanism, output format, usage guidance. Every sentence adds value, though slightly verbose—could be tightened without losing substance.

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 (orchestrating many sources, extracting answers, returning refusals) and absence of output schema, the description fully covers behavior, return format, and refusal modes. 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?

Schema coverage is 100% with all aliases described. Description does not add parameter-specific details beyond what schema provides, so baseline of 3 is appropriate. No value added 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?

States specific verb-resource pair ('Extracts answer using ONLY tool result') and distinguishes from sibling ask_pipeworx by naming it and contrasting behavior. Clearly labels itself as hallucination-resistant for high-stakes reads.

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 (high-stakes reads, when answer will be quoted/cited/acted on) and when not to (prefer ask_pipeworx for casual lookups). Lists refusal reasons, providing clear decision 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?

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=true, idempotentHint=true, and destructiveHint=false, indicating a safe, idempotent operation. The description adds no additional behavioral context, such as error handling or unit restrictions.

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 concise (two words), it is underspecified for a tool with 4 required parameters. Every word should add value, but here it omits critical details, making it more terse than 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 the tool's complexity (4 params, no schema descriptions, but an output schema), the description is completely inadequate. It fails to provide enough information 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?

With 0% schema description coverage, the description must compensate by explaining parameter meanings. It only says 'Unit conversion' and does not describe sourceUnit, targetUnit, sourceAmount, or ingredientName, leaving the agent with no semantic guidance.

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 'Unit conversion,' which conveys the general purpose of converting units, but it lacks specificity about the domain (ingredient conversions) and does not differentiate from siblings. The examples provide context but the description itself is vague.

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 alternatives. The description provides no context about prerequisites, allowed scenarios, 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, open-world, idempotent, and non-destructive behavior. The description adds detailed behavioral context: parallel decomposition, citation format (pipeworx://), gaps array, pre-verified facts, and expected timing (15-60s). 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 but well-structured, front-loading the core value. Every sentence provides unique information, though slightly longer than minimal. Slight redundancy in listing sources count.

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 no output schema, the description covers return format (findings packet, evidence, gaps), parallel execution, source diversity, time estimate, and prerequisite account. No missing critical details 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 covers both parameters fully. Description adds meaning: explains that depth controls facet count (quick=3, standard=5, thorough=8) and that the question parameter accepts broad/multi-part natural language, with automatic decomposition.

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 specifies a grounded multi-source research tool that decomposes questions, routes to 3,744 tools in parallel, and returns evidence per facet. It clearly distinguishes from siblings like ask_pipeworx for single lookups.

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 recommends use for broad or multi-part questions and advises using ask_pipeworx for single lookups. Mentions account requirements and that 'thorough' depth requires a paid plan.

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?

While annotations already declare readOnlyHint and idempotentHint, the description adds no additional behavioral context (e.g., no mention of what data is returned, whether unit/amount affect the output, or any side effects). 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 brief, but it is under-specified. Conciseness should come with sufficient information; here it fails to convey the tool's purpose or usage.

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 and 3 parameters, the description provides almost no context. It does not explain the function of optional parameters, the structure of the response, or any prerequisites.

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%, and the description provides no explanation for the parameters (id, unit, amount). The agent has no insight into what these parameters mean or how to use them correctly.

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 detail' is vague and essentially restates the tool name. It doesn't specify that the tool retrieves detailed information for a given ingredient ID, nor does it distinguish it from sibling tools like '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?

No guidance on when to use this tool versus alternatives such as 'ingredient_search' or 'product_information'. The description provides no context for appropriate usage scenarios.

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 indicate read-only, idempotent, non-destructive behavior. The description adds no additional behavioral context; it simply restates the tool's name in a sentence.

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 short, which is concise, but it sacrifices clarity and usefulness. Every sentence should add value; this one does not.

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

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

With 4 parameters and no descriptions, the tool definition is incomplete. The output schema exists but does not excuse the lack of input semantics. The tool is under-specified.

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%, and the description provides no information about parameters. The examples in the schema offer some hint, but the agent lacks semantic guidance on how to use diet, exclude, timeFrame, and targetCalories.

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 'Generated meal plan.' is a vague noun phrase, not a clear statement of what the tool does. It lacks a verb and does not differentiate from sibling tools like meal_plan_week.

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 provided on when to use this tool versus alternatives such as meal_plan_week. No context on parameters like diet, exclude, or targetCalories.

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, openWorldHint, idempotentHint, and non-destructive behavior, which are helpful. However, the description adds no behavioral context beyond '7-day plan', such as whether it returns a plan, how long it takes, or if it requires internet access.

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 (three words), but at the cost of meaningful information. Conciseness is positive, but not when it leads to under-specification.

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 and three optional parameters, the description fails to explain what the tool returns, how it interacts with other tools, or any use cases. It is insufficient for an AI agent to select 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 description coverage is 0%, and the description omits any mention of the three parameters ('diet', 'exclude', 'targetCalories'). The examples in the schema provide some context, but the description itself adds no semantic value for 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 '7-day plan' is minimally informative. It states a duration but lacks a verb or specific resource, making it unclear whether the tool generates, retrieves, or edits a plan. It does not distinguish 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?

No guidance is provided on when to use this tool versus alternatives like 'meal_plan_generate', 'recipe_search', or 'recipe_random'. No prerequisites or exclusions 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 show readOnly, openWorld, idempotent, non-destructive. Description adds internal logic: monotonicity checks, partition sum, Jaccard similarity threshold, placeholder filtering, fill check against live CLOB depth. No contradiction; description enriches safety understanding 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?

Description is verbose but well-structured: starts with requirement, then each mode, then edge cases, response format, fill check, and reference to sibling. Every sentence adds value; minor marks off for length but justified by 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, but description details response structure including opportunities and partition_check fields. Covers failure case (no args), internal constraints, and references to fill risk tool. Complete for a tool with 2 params and complex logic.

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 with descriptions. Description adds examples for event slugs, seed questions, and explains behavioral differences between modes. Schema coverage is 100%, and description adds significant semantic 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic), and the name and title align. Sibling tools like polymarket_edges, polymarket_fill_risk are distinct, and the description contrasts by mentioning fill risk tool explicitly.

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

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

Explicitly requires one of two parameters, recommends event for single-market and topic for cross-scanning. Explains why cross-event catches patterns single-event misses. References polymarket_fill_risk as alternative for custom sizing. Clear when-to-use and when-not.

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 already provide read-only, open-world, idempotent, non-destructive hints. The description adds no additional behavioral context (e.g., what happens for invalid IDs, caching behavior, or response format).

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

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

Extremely short (two words), but this is under-specification, not conciseness. It omits critical information that should be present.

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 an output schema exists and sibling tools provide context, the description should at least specify that the tool fetches details for a product by ID. It doesn't, making it incomplete.

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% description coverage. The only parameter 'id' is not explained in the description. No hint that it's a product ID or what valid values are. Description completely fails to add parameter semantics.

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

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

Description 'Product detail.' is vague. It doesn't specify what product domain or what details are returned. Sibling tools like ingredient_information and recipe_information indicate a food context, but the tool's purpose is not differentiated.

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 or when not to use this tool. It doesn't mention alternatives like product_search for finding products or recipe_information for recipes. Usage context is entirely implicit.

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

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

Annotations 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the tautological 'detail'.

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 but at the expense of informativeness. 'Recipe detail.' is too sparse to be useful; it could be expanded without losing 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 and simple parameters, the description is incomplete. It lacks essential context about what data the tool returns and how to effectively invoke it.

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

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

Schema description coverage is 0%, yet the description provides zero explanation of parameters `id` and `includeNutrition`. The agent has no guidance on what `includeNutrition` means or how to use it.

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

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

The description 'Recipe detail.' is minimal and does not specify what kind of detail is retrieved. It fails to distinguish from sibling tools like 'recipe_summary' 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?

No guidance on when to use this tool versus the many related recipe tools (e.g., recipe_search, recipe_similar). The context signals show multiple siblings, but the description provides no selection 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and non-destructive. The description adds no additional behavioral context, but does not contradict the annotations. With annotations covering the safety profile, a score of 3 is appropriate.

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 words) but at the cost of clarity. It lacks structure and fails to convey necessary information. Conciseness should not come at the expense of usefulness.

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 that the tool has one parameter and no schema description coverage, the description is insufficient. While an output schema exists, the lack of parameter context and usage guidance makes the tool hard to 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?

The input schema has one required parameter 'id' (number) with 0% description coverage. The description does not explain what 'id' represents (e.g., recipe ID). The description fails to compensate for the missing schema documentation.

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 list' is vague. It doesn't specify what kind of ingredients, for which recipe, or what details are returned. The name suggests it's for recipe ingredients, but without more context, it's unclear how this differs from sibling tools like ingredient_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?

No usage guidelines are provided. There is no indication of when to use this tool over alternatives like ingredient_information or recipe_information.

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 safe, read-only, idempotent behavior. The description adds no behavioral context such as what nutritional data is returned or whether it's per serving. Fails to add value 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?

Extremely concise (two words) but at the cost of completeness. Not front-loaded with useful information; under-specification.

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 multiple sibling recipe tools and an output schema, the description is inadequate. It does not specify what nutrients are included, the return format, or when to use this tool. Incomplete for the 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 0%, and the description does not explain that the 'id' parameter is the recipe ID. The example in schema provides some context, but the description itself adds no meaning.

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 'Nutrition breakdown' is vague. It does not specify that it retrieves nutrition data for a recipe by ID, nor does it distinguish from siblings like recipe_information or recipe_summary.

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 like recipe_information or recipe_summary. No prerequisites or context 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?

Although annotations (readOnlyHint, openWorldHint, idempotentHint) already convey safety and idempotency, the description adds no further behavioral context. It does not explain what the cost breakdown includes, how it behaves, or any side effects beyond what annotations already state. The description is too sparse to enhance the agent's understanding.

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 short (two words), but this is under-specification rather than efficient conciseness. It lacks structure and essential details, failing to earn its space because it provides almost no utility.

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 that the tool has one parameter and an output schema, the description is severely incomplete. It does not explain what the tool does, what the input represents, or what the output contains. The agent would struggle to use this tool correctly without additional 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?

The input schema has one parameter 'id' with no description (0% coverage). The tool description 'Cost breakdown.' provides no additional meaning for the parameter. The agent cannot infer that 'id' refers to a recipe ID or any specific entity, making parameter usage ambiguous.

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 'Cost breakdown.' is vague; it doesn't specify what resource is being broken down (e.g., a recipe). The title 'Recipe Price Breakdown' suggests the tool relates to a recipe's price, but the description lacks a clear verb and resource, making it hard for an agent to distinguish 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?

No guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The agent receives no help in deciding between this and sibling tools like recipe_summary or recipe_information.

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, so the safety profile is clear. The description adds minimal behavioral context beyond the name, but does not contradict annotations. It implies randomness but does not elaborate on non-determinism or side effects.

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?

At two words, the description is underspecified rather than concise. It does not provide enough detail to be useful, earning its place poorly.

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 insufficient for a tool that generates random results with optional tag filtering. It lacks explanation of randomness behavior, return format, or how tags affect results, making it incomplete for an AI agent to 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?

Schema description coverage is 0%, and the description contains no information about the parameters 'tags' or 'number'. The examples in the schema provide usage hints, but the textual description fails to explain the meaning or effect of these parameters, leaving the agent uninformed.

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 'Random recipes' is vague and lacks a clear verb indicating the action (e.g., 'get', 'fetch'). It does not distinguish this tool from sibling tools like recipe_search or recipe_similar, which also deal with recipes but in different ways.

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?

There is no guidance on when to use this tool versus alternatives. No context about scenarios where random recipes are preferable over searching or filtering 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 readOnly, idempotent, openWorld. Description adds no behavioral context beyond 'complex', failing to disclose result format or search behavior.

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

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

One phrase is too brief; it is under-specified rather than concisely informative.

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 many sibling tools and presence of an output schema, the description provides no information about inputs, outputs, or usage context, making it grossly incomplete.

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 zero parameters, so description needs no parameter detail; baseline 4 applies. However, examples in schema suggest possible parameters, causing inconsistency.

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 'Complex recipe search' is vague; it states a search but does not specify what distinguishes it from other recipe tools like recipe_information or recipe_similar.

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. the many alternative recipe search/detail tools in the sibling list.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate the tool is safe and idempotent. The description adds no behavioral context beyond annotations, such as what 'similar' means (e.g., based on ingredients) or result 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 extremely concise but at the expense of utility. It does not earn its brevity because it omits critical information needed for correct tool invocation.

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 0% parameter coverage and no explanation of output, the description is wholly insufficient. An agent cannot determine how to use the tool or what to expect from it.

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

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

Schema description coverage is 0%, and the description fails to explain the two parameters (id and number). Agent cannot infer the meaning or role of these parameters from the 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 'Similar recipes.' is a noun phrase that restates the tool name, offering no verb or specific action. It vaguely hints at finding similar recipes but fails to specify the input (recipe ID) or output, and does not distinguish it 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 provides no guidance on when to use this tool, when not to, or what alternatives exist. With many recipe-related siblings, an agent has no context to choose appropriately.

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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds no behavioral context beyond that. For a tool with no annotation gaps, a score of 2 is appropriate because the description fails to add any value, such as output format or side effects.

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 short but under-specified. Conciseness is only valuable with sufficient content; here, the two words are not concise but insufficient. No structuring or front-loading of key 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?

Given the presence of an output schema, the description need not explain return values, but it must clarify the tool's scope. It fails to provide any completeness for a simple tool with one parameter and many 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?

Schema description coverage is 0%, meaning the input schema has no description for the 'id' parameter. The description completely fails to explain what the 'id' represents (e.g., recipe ID) or how to use it, forcing the agent to guess.

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 'Short summary' is a tautology that restates the tool name without providing any specific verb or resource. It does not distinguish this tool from sibling tools like recipe_information or recipe_nutrition, all of which could be considered summaries.

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 offers no guidance on when to use this tool versus alternatives. Given the many recipe siblings, an agent cannot determine whether to call recipe_summary or another tool like recipe_information without additional 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 declare readOnly, idempotent, non-destructive. Description adds no extra behavioral info, but does not contradict 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?

Extremely short but lacks necessary detail. Not concise in a helpful sense; omits essential information about purpose and usage.

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 low complexity and presence of output schema, the description fails to communicate what the tool returns or how it fits among siblings. Agent cannot determine when to use it.

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

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

Schema coverage is 0%, and description provides no parameter explanations. Agent must infer meaning of 'id' and 'normalize' from names 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?

Description says 'Taste widget,' which is vague and does not specify the action (e.g., 'get taste profile'). It fails to differentiate from sibling tools like recipe_information or recipe_summary.

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 alternatives. Sibling tools have overlapping purposes, but no context is given 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds no additional behavioral context (e.g., what data is returned, whether it uses external sources). It is not contradictory but fails to enhance 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?

The description is overly terse ('Wine pairing.')—this is under-specification rather than effective conciseness. It lacks essential structure such as a verb or explanation of functionality.

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 two parameters and an output schema, the description is completely inadequate. It fails to explain what the tool returns, how to use the 'food' parameter, or any behavioral details, leaving agents with insufficient information to invoke it correctly.

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

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

With 0% schema description coverage, the description must compensate by explaining parameters, but it does not. 'food' and 'maxPrice' are entirely undocumented, leaving the agent without guidance on valid inputs or constraints.

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 'Wine pairing' is a tautology that merely restates the tool's name. It lacks a specific verb (e.g., 'suggests', 'recommends', 'finds') and does not indicate what action the tool performs or what resource it acts upon.

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 usage guidance is provided. The description gives no context on when to use this tool versus its sibling tools like 'wine_recommendation' or 'recipe_search', nor does it mention any prerequisites or limitations.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral insight beyond these annotations, such as what the recommendation is based on or any 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 extremely concise (3 words) but at the cost of missing critical information. It is not structured and provides no additional 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 having an output schema and four parameters, the description is completely inadequate. It fails to explain the tool's purpose, parameters, or behavior, leaving the agent with no useful context for selection or 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 0%, yet the description provides no explanation for any of the four parameters (wine, price, number, minRating). The meaning of each parameter is left entirely to the schema, which has no 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 'Wine recommendation.' is a tautology that merely restates the tool name. It lacks a specific verb and resource distinction, and does not differentiate from the sibling tool '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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.

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