Spoonacular

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

The annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the default model is free, using Anthropic requires a BYO API key with direct costs, and the return shape includes score, confidence, signals, raw_response, and a combined view.

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 composed of three efficient sentences: the primary function, the model/cost detail, and the return/use-case context. Every sentence contributes actionable information, and there is no redundant or filler 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?

Despite the lack of an output schema, the description clearly lists the per-model response fields and the combined view. Combined with the fully described parameters and relevant annotations, the description is complete enough for the agent 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 coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by explaining the default model (Workers AI Llama-3.3-70b, free), the requirement for an Anthropic API key if Anthropic is probed, and the direct payment relationship. This helps the agent understand cost implications and defaults.

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 clear purpose: probing LLMs for knowledge about an entity and scoring visibility 0-100 per model. It is specific about the output structure and use cases. However, it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, despite overlapping use cases like competitive monitoring.

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 names concrete use cases: AI-marketing audits, pre-launch brand checks, and competitive monitoring. This gives the agent context on when to use it. However, it does not mention when not to use it or suggest alternative tools for related needs.

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, destructiveHint=false. The description adds valuable behavioral context beyond annotations: routing mechanism ('routes the question to the right one of 5,521 tools'), argument filling, return format with citation URIs, and operational characteristics ('works on every tier, one fast call'). It doesn't disclose potential failure modes or rate limits, but the annotations cover safety and the description explains the core behavior well.

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 long but each sentence earns its place. It is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'), then explains mechanics, provides examples, and ends with escalation alternatives. The structure is hierarchical and scannable, with no redundant content or repetition of schema details.

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 routing tool with no output schema, the description is remarkably complete. It covers the tool's scope, behavior, return format (structured answer with citation URIs), usage triggers, alternative tools, and even performance characteristics. The examples illustrate a wide range of domains, making it easy for an agent to judge applicability. Given the rich annotations and schema, the description leaves no critical 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 input schema has 100% coverage for all 6 parameters (question and its aliases), each with a clear description. The description doesn't add parameter-level syntax details beyond the schema, but it does provide examples of valid questions, which indirectly illustrate usage. Since the schema fully describes the parameters, a baseline score of 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 clearly states this tool answers factual questions by routing to a large set of tools/sources and returning structured answers with citations. It explicitly specifies the resource (5,521 tools, 1,452 sources) and differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides concrete examples and trigger phrases ('what is', 'look up', 'get the latest'). It also tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions), providing clear conditional logic.

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 valuable experimental context: candidate routing improvements are live only when tested, results are compared against the stable router, and it is a full working router with no fallback. 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?

Three sentences efficiently communicate beta status, relationship to stable ask_pipeworx, current candidate status, and usage directive. Every sentence adds distinct value; the note about the retired candidate is specific but relevant for understanding current state.

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 router with no output schema, the description sufficiently covers purpose, experimental nature, current equivalence to stable, and how it is evaluated. It mentions 'same response shape' to compensate for missing output schema. It could mention potential side effects or failure modes, but annotations and sibling context reduce the need.

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

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

Schema description coverage is 100%, with each alias (q, text, input, query, prompt) individually documented as an alias for question. The description adds no param-level detail beyond this, so it stays at the baseline for full schema coverage.

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 this is a beta universal router: 'identical universal router (same 5,521 tools, same arguments, same response shape) with candidate routing improvements.' It names the verb (ask/route) and resource, and differentiates itself from the stable ask_pipeworx by being the experimental edge.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies current behavior with no active candidate. This gives clear context for when to use it. It does not explicitly mention alternatives like ask_pipeworx_grounded, but the primary alternative (ask_pipeworx) is well addressed.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behaviors: it returns refusal reasons when the data doesn't answer, provides a verbatim quote as evidence, and costs one extra LLM call. It also explains the internal routing and extraction process, which is valuable 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 well-structured, front-loading the core purpose and then detailing return format, usage guidance, and cost tradeoff. Every sentence provides unique value: purpose, process, success/failure formats, when to use, and cost comparison. No wasted words, 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 tool's complexity and the absence of an output schema, the description is highly complete. It explains the routing behavior, the extraction constraint, the exact success response shape, all possible refusal reasons, and the tradeoff vs. the sibling tool. There is no obvious missing context for an agent to select and invoke 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?

The schema covers 100% of parameters, all as aliases for 'question', with descriptions in the schema itself. The tool description adds no additional parameter semantics, so baseline 3 is appropriate. The description implies the input is a natural language question but doesn't enrich the schema's existing definitions.

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: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded extraction step and the return of evidence, making the specific verb+resource (extract grounded answer) 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of one extra LLM call. This is clear, actionable guidance with named 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 declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond by detailing fan-out examples, resolver contract (market_match_confidence), short-circuit statuses ('low_confidence_match'), closed-market handling, wide-spread tradeability, and cancellation-rule risk. This extensively discloses behavior that annotations cannot convey.

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

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

The description is long but unusually well-structured: it opens with the core purpose, then uses SCREAMING-CASE section headers for classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, safety, and resolution-rule risk. Every sentence adds operational value for a complex tool, making the length justified.

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

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

With no output schema, the description carries full burden for return values and edge cases, and it excels: it documents result.market/analysis/evidence, match_confidence semantics, parent_event extraction, fallback fields, and blocking statuses. Given the tool's complexity, this is a complete and self-sufficient reference.

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%—all three parameters have descriptions already. The description adds context about the market parameter (slug/URL/question text) but this is duplicated from the schema; no new parameter-level semantics are introduced. Thus baseline 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 opens with a specific verb+resource combination ('Research a Polymarket bet by pulling the relevant Pipeworx data') and clearly differentiates from siblings like polymarket_edges by describing the fan-out to category-specific data packs. It also lists concrete input formats (slug, URL, question text) and classifier categories, leaving no ambiguity about what the tool does.

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

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

It provides explicit usage scenarios ('Use for "should I bet on X"') and behavioral guardrails ('ALWAYS inspect these before trusting the analysis block'). However, it does not name alternative sibling tools for when-not-to-use cases, so it's clear context but no explicit exclusions.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: parallel call execution, exact financial data points pulled, handling of off-calendar fiscal years, sorting by primary metric, and citation URI return. This goes well 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 quite long but every sentence contributes unique information: usage examples, preference rule, type-specific data details, sorting behavior, and efficiency note. It is front-loaded with user phrasings. Slight verbosity in listing example phrasings prevents a perfect 5, but it is 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?

With no output schema, the description fully explains what data is returned (paired data, citation URIs, sorted by primary metric). It covers complexity: multiple entity types, data sources, and edge cases like off-calendar fiscal years. Annotations handle safety, and the description handles everything else, making it complete.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description enriches meaning significantly by defining what each type fetches (e.g., 'revenue + net income + cash + long-term debt' for company, 'FAERS adverse-event counts' for drug) and giving concrete examples like AAPL, MSFT, ozempic, mounjaro. This adds 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 performs side-by-side comparison of 2-5 companies or drugs, with specific user phrasings and examples. It explicitly distinguishes from sequential single-pack lookups by mentioning 'one parallel call' and 'replaces 8–15 sequential 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?

It provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies the type-specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), so the agent knows exactly when and how 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 establish read-only, idempotent, and non-destructive behavior. The description adds context by naming the external API (Spoonacular) and providing an example output format (1 cup flour → 125 grams), which is useful behavioral information beyond what annotations state.

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

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

Two sentences, front-loaded with purpose, then usage requirements and an illustrative example. No wasted words or repetition of schema 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?

The description covers purpose, required parameters, and expected output format. Output schema exists, and annotations cover safety. It could mention potential errors or unit constraints, but for a simple conversion tool it is adequately complete.

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

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

Schema description coverage is 0%, so the description compensates by naming all four required parameters and giving a concrete example with specific values. This clarifies the meaning of sourceAmount, sourceUnit, targetUnit, and ingredientName beyond their raw 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 the tool converts cooking measurement amounts for a specific ingredient between units using Spoonacular. This verb+resource+scope formulation distinguishes it from sibling tools like recipe_search or 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?

The description implies usage (when you need to convert units for a recipe ingredient) but does not explicitly state when to use it over alternatives or provide any exclusions. 'Requires' hints at prerequisites but no concrete usage scenarios are given.

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/open-world/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: account requirements, paid plan for thorough depth, lack of open-web access, gaps[] behavior (never invented), citability constraints, contradiction scanning, semantic excerpting, and expected latency. 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 long but contains high-value, non-redundant information for a complex tool. It is front-loaded with the critical account requirement and fallback. Minor redundancy exists (e.g., 'NOT open-web search' is repeated and depth details overlap with the schema), but overall the length 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?

Given the absence of an output schema and the tool's complexity, the description thoroughly covers return values (findings packet, gaps[], contradictions[], hop, citation_uri, fetched_at), latency, prerequisites, and edge cases. It leaves little ambiguity about what the agent should expect and how to handle common scenarios like unsigned-in users or unsupported topics.

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?

Although schema coverage is 100%, the description adds significant parameter-level meaning: the question parameter is illustrated with concrete examples, and the depth parameter is elaborated with facet counts, hop behaviors, and cost implications beyond the schema's enum descriptions. This is genuinely additive.

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 function: grounded multi-source research across Pipeworx's structured data sources, decomposing broad questions into facets and routing them to parallel tools. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its purpose 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 gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, while single lookups and breaking/current-news topics should use ask_pipeworx. It also provides a concrete fallback ('If you are not signed in, use ask_pipeworx instead') and explains the depth tiers, giving agents clear decision rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, which describe the safety profile. The description adds valuable behavioral detail about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies what the agent can expect and the convenience of direct callability, going 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 slightly long due to the enumerated list of example domains, but that list is informative and helps the agent understand what kinds of queries are appropriate. The first sentence is concise and front-loaded with the core purpose. Every sentence contributes context about usage and output, so it is appropriately sized.

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 this is a discovery tool with no output schema, the description fully explains when to use it, what it returns, and why it is useful (direct-callable results). It covers the essential context for an agent to decide whether to invoke this tool and what to expect, without any significant 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 for parameters is 100%, so the baseline is 3. The description mentions 'top-N' which loosely relates to the limit parameter, but it does not add detailed semantics beyond what the schema already documents (e.g., query aliases, default/max limit). The description does not compensate for any schema gaps since there are none, so a 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and distinguishes itself from sibling tools by being a meta-tool for exploring the available toolset. The list of example domains reinforces its 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?

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear when-to-use direction and even suggests calling it first, which is a strong usage guideline.

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, destructiveHint=false, but the description goes far beyond. It discloses the multi-source fan-out (SEC EDGAR, XBRL, USPTO, news, GLEIF), the exact return fields, and important caveats: patents API sunset and soft-fail, GDELT→GNews fallback, and the format for recent_filings URIs. This is rich behavioral context that annotations cannot convey.

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

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

The description is long but information-dense. It front-loads with example queries and the core value proposition, then systematically lists sources and return fields. Every clause adds value, but the density could be slightly trimmed without losing meaning. Given the tool's complexity, the length is justified, but it is not as lean as the TDQS exemplar.

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

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

With no output schema, the description must fully specify the return structure, and it does: cik, company_name, recent_filings (with up to 5 and URI format), fundamentals (specific fields and sorting), patents (with sunset caveat), news (with fallback), and LEI. It also covers input restrictions and alternatives. For a tool of this complexity, the description is complete.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description reinforces this by giving concrete examples ('AAPL' or zero-padded CIK '0000320193') and re-emphasizes the 'names not supported' constraint, adding clarity beyond the schema's generic description. It earns a 4 because it adds examples and practical context without being redundant.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') that make the intended use unmistakable. It then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call' and explicitly differentiates from chaining single-purpose lookups, positioning it as the preferred holistic tool. It also distinguishes itself from sibling tools like resolve_entity by noting the input limitation and alternative.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear when-not-to-use with an alternative: 'names not supported (use resolve_entity first if you only have a name).' This is a textbook example of directing the agent to the right tool.

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 destructiveHint and readOnlyHint false. The description adds value by specifying exactly what gets destroyed (previously stored memory) and offers rationale (clear sensitive data). No contradiction with annotations, though it doesn't discuss irreversibility or edge cases, which is acceptable given the simple action.

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

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

Two concise sentences: the first states the action, the second provides usage conditions and sibling tool relationships. No fluff, front-loaded, every sentence earns its place.

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

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

For a single-parameter, no-output-schema tool, the description adequately covers purpose, usage, and relationships. It could mention error behavior (e.g., key not found) but the deletion action is straightforward and well-contextualized within the tool set.

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

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

Schema description coverage is 100%, with the 'key' property described as 'Memory key to delete'. The tool description's mention of 'by key' adds no new semantic detail beyond the schema, so baseline score applies.

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

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

The description clearly states the core action: 'Delete a previously stored memory by key.' It uses specific verb+resource and distinguishes from siblings by mentioning pairing with remember and recall, making its purpose 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?

Explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This provides clear context and conditions, plus mentions pair with related tools, offering practical guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description explains that it fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt markdown. This adds behavioral detail on process and output format beyond the structured hints.

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, front-loaded with the core action, and each sentence adds value: purpose, process/output, and use cases. 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?

With no output schema, the description compensates by explaining the output is a single text blob ready to drop at site-root/llms.txt. It covers action, process, use cases, and output format, though it omits potential error handling or prerequisites like network access.

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 both parameters (url, max_links) already well-described. The description adds no additional parameter-specific meaning, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb+resource. It distinguishes from siblings by focusing on llms.txt generation, unlike ai_visibility_check or scan_competitor_ai_presence which assess AI visibility.

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 ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not mention alternatives or when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds behavioral context about the data returned (name, category, possible units, nutrition data) and the dependency on having the correct id. This is useful 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 two sentences, front-loads the main action, and includes a practical workflow tip. Every word adds value 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 tool with 3 parameters, strong annotations, and an output schema, the description covers the essential points: what it does, what it returns, and how to obtain the required id. It also correctly differentiates from the sibling tool. No critical information is missing.

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

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

The schema has 0% description coverage, so the description carries the burden. It clarifies that 'amount' and 'unit' are used to compute nutrition data, and that 'id' is numeric, but it does not fully explain each parameter's format or allowed values. The examples in the schema help, but the description partially compensates without being exhaustive.

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 the specific verb 'Fetch' and clearly identifies the resource (Spoonacular ingredient by id). It also distinguishes itself from sibling ingredient_search by implying that this tool retrieves details rather than performing searches, making its scope 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 explicitly states when to use the tool ('Fetch details for a Spoonacular ingredient by numeric id') and provides a direct alternative/guidance: 'Use ingredient_search to get the id first.' This gives clear contextual usage direction.

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, so the description is not required to repeat that. However, it adds no additional behavioral context—no mention of search scope, result format, pagination, 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 just three words, but this is under-specification rather than concise effectiveness. It lacks necessary detail and does not front-load any useful information beyond the tool's name.

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 there are 4 parameters with no schema descriptions and an output schema exists, the description is woefully incomplete. It fails to explain what the tool returns, how to construct a valid search, or what the output schema represents. The minimal text leaves the agent entirely reliant on guessing.

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 compensate. It does not explain what 'query', 'sort', 'number', or 'intolerances' mean or how they interact. The examples provide minimal hints but the description itself adds zero parameter-level semantics.

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

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

The description 'Ingredient search.' merely restates the tool name and title without any specific verb or resource context. It does not distinguish this tool from siblings like ingredient_information or product_search, leaving the purpose ambiguous.

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 or how it differs from alternatives. The sibling list includes similar search tools (e.g., product_search, recipe_search), but the description gives no contextual clues 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by specifying the caller scope and the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), which is useful context beyond annotations.

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

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

Two sentences: the first states the action and return fields, the second gives usage guidance. No unnecessary words, and the most important information is front-loaded.

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

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

The description covers purpose, usage, return fields, and caller scope. The optional parameter is documented in the schema, and annotations handle safety. Given the simplicity of the tool, this is complete without needing an 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% for the single optional parameter include_inactive, with a clear description in the schema. The tool description does not add any additional meaning about parameters beyond the schema's own description, 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing 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 gives explicit usage scenarios: 'review what you're monitoring before adding more' and 'find an id to cancel.' These imply when to use it relative to subscribe and unsubscribe, providing clear context even if alternatives are not named directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds value by stating the return fields (recipe ids, titles, images, nutrition summary), but it does not disclose other behavioral aspects like rate limits or error conditions. 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-loaded with the action, and every clause carries meaning. No fluff, no 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?

It covers purpose, parameters, and return shape, and an output schema exists for further details. The main gap is the lack of guidance on the relationship with the sibling tool meal_plan_week and possible default behaviors (e.g., what happens if timeFrame is omitted). Still, it is substantially complete for a read-only idempotent tool.

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

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

With schema description coverage at 0%, the description fully compensates by explaining all 4 parameters: timeFrame values ('day' or 'week'), targetCalories, diet with examples (vegetarian/vegan/paleo), and the comma-separated format for exclude. This goes well beyond the bare schema and gives the agent everything needed.

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

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

The description uses specific verbs and resources: 'Generate a Spoonacular meal plan' with explicit parameter scoping for timeFrame, targetCalories, diet, and exclude. It also lists return contents. However, it does not explicitly distinguish itself from the sibling tool 'meal_plan_week', which may also handle week plans, so it misses that sibling differentiation.

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

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

The description implies usage for meal plan generation but does not explicitly say when to use this tool versus alternatives like meal_plan_week. There are no exclusions or alternative mentions, leaving the agent to infer the appropriate context from the tool name and description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds no contradicting claims. It supplements annotations by stating the exact output shape (meals per day with ids, titles, images, nutrition totals) and that the plan matches the given filters, which are useful behavioral details. It does not discuss failure modes or rate limits, but given the strong annotation coverage, this is a solid contribution.

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

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

Two sentences, front-loaded with the action and followed by the minimal necessary detail on inputs and return format. There is no redundant or filler 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?

The tool is a simple 3-optional-parameter read-only generator with an output schema and strong annotations. The description covers the input filters and result structure adequately. A minor gap is that with required parameters = 0, it does not state defaults or behavior when optional params are omitted, but the included examples partially compensate.

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 carry the parameter semantics. It explicitly names all three parameters (targetCalories, diet, exclude) and specifies that exclude uses comma-separated ingredients, adding real meaning beyond the bare schema. It still leaves some ambiguity around accepted diet values and targetCalories units, but the core semantics are present.

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

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

The description opens with 'Generate a Spoonacular 7-day meal plan' – a specific verb and resource – and enumerates the filtering criteria (targetCalories, diet, exclude) plus the output composition. This clearly distinguishes it from generic meal-plan tools like sibling meal_plan_generate by specifying the 7-day span and per-day nutrition totals.

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 a weekly-planning use case through '7-day meal plan' and 'meals per day,' but it does not provide explicit when-to-use/when-not-to-use guidance, nor does it name alternatives such as meal_plan_generate for single-day plans. Thus the guidance is only implied.

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 reveals important behaviors not captured by the annotations: the claim_token mechanism for checking status later, rate limiting to 5 per identifier per day, the fact that no account is required, and that feedback is read daily and affects the roadmap. This adds substantial transparency beyond the minimal annotation hints.

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

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

The description is a single dense paragraph but every sentence provides necessary information: primary purpose, use cases, exclusions, token mechanics, rate limits, and cost. No redundancy or filler words. For the tool's complexity, this is appropriately sized and well-structured.

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

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

Given the tool's dual-mode operation (submitting feedback vs. checking a claim token), the absence of an output schema, and the need to set expectations about rate limits and scope, the description is complete. It covers all parameters, the return token behavior, and the exclusion criteria, leaving no critical gaps for an agent to misuse the tool.

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

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

The input schema already provides 100% parameter coverage, giving the baseline of 3. However, the description adds workflow-level semantics: it explains that passing claim_token alone reads the prior report status, and that context is optional but helps route feedback. This goes beyond the schema's field descriptions, so a 4 is warranted.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It precisely defines the tool's scope as feedback about Pipeworx tools and distinguishes it from sibling tools like ask_pipeworx or discover_tools, making the purpose 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 explicitly lists when to use it (bug, feature/data_gap, praise), when NOT to use it (feedback about other MCP servers), and provides a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary guidance that covers both positive and negative use cases.

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 non-destructive behavior. The description adds valuable context beyond that: data is self-aggregating from the CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This gives the agent useful expectations about freshness and privacy.

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

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

The description is a single dense paragraph that wastes few words, but the wall of text could benefit from structured bullets for the three use cases and a clearer separation between output description and caveats. It remains concise overall and every sentence earns its place.

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

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

With no output schema, the description does a solid job of explaining the return value (top tools, top packs, total call volume, and the (pack, tool, count) tuple). It also covers data source, privacy, and caching behavior, making the tool's behavior reasonably predictable. Minor gaps: no mention of pagination if results are long-lived, or how 'volume' is computed.

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 window parameter is well-documented with an enum and description. The description further enriches the meaning by explaining that shorter windows surface 'hot' trends while longer windows show steady-state demand, helping the agent choose an appropriate 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?

The description opens with a specific, vivid question ('What other AI agents are calling on Pipeworx right now?') and immediately states the concrete outputs: top tools, top packs, and total call volume. This distinguishes it from sibling tools like discover_tools, which likely focus on discovery rather than real-time usage trends.

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 three high-value use cases (discovering hot data sources, confirming canonical tool choices, and aligning with agent needs), giving clear context for when to invoke this tool. However, it does not state when NOT to use it or identify alternatives such as discover_tools, leaving minor room for improvement.

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 read-only and non-destructive, but the description adds rich behavioral context beyond them: the >3pp threshold for partition signals, the placeholder filter rule (>20% returns null), the fill check against live CLOB depth, and the caveat that realizable_edge_pp <= 0 means the arb only exists at last-trade. This gives agents a clear picture of edge-case behavior.

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

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

The description is long but densely packed with high-value information. It front-loads the primary purpose and then details modes, filters, output fields, and fill-check logic. It reads as a compact wall of text without paragraph breaks, which slightly hinders quick parsing, but every sentence earns its place.

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

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

The tool has no output schema, so the description fully takes on the burden of explaining the response structure: opportunities[] with fields, partition_check details, and the fill-check output. It also covers semantic anchor thresholds, placeholder filtering, and gives concrete examples of slugs and seed questions. For a complex, multi-mode tool, this is complete.

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

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

Schema coverage is 100%, but the description elevates the parameters by explaining the exact semantics: 'event' expects a Polymarket slug or URL, 'topic' expects a seed question, and both are optional with distinct behavior. It also clarifies what the tool does when no args are passed, making the parameter model fully understandable beyond the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by its unique focus on arbitrage detection and the three invocation modes.

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 each mode: no args for trending_scan, 'event' for a specific market, and 'topic' for cross-event scanning. It also provides recommended usage guidance ('recommended for a specific market') and points to the alternative tool polymarket_fill_risk for custom sizing, giving clear when-to-use vs 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 declare readOnly and idempotent hints, but the description adds substantial behavioral detail: 24-hour move warnings, per-sport alpha values, placeholder-slug filters, funnel diagnostics, and a 1-hour KV cache keyed on all knobs. It goes far beyond what annotations alone convey and contains 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 with uppercase headers and front-loaded purpose, but it is exceptionally long, including exhaustive model internals such as per-sport alphas and threshold gates. While each detail is relevant, the volume exceeds the 'appropriately sized' bar; a leaner version would be more 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?

There is no output schema, so the description must explain return values; it does so thoroughly by specifying by_segment, top-level fields, diagnostics, cached behavior, and Fed exclusions. For a tool of this complexity, the description is complete and self-sufficient.

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% for all 9 parameters, so baseline is 3. The description adds value beyond schema by explaining slippage defaults in real-market terms ('20-50bp per trade'), clarifying that min_partition_leg_kelly applies per-leg rather than at parent level, and noting that caching is keyed on all knobs.

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

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

The description opens with a specific verb+resource+output: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself by detailing three response segments and five model families, making its scope unmistakable and differentiated 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 clearly states its intended use case: 'Built for "what should I bet on today"' and 'agents discover opportunities without paging hundreds of markets.' It does not explicitly name alternatives or exclusionary conditions, so it stops short of a 5, but the context is unambiguous.

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 read-only and non-destructive behavior, and the description goes beyond by explaining response structure, snapshot TTL (60-day), cache-miss behavior, and that decay is computed on daily closes not intraday. It also clarifies edge_pp_net sign semantics, adding significant contextual depth.

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 structured into purpose, args, response, and limits, with the core question front-loaded. While verbose, each sentence carries essential information for a tool with no output schema, and the use of labeled sections makes it scannable.

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

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

With no output schema, the description fully documents the return structure (tracked[], expired[], snapshot_dates[]) and their semantics, including field meanings and limitations like lifespan_days and snapshot gaps. This makes the tool's behavior predictable without additional 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% with descriptive parameter documentation. The description repeats default values and adds 'snapshot family' context for window, but does not meaningfully extend the schema's semantics. This meets the baseline for full schema coverage.

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 function: edge persistence and decay telemetry from daily snapshots, answering whether an edge is shrinking. It specifies the resource (polymarket_edges snapshots) and distinguishes itself from sibling tools by focusing on temporal decay rather than current edges.

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 a clear use case ('Answers how long has this edge existed and is it shrinking?') and defines the scope without naming explicit alternatives. It lacks direct 'when not to use' exclusions, but the context is sufficiently clear for an agent to select it 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?

Annotations already declare readOnlyHint=true, and the description adds rich behavioral context: 'walks the ladder,' returns slippage_pp, shares_filled, verdict values, per-leg fill detail, and 'forced_directional_risk naming the legs most likely to strand you unhedged.' It also warns about partial basket fills converting an arb into an unhedged directional position, which is a crucial safety disclosure beyond the read-only annotation.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then uses uppercase labels (SINGLE-MARKET, BASKET, USE THIS) to organize distinct sections. Despite its length, it avoids redundancy and packs a large amount of essential information into a structured and readable format.

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

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

Given no output schema, the description thoroughly lists all returns for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.). It also explains edge cases like forced_directional_risk and the risk of partial fills, making it highly 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 coverage is 100%, but the description adds substantial meaning beyond the schema. It clarifies size_usd interpretation per mode: 'max spend on buys, target proceeds on sells' in single-market, and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains the side default for basket mode (auto from partition sum), which is not in the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' which separates it from tools like polymarket_edges or 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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (SINGLE-MARKET vs BASKET) and when each is appropriate, plus the risk rationale for partial fills and thin books.

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 readOnlyHint annotations, the description discloses critical behavioral traits: compatibility_warning conditions, temporal alignment significance, skipped_cross_type/subtype counters, and the caveat that pre-mapped shortcuts often return warnings. This adds substantial value and shows the tool's limitations and edge cases.

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 front-loaded: it leads with purpose, then modes, response format, and safety fields. Every section conveys essential information for correct interpretation, but the length is notable and could be trimmed slightly without losing key 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?

Despite no output schema, the description fully covers the response structure (leg-by-leg prices, top_spreads_pp), edge cases (compatibility_warning scenarios, temporal_alignment), and diagnostic counters. It is complete enough for an agent to understand what the tool returns and how to interpret unusual 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?

The schema already documents all 3 parameters with 100% coverage, but the description adds the two-mode structure, the full list of 10 pre-mapped topic values, and clarifies override behavior for explicit ticker/slug parameters. This enriches parameter meaning beyond basic schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific output details and two operation modes. This distinguishes it from sibling tools like polymarket_arbitrage that focus on a single venue or different comparisons.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug) and warns that most pre-mapped topics are not tradeable, indicating when NOT to rely on results. It lacks direct comparisons to alternative sibling tools, but the context is sufficient for an AI to determine 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by enumerating the returned fields (title, UPC, brand, ingredients, nutrition facts, image URL) and specifying the 'branded grocery product' domain, going beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loads the action, and every word serves a purpose. There is no redundancy or filler, and it is easy to scan.

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 required parameter), the existence of an output schema, and the strong annotations, the description provides all necessary context. It covers the input, the output highlights, and the product domain, making it fully adequate for an agent 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?

The input schema only specifies 'id' as a number with no description. The description compensates by explaining that the id is a Spoonacular numeric identifier for a branded grocery product, adding meaningful context about the parameter's origin and purpose despite the schema coverage being 0%.

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 the specific verb 'Fetch' and identifies the resource as 'details for a branded grocery product by Spoonacular numeric id.' This clearly distinguishes it from sibling tools like product_search (which searches) and ingredient_information (which targets ingredients).

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

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

The description implies the use case: call this tool when you have a numeric product id for a branded grocery product. It does not explicitly name alternatives or exclusions, but the context is clear enough for a simple lookup tool.

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, providing a clear safety profile. The description adds no behavioral context beyond 'branded'—no mention of result behavior, limits, or data source. It fails to build on 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?

At two words, the description is under-specified rather than concise. It is short but lacks necessary details, so it fails to earn its place as a functional description.

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 a 5-parameter tool with no schema descriptions, the description is severely incomplete. It does not explain search behavior, filter semantics, or how it differs from sibling tools. The output schema exists but does not compensate for the lack of textual 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 description coverage is 0% and the description provides no explanation of the parameters. The schema only includes an example, not semantic descriptions. The description does not help the agent understand what number, offset, maxCalories, or minCalories mean.

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 'Branded product search' identifies the tool as a product search function, adding the modifier 'branded' which gives some specificity. However, it is vague about what 'branded' means and does not distinguish it from sibling tools like product_information or ingredient_search. It stops just short of being a tautology.

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 use cases, prerequisites, or exclusions are provided. The agent is left to guess based on the tool name alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating scoping ('Scoped to your identifier') and the listing behavior when key is omitted. This goes beyond the structured annotations without contradicting them.

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

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

Four sentences, each serving a distinct purpose: main function, use case, scoping, and companion tools. No redundancy, front-loaded with the action, and every sentence earns its place.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, scoping, and relationships to sibling tools. The schema and annotations handle the remaining details, so there are no significant 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 describes the key parameter well (100% coverage), so the baseline is 3. The description adds extra meaning by reinforcing the omit-to-list behavior and providing examples of key contents (ticker, address, notes), which helps the agent understand what keys are useful.

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all saved keys when the key argument is omitted. It distinguishes itself from sibling tools by explicitly naming remember and forget as its counterparts.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples like the user's target ticker or research notes. It also names alternative tools ('Pair with remember... forget to delete'), making the usage context complete.

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?

Despite readOnlyHint=true, the description transparently discloses that setting mark_read:true mutates read state, and notes that polling is safe. It also reveals the persisted feed nature and the payload structure, adding substantial 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?

Three sentences, front-loaded with the main purpose, and every sentence earns its place—covering return value, filtering, side effects, and external access. No fluff.

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

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

With no output schema, the description covers the return format (source, citation_uri, raw payload), filtering, side effects, and polling behavior. It is thorough for a read-oriented tool with 5 optional params.

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 enriches key parameters with examples ('sec_8k'), clarifies 'since' semantics, and explains the side effect of mark_read. It does not mention limit or unread_only explicitly, but those are well-described in 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing this tool from siblings like recent_changes or list_subscriptions. It also specifies what each alert carries (source, citation_uri, raw payload).

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

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

Provides clear context on when to use (fetching recent alerts from a feed) and how to filter, along with an explicit alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly mention alternative tools or when not to use the tool, so it's not a 5.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the multi-source fan-out, fallback logic (GDELT preferred, GNews on rate-limit/5xx), USPTO API sunset causing soft-fail, and the output structure. This is valuable operational context that annotations don't cover.

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

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

The description is dense but well-structured, starting with example queries, then functionality, source details, fallback, return structure, and an alternative. Every sentence adds value, though the opening quoted examples are slightly redundant with the functional statement.

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 data sources, fallbacks, time windows), the description is comprehensive. It explicitly describes the return shape (changes[], total_changes, citation URIs), fallback behavior, API sunset limitation, and references the key alternative tool. No output schema exists, so this description carries the full burden and succeeds.

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 already covers all three parameters with rich descriptions (e.g., `since` includes ISO/relative examples and recommended values). The description adds little beyond the schema—it restates ticker/CIK and confirms only 'company' is supported, but doesn't introduce new parameter 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 clearly identifies the tool as a change feed for companies over a time window, with concrete example queries ('What's new with X', 'latest on Y'). It specifies the resource (company changes) and distinguishes from sibling entity_profile by explicitly directing users there for static profiles.

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

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

It provides explicit usage guidance: example queries, intended use cases, and explicitly says 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior between GDELT and GNews, offering clear when-to-use 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it specifies what data is returned and how the includeNutrition parameter toggles additional data, going beyond the structured hints.

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-loaded with the primary action, and every sentence contributes value. No redundancy or filler.

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

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

Given the simple get-by-id nature, an output schema exists (so return structure is covered), and the description lists the key fields and optional parameter. It is sufficiently complete for an agent to select and invoke the tool correctly, though it does not mention error cases or edge conditions.

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 has 0% description coverage, but the tool description explains both parameters: 'id' is a numeric recipe identifier, and 'includeNutrition' controls whether full nutrition data is returned. This adds clear meaning beyond the raw 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 a specific action ('Fetch full details') and resource ('Spoonacular recipe by numeric id'), and lists the returned fields. This distinguishes it from sibling tools like recipe_ingredients or recipe_summary that focus on subsets.

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?

Usage is implied through the phrase 'full details' and the field list, suggesting that this tool is for comprehensive recipe data. However, it does not explicitly mention alternatives or provide when-to-use/when-not-to-use guidance relative to the many sibling recipe tools.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context about the output fields and cost unit (US cents), which goes beyond the annotations and helps the agent anticipate results.

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

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

The description is extremely concise, using two sentences that front-load the primary action and parameter. It avoids unnecessary detail and every word contributes to understanding 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?

For a simple one-parameter, read-only tool with a well-defined output schema and comprehensive annotations, this description is complete. It specifies the parameter purpose and return fields, making it sufficient 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?

The schema only states the id is a number with no description. The description clarifies that id refers to a Spoonacular recipe, but does not detail its source or format. This adds some meaning but leaves room for more explicit 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 clearly states the tool's function: fetching the ingredient list for a Spoonacular recipe by id. It lists the specific data returned (name, amount, unit, image URL, cost in cents), distinguishing it from sibling tools like recipe_nutrition 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?

Usage is implied: when you need ingredient details for a recipe. However, it does not explicitly mention when not to use this tool or point to alternatives for different needs, such as recipe_price_breakdown for cost details.

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, so the safety profile is clear. The description adds context about the return content (calories, macros, percent daily values), but does not disclose any potential edge behaviors (errors, rate limits, or response formats) beyond what the output schema already presents. This is baseline value-add given 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 two concise sentences that immediately state the purpose and then detail the return contents. There is no fluff or unnecessary information, and the key actions are front-loaded.

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

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

Given the tool has a single parameter, an output schema, and strong annotations, the description covers the essential usage: what to pass (a recipe id) and what to expect (nutrition breakdown). It is sufficient for an agent to correctly select and invoke the tool, and it differentiates among many recipe-related 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?

With 0% schema description coverage, the description compensates by explaining that `id` refers to a Spoonacular recipe id. This gives semantic meaning to an otherwise bare numeric parameter, though it does not provide additional constraints or examples beyond the schema's existing sample.

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 action ('Fetch') and resource ('full nutrition breakdown for a Spoonacular recipe'), with a specific scope (by `id`). It distinguishes from sibling tools like recipe_ingredients or recipe_taste by explicitly mentioning calories, macros, and per-nutrient values.

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: when a full nutrition breakdown is needed. However, it does not provide explicit exclusions or name alternative tools for different nutritional needs (e.g., recipe_ingredients for just ingredient lists), so it lacks the full when/when-not guidance of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds value by explaining the 'estimated' nature and exact return contents (per-ingredient price in US cents, total estimated cost per serving). This goes beyond what the annotations alone 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?

The description is exactly two sentences, front-loaded with the primary action and resource, and contains no filler. Every phrase earns its place, and the return format is stated efficiently.

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

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

This is a simple read-only tool with a single parameter and an output schema available. The description sufficiently covers what the tool does and what it returns, and it does not need to explain the return schema in detail since that is structured elsewhere.

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 has one undocumented `id` parameter (0% schema description coverage). The description clarifies that `id` refers to a 'Spoonacular recipe', which is minimal but helpful. However, it does not elaborate on expected id format or validation, leaving the agent to infer from the example 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?

The description opens with a specific verb ('Fetch') and a clear resource ('estimated ingredient cost breakdown'), scoped by recipe `id`. This distinguishes it from sibling tools like recipe_information or recipe_ingredients, which focus on other aspects of a recipe.

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 clearly implies when to use this tool: when you need the ingredient cost breakdown for a given recipe ID. It does not explicitly name alternatives or exclusions, but the focused wording provides enough context for an agent to select this tool over siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive hints. The description adds that the tool returns 'full recipe details including ingredients and instructions,' which is useful behavioral context about the response shape. It does not contradict annotations, and no extra warnings are necessary given the read-only nature.

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

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

The description is two sentences long, front-loads the core action, and includes a concrete example of tag formatting. Every sentence adds value without any fluff or 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 tool with only two optional parameters and an output schema present, the description fully covers the purpose, parameter semantics, and return content. It's sufficient for an agent to know when to use it and how to invoke it correctly.

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

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

The schema has no descriptions (0% coverage), but the description compensates by explaining both parameters: `tags` are comma-separated and demonstrated with an example, and `number` is the number of results. This gives the agent enough semantic understanding to construct valid input.

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

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

Description uses 'Fetch' as a specific verb and identifies 'random Spoonacular recipes' as the resource, distinguishing it from sibling recipe tools like recipe_search or recipe_information. It clearly states the optional filters and returns. This makes the tool's purpose explicit and unique.

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 clearly indicates the tool's primary use case—fetching random recipes—with optional tag and count filtering. However, it does not explicitly mention when to prefer this over recipe_search or other recipe query tools, nor does it state any exclusions. The 'random' keyword implies the context, but no alternative tools are named.

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 establish read-only, idempotent, non-destructive behavior. The description adds value by disclosing that filters are passed as query parameters and that the response includes concise summary fields (id, title, image, ready-in minutes), which helps set expectations beyond the annotations. It does not mention rate limits or pagination, so not a 5.

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

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

Two sentences, front-loaded with the core purpose, then a compact enumeration of filters and return fields. Every clause is informative and no words are wasted.

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 annotations and the presence of an output schema, the description adequately covers the tool's basic contract. It lists the major filter options and return fields, and the schema examples provide additional context. However, it lacks details on pagination, default result counts, or how certain filters are formatted, which keeps it from being fully complete for a complex search API.

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

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

The input schema has no explicit properties, only examples, so the description carries the burden of parameter meaning. It names many relevant parameters (query, cuisine, diet, intolerances, includeIngredients, excludeIngredients, maxReadyTime, sort) and mentions 'query params'. It does not explain value formats or syntax for more complex filters, so it is helpful but not exhaustive; baseline 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 opens with the specific verb 'Search' and identifies the resource as 'Spoonacular recipes'. It enumerates the key filtering dimensions (query, cuisine, diet, intolerances, time, sort) and clearly states the return fields (id, title, image, ready-in minutes), distinguishing this tool from sibling tools like recipe_information or recipe_random.

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 conveys that this tool is for searching recipes with rich filters, which is clear context for when to choose it. However, it does not explicitly mention alternatives or when not to use it (e.g., use recipe_information for full details), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds value by specifying the output content (title, image URL, ready time, servings) and the 'up to number' limit, providing behavioral details beyond the structured 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 a single, front-loaded sentence that states the action, source, and key output in a compact way. Every clause contributes meaning with no redundant wording.

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 only two simple numeric parameters, an output schema present, and strong annotations, the description adequately covers essential behavior. It mentions the source (Spoonacular) and the return fields, though it leaves minor details like default `number` or empty-result behavior unspecified, which are not critical for basic usage.

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 text gives meaning to both parameters: `id` is identified as the source recipe identifier, and `number` is described as the maximum number of returned recipes. This compensates for the 0% schema description coverage, though it does not specify a default value for `number`.

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

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

The description uses a specific verb ('Fetch') and a clear resource ('Spoonacular recipes similar to a given recipe by id'). It also lists the return fields (title, image URL, ready time, servings), which distinguishes this tool from sibling recipe 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 clearly implies when to use the tool: when you have a recipe id and want similar recipe recommendations. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to guide an agent among the many recipe_* sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by stating the return content (recipe title and a 1-2 sentence description), which goes beyond the schema's type information. No 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?

A single, front-loaded sentence with the verb and resource first, then the return format. No filler 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's simplicity (one required parameter, strong annotations, output schema present), the description adequately covers purpose, parameter, and return semantics. No significant 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 has 0% description coverage, so the description carries the burden. It clarifies that the id parameter refers to the Spoonacular recipe identifier and the schema provides a concrete example, but it does not explain id format, source, or validity constraints. This is minimal but sufficient for a simple numeric ID.

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 ('Fetch') plus a clear resource ('short human-readable summary paragraph for a Spoonacular recipe by id') and explicitly states the return value. This distinguishes it from sibling tools like recipe_information or recipe_ingredients, which have different scopes.

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 clearly implies the use case ('short human-readable summary') and the return format, giving context for when to use it (quick overview). However, it does not explicitly mention alternatives or when-not-to-use, so it stops short of a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by enumerating the specific scores returned (sweetness, saltiness, etc.) and noting the optional normalization to 0-100. This goes beyond the annotations and helps the agent understand what to expect.

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 long, front-loaded with the main purpose, and contains no fluff. Every sentence adds value, making it very concise and 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?

The tool is simple with only two parameters and an output schema exists, so the description doesn't need to explain return format. It covers the purpose, parameters, and output structure (scores list plus normalization). It could mention error conditions or prerequisites, but for a read-only fetch, the description is sufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does: 'by id' clarifies the id parameter is the recipe id, and 'Optionally normalize scores 0–100' explains the normalize boolean parameter. No additional detail is needed beyond what is provided and inferred from 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 function: 'Fetch taste profile scores for a Spoonacular recipe by id.' It uses a specific verb ('fetch'), identifies the resource ('taste profile scores'), and distinguishes itself from sibling tools like recipe_nutrition or recipe_summary by focusing on taste dimensions.

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?

Usage is implied: the tool should be used when you need taste profile scores for a recipe. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or conditions. Given the many recipe-related siblings, more explicit guidance would be helpful.

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 (idempotentHint=true, destructiveHint=false), the description adds critical behavioral detail: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This explains scoping and retention semantics, which are not conveyed by the annotations. No contradiction with annotations.

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

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

The description is four sentences, each adding distinct value: purpose, usage trigger, storage semantics, and companion tools. It is front-loaded with the primary action and includes no filler or redundant information. Every sentence earns its place.

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

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

For a simple 2-parameter write tool with no output schema, the description covers purpose, usage context, persistence rules, scoping, and companion tools. Annotations handle safety (idempotent, non-destructive). The description is complete enough for an agent to correctly select and invoke the tool without 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 coverage is 100% (both key and value described with examples), so baseline is 3. The description adds meaning by explaining the key-value pair model, scoping by identifier (key uniqueness per user), and providing domain examples for values ('findings, addresses, preferences, notes'). This clarifies how to choose keys and values, going slightly 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 function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data' as key-value pair), and distinguishes from siblings by explicitly pairing with 'recall' (retrieve) and 'forget' (delete), making its unique role 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 when-to-use guidance with concrete examples: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It also differentiates from recall and forget by stating 'Pair with recall to retrieve later, forget to delete,' and clarifies persistence context (authenticated vs anonymous) that affects when memory is reliable.

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 read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond that: it states the tool cascades through several internal lookup endpoints, and details the specific return payloads (ticker, CIK, company_name, RxCUI, ingredient, brand, citation URIs), which are not evident from annotations alone.

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 information-dense and well-organized, starting with example queries and a clear purpose statement. It uses structured formatting for supported types. Slightly long, but every sentence contributes useful information, so minor deduction only for 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?

Despite lacking an output schema, the description fully specifies what will be returned for each entity type, including example input formats and citation URIs. It covers the two supported types exhaustively and explains the internal behavior. No critical gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning. For 'type' it enumerates and clarifies the two values, and for 'value' it explains accepted formats per type (ticker, CIK, name for company; brand/generic for drug), plus auto-disambiguation. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool resolves user-spoken entity names to canonical/official identifiers, with specific examples like ticker, CIK, RxCUI. It uses a specific verb ('resolve') and resource ('entity name to identifier'), and distinguishes itself from sibling tools like compare_entities and entity_profile.

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

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

It gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This is a clear directive that also implies when not to use it (when you already have an ID). It also explains that it replaces 2-3 manual lookups, providing strong contextual signals.

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?

Reveals that it probes each entity with ai_visibility_check, ranks results, and returns specific metrics (score, confidence, signal density), which adds behavioral context beyond the annotation hints. It does not mention potential external API calls or rate limits, but annotations already ensure the operation is safe and read-only.

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

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

Two concise sentences that front-load the core purpose and then efficiently add a use case and return-format details. No redundant or extraneous 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?

Covers purpose, behavior, use case, and return format, which is essential given no output schema. It relies on the schema for parameter details, which is adequate because the schema already has 100% coverage. A small gap is not explaining interactions with the 'models' parameter, but schema handles that.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-level meaning, merely restating that the first entity is the subject, a detail already present in the schema. Thus it does not compensate further beyond what the schema provides.

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

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

States a specific verb 'Compare' with a clear resource ('AI visibility across multiple entities side-by-side'). It differentiates from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking, making the tool's unique function unmistakable.

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

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

Provides an explicit use case ('competitive AI-marketing audits') with a concrete example question. It implies the alternative of using ai_visibility_check for a single entity, but does not explicitly state when not to use this tool or list other 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?

The description discloses failure behavior ('Partial failures degrade gracefully'), timing caveats (5-30s for first bundlephobia measurement), and the sources_failed field for timeouts. It also details what the return block contains, which is beyond the readOnlyHint and idempotentHint 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 each sentence serves a purpose: it defines the composite check, gives usage triggers, specifies return structure, outlines ecosystem scope, and explains partial failure behavior. It is front-loaded with the core purpose and uses clear punctuation to separate sections.

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

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

Since there is no output schema, the description compensates by specifying the exact return summary fields and per-advisory details. It also covers limitations (only NPM, bundlephobia timing) and fallback behavior, making it sufficiently complete for an agent to know what to expect.

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

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

Schema description coverage is 100% for both package and version. The description adds no substantial new meaning beyond the schema; it merely reaffirms that package is a npm package name and version defaults to latest, both already in 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 it is a composite 'should I add this npm package to my project' check that aggregates data from deps.dev and bundlephobia. The resource (npm package) and scope (NPM ecosystem) are explicit, and it distinguishes itself from siblings like scan_competitor_ai_presence by specifying exactly what it evaluates.

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 provides when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also tells agents when NOT to use it by stating 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which directs them to an alternative tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds significant behavioral context: it discloses the algorithm (BGE-base-en embeddings + cosine over 500-char overlapping windows), the 200K character cap with truncation flagging, and the return format (passages with character offsets and similarity scores). 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 concise yet information-dense: four sentences cover purpose, use case, pairing, algorithm, and limits. It is front-loaded with the action and builds logically to technical details, 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?

Given the tool's moderate complexity and lack of output schema, the description fully covers what an agent needs: return values (passages, offsets, scores), behavioral constraints (cap, truncation), and integration with a sibling tool. It is complete for selection and 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%, so baseline is 3. The description adds value by clarifying the 'text' parameter as the fetched record, providing example natural-language queries for the 'query' parameter, and explaining the 'limit' behavior via 'top-N passages.' It reinforces schema meaning without redundancy.

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 a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from sibling tools by emphasizing that the input is text already pulled, not a global search, and explicitly pairs with ask_pipeworx_grounded. The title and name are also complemented by the description.

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 when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative/complement (ask_pipeworx_grounded) and explains the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear contextual guidance.

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

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

Adds extensive behavioral context beyond annotations: requires Pipeworx OAuth account, anonymous/BYO cannot persist, SMS must be verified with a 10/day cap, webhook signing secret returned once, HMAC verification details, and auto-disable after 10 failing runs. No contradiction with idempotentHint or openWorldHint.

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?

Dense but well-organized; purpose and return value are front-loaded. The long paragraph is justified by the detailed type and delivery options, though bullet formatting could improve readability.

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

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

Covers prerequisites, return value, all supported types, delivery channels, verification steps, rate limits, webhook security, and failure behavior. Since there is no output schema, the description appropriately explains key response fields like the one-time webhook secret.

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 meaningful real-world examples and semantics beyond the schema, such as 'items:["5.02"] = officer change' and 'topic:"fed"', which help the agent select correct parameter values.

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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb and resource, and distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides clear context for use: proactive monitoring of live-data events, with delivery channel choices and account prerequisites. It implies consumption via recent_alerts and mentions the always-on feed, but does not explicitly name alternatives or state when not to use subscribe.

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 covered. The description adds useful behavioral context beyond annotations: it returns category-bucketed examples with tool+argument shapes, it draws from the live catalog, and it can be called with no arguments or a topic. This enriches the agent's understanding without contradicting any annotation.

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 long but front-loaded with common question phrasings, then moves into the output format and usage. Every sentence contributes: the synonym list helps the agent recognize user intent, the return explanation sets expectations, and the 'Use this FIRST' directive is actionable. It is slightly longer than the minimal two-sentence ideal, but appropriate for the density of information.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, return value (categories, tool+argument shape), usage variants (no-arg vs. topic), and place in the overall workflow (use first, learn meta-tools). There are no significant gaps; the agent knows exactly what to expect and when to call it.

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

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

Schema coverage is 100% for the single optional parameter, so the schema already documents 'topic' with allowed values. The description adds value by showing concrete examples ('finance', 'pharma', 'betting'), explaining the default behavior when omitted ('Call with no arguments for the full spread'), and grounding the parameter in the tool's purpose. This exceeds the baseline 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 identifies this as the onboarding entry point: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the exact action (returns category-bucketed example questions), the resource (Pipeworx), and the deliverable (each question paired with the exact tool + argument shape). This strongly distinguishes it from sibling tools 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 provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter and the default no-argument behavior, giving the agent a clear decision path for when to invoke this tool versus 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?

The description adds valuable behavioral context beyond annotations by disclosing that the row is deactivated (not deleted) and that historical events stay available. It also explains the ownership constraint. These details go beyond the annotations' safety hints. 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 highly concise, with two sentences. The first sentence front-loads the action, and the second provides essential behavioral context. No redundancy or 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?

For a simple one-parameter tool with good annotations, the description sufficiently explains the key behavioral outcome (deactivation not deletion), ownership constraints, and points to recent_alerts for historical events. It does not need to detail return values since no output schema exists. Minor details like repeated cancellation behavior are covered by the idempotentHint annotation.

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 already provides full coverage of the single id parameter, including its source ('returned by subscribe'). The description merely says 'by id' and adds no additional syntactic or semantic detail, so it adds minimal 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 'Cancel a subscription by id' with a specific verb and resource. It also distinguishes the tool from siblings by explaining that subscriptions are deactivated rather than deleted, and by mentioning ownership enforcement.

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 useful context: ownership is enforced (you can only cancel your own subscriptions) and historical events remain available via recent_alerts, which implies an alternative tool. However, it does not explicitly name subscribe or list_subscriptions as related tools or state when not to use this tool.

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, and non-destructive behavior, so the description adds value by disclosing the return format (verdict types, actual value with citation, reasoning) and the dual-path execution behavior. It does not mention potential latency or edge cases, but the added context is meaningful.

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-organized: opening query phrases, clear usage statement, path breakdown, return details, and a closing efficiency note. Every sentence adds value and the structure is front-loaded with the most operative 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 tool's complexity (two processing paths, specific return values) and the absence of an output schema, the description adequately covers expected behavior and outputs. It does not enumerate all possible verdict edge cases or failure modes, but for a claim-verification tool, it is sufficiently complete.

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

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

Schema coverage is 100% with good param descriptions, but the description enhances both params: 'claim' is given example phrasings, and 'tolerance_pct' is explained in context ('exact percent-delta math', 'overrides the tolerance implied by the claim wording'). This exceeds the baseline for fully covered schemas.

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: natural-language claim verification against authoritative sources. It provides a specific verb ('verify', 'fact check', 'confirm or refute') and resource (authoritative sources), and distinguishes it from siblings by framing it as a claim-checking tool that replaces 4–6 sequential calls.

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 usage guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (structured SEC EDGAR path) and other claims (grounded pipeline), giving the agent a clear decision rule for when and how to invoke.

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 establish this as read-only, idempotent, open-world, and non-destructive. The description adds behavioral context by specifying that it returns 'paired wine types and specific product recommendations with name, price, and description', which goes beyond the annotations but doesn't introduce new safety concerns. No contradictions.

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

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

Two sentences: first sentence states purpose and parameters, second describes the return. Front-loaded, no fluff, examples embedded inline. Efficient and 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?

For a 2-parameter, read-only tool with output schema present and strong annotations, the description covers the core functionality, parameters, and return type. It is complete enough for an agent to decide and invoke correctly. No significant 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?

With 0% schema description coverage, the description compensates by explaining that `food` is a dish or ingredient and `maxPrice` is an optional filter. It provides examples ('salmon', 'steak' with maxPrice 50) that clarify parameter usage, though it doesn't specify units or behavior for maxPrice.

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 the specific verb 'Fetch' and clearly identifies the resource: 'wine pairing suggestions for a food dish or ingredient', with examples. It clearly communicates the tool's function but does not explicitly differentiate from the sibling tool 'wine_recommendation', so it stops short of full differentiation.

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 its usage context—when you need wine pairing suggestions for a specific dish—but provides no explicit when-to-use or when-not-to-use guidance, and does not mention alternatives like 'wine_recommendation'.

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 establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the return fields (product name, price, average rating, description) and the optional filter parameters, which are not fully implied by the annotations alone.

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-loaded with the action and an example, with no redundant phrases. Every sentence contributes to understanding the tool's purpose and parameters.

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, the presence of an output schema, and the rich annotations, the description is complete. It covers the purpose, parameters, and return values, and does not need to explain output format detailed in the 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It names all four parameters and gives each a semantic role: 'wine type name', 'minRating', 'price target', and 'number of results'. This adds meaning beyond the raw schema names, although it does not specify formats or constraints (e.g., price string 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 states the tool fetches specific wine product recommendations by wine type name, using a specific verb ('Fetch') and resource ('wine product recommendations'). It is well-distinguished from sibling tools like wine_pairing, which focuses on pairings rather than product recommendations.

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

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

The description provides clear context for when to use the tool: when you have a wine type name and want product recommendations, with optional filtering by rating, price, and number. It does not explicitly mention alternatives or exclusions, but the use case is unambiguous and self-contained.

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