Data Govt Nz

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: cost implications ('you pay Anthropic directly for those calls'), key pass-through behavior, and the exact response structure ('per-model {score, confidence, signals, raw_response} + a combined view'). This is rich context, though it does not cover rate limits or error 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 concise: three sentences that cover purpose, mode selection, cost, response shape, and use cases. It is front-loaded with the main operation and meaningful details without fluff. Every sentence adds value.

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

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

Despite having no output schema, the description explicitly lists the return fields ('score, confidence, signals, raw_response') and a combined view. It also covers defaults, cost, key requirement, and use cases. This is complete for an agent to select and invoke the tool correctly, given the simple parameter schema and read-only annotations.

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 each parameter described. The description adds extra semantics: 'Default model is Workers AI Llama-3.3-70b (free)', 'pass _apiKey to also probe Anthropic', 'Omit for just workers-ai', and 'Helps disambiguate common names' for context. These override or clarify defaults and conditions, going 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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It includes a specific verb ('probe'), target resource ('LLMs'), and output metric ('score visibility (0-100)'). This distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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 AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional Anthropic key and the default free model. However, it does not explicitly mention when not to use this tool or alternatives, so it lacks full exclusion guidance.

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

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

Annotations already carry readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is established. The description adds genuine behavioral context beyond that: the tool 'fills arguments' autonomously and returns a 'structured answer with stable pipeworx:// citation URIs,' disclosing the delegation model and return format. It omits failure/fallback behavior, but given strong annotation coverage the bar is lower and the disclosure is adequate.

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

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

The most important directive ('PREFER OVER WEB SEARCH') is front-loaded, and every subsequent element — domain list, routing behavior, trigger phrases, examples, alternative routing — performs distinct work. It is long, but the length is earned for a router covering 5,798 tools; the only minor redundancy is 'START HERE for most questions' reinforcing the opening.

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-required-parameter router with no output schema, the description covers scope, invocation triggers, return format (structured answer with citation URIs), and the key alternative (deep_research). The notable gap is silence on how the base tool relates to its close siblings ask_pipeworx_beta and ask_pipeworx_grounded, and no guidance on out-of-scope or unanswerable questions. Still, it is complete enough 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?

Schema coverage is 100% and the schema already documents all six parameters as aliases of the required 'question,' so repetition is unnecessary. The description adds value beyond the schema by teaching the agent what a well-formed question looks like: trigger-phrase patterns plus six concrete examples spanning unemployment, SEC filings, adverse events, patents, weather, and clinical trials. The domain list also signals the content scope expected in the parameter.

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

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

The description states a specific verb+resource: it 'Routes the question to the right one of 5,798 tools across 1517 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' The enumerated domains (SEC filings, FDA drug data, FRED/BLS, USPTO, ATTOM, clinical trials, etc.) sharply delimit what this tool does, and naming the sibling deep_research explicitly prevents confusion.

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?

Opens with a hard precedence rule ('PREFER OVER WEB SEARCH'), then gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete examples, and an explicit alternative: 'use deep_research (free account)' for broad/multi-part questions. The agent is told both when to use this tool and when to route elsewhere.

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

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

Beyond the annotations, the description discloses that this is an experimental edge, that candidate routing improvements are enabled live only while under test, that no candidate is currently active, and that it is a full working router with no fallback. This is rich, non-obvious behavioral context that an agent needs to calibrate expectations.

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

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

Every sentence earns its place: identity/equivalence, active-candidate status, usage instruction, comparison purpose, and operational guarantee. The description is front-loaded and contains no 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?

The description covers the tool's purpose, experimental status, current behavior, usage intent, and response-shape equivalence, which is strong given the annotations and no output schema. It relies somewhat on the referenced ask_pipeworx tool for full understanding of what arguments look like, but it is 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?

Schema description coverage is 100%, so the baseline is 3. The description only repeats that arguments match ask_pipeworx and does not add meaning about the required question parameter or the aliases beyond what the schema already states.

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 beta universal router with the same 5,798 tools, arguments, and response shape as ask_pipeworx. It is not tautological and explicitly distinguishes this experimental variant from the stable sibling by naming the candidate-improvement mechanism.

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 to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It does not cover explicit when-not-to-use conditions or alternatives beyond the implied stable router, 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the exact return structure on both success and refusal, listing specific refusal reasons such as not_in_source, no_tool_match, tool_error, data_truncated, and llm_error. It also transparently states the extra LLM call cost compared to ask_pipeworx, which is material behavioral context.

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 but every sentence adds value: it establishes the mode, the routing behavior, the output contract, the refusal behavior, usage criteria, and the cost tradeoff. It is front-loaded with the core purpose and returns key operational details without fluff.

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

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

Despite lacking an output schema, the description fully explains the return shape and refusal reasons, making the tool usable without additional documentation. It clarifies the relationship with ask_pipeworx and provides decision criteria. The description is comprehensive for an agent to invoke the tool correctly and interpret results confidently.

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 a clear description of the 'question' parameter and its aliases (query, q, prompt, text, input). The description does not add parameter-level detail beyond what the schema offers, but it does contextually frame that the question will be routed to the right tool. Baseline 3 is appropriate because the schema carries the parameter documentation burden effectively.

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

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

The description states a precise verb ('answer mode') with a clear resource (Pipeworx knowledge base) and explicitly differentiates itself from ask_pipeworx by being 'hallucination-resistant' and grounded in tool results. It names the routing mechanism and extraction behavior, so an agent can clearly understand what the tool does and how it differs from siblings.

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

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

The description provides explicit usage guidance: use when answers will be quoted, cited, or acted on, and for high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also explicitly says to prefer ask_pipeworx for casual lookups due to the extra LLM call cost, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description goes far beyond by detailing resolver contract, safety short-circuits, closed-market behavior, wide-spread warnings, and resolution-rule risk. No contradiction found.

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 very long but organized with uppercase section headers. While information is dense and valuable, it is overly verbose and could be trimmed significantly. It is front-loaded with the main purpose but several details are arguably excessive.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers response shapes, resolver contract, parent event extraction, news fallback, safety statuses, and cancellation rules, giving the agent all necessary context to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds context about what a market input can be (slug/URL/question), but that duplicates schema. It doesn't clarify depth or include_raw beyond schema, 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 it 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which is a specific verb+resource. It distinguishes itself from siblings by focusing on Polymarket bet resolution and category-specific fan-out, making its unique purpose evident.

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

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

Provides explicit guidance: Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It does not mention when-not-to-use or alternative tools, so it lacks exclusions, but the usage context is clearly stated.

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 read-only, open-world, idempotent, and non-destructive traits. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and the return of paired data plus citation URIs. 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 longer than average but every sentence serves a purpose: trigger phrases, data details, outputs, and advantages. It is front-loaded with usage cues and remains logically organized. Slightly verbose but not wasteful, warranting a 4.

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 naming the returned structure (paired data + citation URIs), explaining sorting behavior, data sources, and edge cases (fiscal year handling). It is fully self-contained for an agent to decide when and how to invoke it.

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

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

Schema covers both parameters with descriptions and enum, achieving 100% coverage. The description elevates this by explaining what each type actually retrieves (company financials vs. drug stats) and providing concrete examples for values. This adds meaning beyond the schema's basic field 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 opens with explicit trigger phrases and states the exact function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It clearly distinguishes from sequential single-pack lookups, 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?

Provides clear when-to-use guidance: any comparison phrasing like 'X vs Y' or 'rank these companies'—with explicit instruction to ALWAYS PREFER this over sequential lookups. It also implies the alternative (sequential lookups) by saying it replaces 8–15 of them.

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

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

Annotations already mark the tool as read-only and idempotent; the description adds substantial behavioral context: account requirement, paid tier, non-open-web nature, findings packet structure with verbatim evidence + confidence + source + fetched_at + pipeworx:// citations, explicit gaps[] that are never invented, contradictions[] for standard/thorough, always-fetchable citation_uri, semantic excerpting of large records, and latency expectations. This far exceeds what annotations alone provide.

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

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

The description is severely bloated and repetitive. Sentences like 'For a single lookup use ask_pipeworx instead. Also useful for fact-checking broad claims (see validate_claim).' and '(one LLM call, not many).' are repeated multiple times, and large chunks of the opening are duplicated. It is not front-loaded cleanly: essential depth and timing details are buried after repeated filler, making the description harder to parse than it should be.

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 redundancy, every piece of information an agent needs is present: account/auth prerequisites, alternatives, input semantics, output format (findings packet, gaps[], contradictions[], hop field, citation_uri), behavior on large records, and expected latency. With no output schema, the description fully takes on the burden of explaining return values, and it does so thoroughly.

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 depth enum is well-documented in the schema. The description goes further by explaining what each depth means in execution: 'quick=3 (single hop)', 'standard=3 ... adds a gap-recovery hop', 'thorough=6 ... adds a full iterative hop', plus the paid nature of thorough. The question parameter is also contextualized as 'broad/multi-part is fine — decomposition is the point', though somewhat redundantly.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources...' and explains it decomposes questions into facets and routes them to 5,798 tools in parallel. It clearly differentiates itself from siblings: 'this is NOT open-web search', 'For a single lookup use ask_pipeworx instead', and references validate_claim.

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

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

Explicit when-to-use guidance is given: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx instead', and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' It also distinguishes depth levels and notes the paid plan requirement for 'thorough'.

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 behavioral details beyond the annotations: returns top-N results with full input schemas and curated examples, and each result is ready to call directly without a second schema lookup. This adds meaningful context not present in readOnlyHint/idempotentHint, and there is 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?

Two sentences, front-loaded with the core purpose. The first sentence is crisp; the second expands with use cases and return behavior. The long list of data domains is relevant and helps the agent understand scope without being redundant. 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 absence of an output schema, the description steps in to explain the return format (top-N tools with names, descriptions, full schemas, examples) and the direct-callability benefit. Combined with rich schema and annotations, this makes the tool fully understandable for invocation. The description covers purpose, usage, and behavior sufficiently.

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

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

Schema description coverage is 100%, and the schema itself documents aliases and provides examples. The description adds general context about the query being a natural language task description, but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by positioning it as a meta-search for discovering other tools, listing concrete domains (SEC filings, FDA drugs, etc.). This makes the tool's 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?

Provides explicit when-to-use guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists example use cases and domain coverage, giving the agent strong decision criteria for choosing this tool over direct specialized 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 mark it read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by disclosing exact data sources, soft-failure behavior for the USPTO API, expected empty sections for small-molecule-only FDA companies, sources_used/sources_failed semantics, and the resolved:false result for private companies. 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 long, but the tool is complex and has no output schema, so the density is largely justified. It front-loads example queries and the core 'one parallel call' value, then systematically covers sources, returns, failure modes, and input forms. A bit more paragraphing would improve scannability, 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?

Given that there is no output schema, the description thoroughly covers return fields, source-specific caveats, expected empty results, failure behavior, and alternative input formats. An agent has enough context to call the tool correctly and interpret results without additional lookup.

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 still adds meaningful parameter semantics: both type values behave identically, value accepts ticker/CIK/name interchangeably, CIK must be zero-padded, and names resolve via SEC EDGAR. These details go beyond the schema descriptions and prevent incorrect invocation.

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: building a full cross-source profile of a US public company from natural-language requests like 'tell me about X' or 'research Acme.' It is specific about the resource (US public company entity), the action (profile/research), and the outputs, while distinguishing itself from chaining multiple single-purpose 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?

The description explicitly tells agents to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It also gives explicit input guidance (ticker, zero-padded CIK, or company name) and describes the private-company fallback behavior, so the agent knows 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 declare destructiveHint=true and idempotentHint=true, and the description aligns with these by stating deletion. It adds practical context about the conditions triggering deletion, which goes beyond the raw annotation flags.

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 purpose, and every word earns its place. It is succinct and free of filler.

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

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

For a simple single-parameter deletion tool with strong annotations and clear usage guidance, the description is complete. It does not need to explain return values since there's no output schema, and the behavioral context is adequately covered.

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 'key' parameter, and the description reinforces its role ('by key'). With full schema documentation, the description adds minimal new meaning but enough to clarify that the key identifies the memory to delete.

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

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

The description clearly states the verb (delete) and resource (memory), and specifies the method (by key). It distinguishes itself from sibling tools like remember and recall by explicitly framing itself as the deletion counterpart.

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 ('when context is stale, task is done, or clear sensitive data'), which is strong guidance. However, it does not explicitly state when not to use or name alternative tools, though the pairing with remember/recall implies the complementary workflow.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by detailing that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which is useful contextual behavior beyond the annotations. 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 front-loaded with the core purpose, followed by process and use cases. While the 'Useful for' list adds some length, every sentence provides meaningful context. It is efficient without being overly terse.

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 lack of an output schema, the description compensates by specifying the output as 'a single text blob ready to drop at site-root/llms.txt' and the format. Combined with detailed parameter schemas and annotations, the description covers the essential context for 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?

Schema description coverage is 100%, with both parameters ('url' and 'max_links') already well-documented in the schema. The description does not add additional meaning about parameter semantics, so the 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 a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It explains the internal process (fetch, extract, emit) and distinguishes this tool from siblings by focusing on llms.txt generation specifically.

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

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

The description provides clear context with 'Useful for' scenarios (client indexing, own project, competitor auditing), making it easy to understand when to use it. However, it does not explicitly name alternatives or exclusion criteria, so it falls slightly 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=true, idempotentHint=true, and destructiveHint=false, so the safe-reading nature is covered. The description adds useful context about the data source (NZ open data catalogue) and the all_fields behavior, but does not disclose default field sets or pagination semantics beyond the schema's existence.

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 one concise sentence that front-loads the core purpose and adds a single actionable tip. There is no fluff or redundant information.

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

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

For a simple listing tool with an output schema present, the description provides a solid context: what it lists, from where, and a key parameter hint. It does not explain return formatting (output schema covers that) and limit/offset are intuitive, so overall it is complete enough for its complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains all_fields (true returns names and descriptions) but does not clarify limit or offset parameters, which are left to inference from examples. This is a partial gap in parameter documentation.

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

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

The description uses a specific verb ('list') and resource ('thematic groups/categories') tied to the NZ open data catalogue, clearly distinguishing it from sibling tools like group_show (which would show a single group) and tag_list/organization_list (which list other entity types).

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 listing all groups but does not explicitly contrast with alternatives like group_show. The tip 'Pass all_fields=true' offers a usage hint, but no explicit when-not-to-use or alternative references beyond what the name conveys.

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 minimal behavioral context (returns title, description, and optionally datasets) but does not expose any quirks or side effects beyond what annotations provide.

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

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

The description is a single, front-loaded sentence with no redundancy. It packs context (source catalogue), function, and return details 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?

Given the simple tool signature (2 params, read-only, with an output schema), the description provides enough coverage of purpose and parameters. It is slightly incomplete due to the lack of usage guidelines, but the context is adequate for a straightforward show 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?

Despite 0% schema description coverage, the description compensates by explaining both parameters: 'by ID' clarifies the required id, and 'optionally the datasets it contains' maps directly to include_datasets. This adds significant meaning beyond the bare 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 returns full detail for a thematic group by ID, listing the specific fields (title, description, optional datasets). It lacks an explicit verb like 'retrieve' or 'show', but the meaning is unambiguous and distinguishes from group_list by emphasizing full detail.

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

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

No guidance is given on when to use this tool versus alternatives like group_list or other show tools. The description implies 'use this for full detail' but does not state exclusions or when a sibling would be more appropriate.

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, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope (caller's active subscriptions). This enriches the behavioral understanding without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the purpose, followed by return fields and usage guidance. Every sentence earns its place with 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?

For a simple list tool with one optional parameter and no output schema, the description is complete. It states what it returns and when to use it, and the annotations cover safety aspects. No gaps remain.

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

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

The input schema provides 100% coverage for the single parameter include_inactive, with a clear description. The tool description does not add further parameter-specific semantics, so the baseline score of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes itself from related tools like subscribe/unsubscribe by mentioning reviewing existing subscriptions and finding an id to cancel.

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

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

Explicitly states when to use the tool: to review what you're monitoring before adding more or to find an id to cancel. This provides clear context and implies alternatives (subscribe/unsubscribe) without naming them 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 the tool as readOnly, idempotent, and non-destructive, covering the main safety aspects. The description adds the all_fields behavior (names/descriptions vs. IDs) and the specific data source, but doesn't disclose pagination behavior, rate limits, or default result size, which would enhance transparency.

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

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

The description is exceptionally concise: one sentence for purpose and one for parameter guidance. Every word adds value, and the core action is front-loaded, making it easy for an agent to quickly understand 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 list tool with an output schema and comprehensive annotations, the description covers the essential information: what is listed, where from, and how to get extended details. The only minor gap is the absence of explicit pagination semantics for limit and offset, though these are intuitive based on their names.

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 provides no descriptions for parameters (coverage 0%). The description explains all_fields (names and descriptions vs. IDs) but leaves limit and offset unexplained. Their names imply pagination, but the description doesn't confirm their role, so parameter semantics are only partially compensated.

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: listing New Zealand government organizations that publish datasets from the data.govt.nz CKAN catalogue. It uses a specific verb ('list') and resource ('organizations'), and naturally distinguishes itself from siblings like organization_show (which retrieves a single organization) and group_list (which lists groups, not organizations).

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 listing organizations but does not explicitly contrast it with alternatives like organization_show or package_list. It provides parameter-level guidance for all_fields, but lacks clear 'when to use this vs. other tools' instructions.

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 well covered. The description adds context about the optional datasets inclusion and the source system (data.govt.nz CKAN), but does not disclose potential error behavior, rate limits, or other edge-case behaviors. This is similar to the get_calls example, where annotations cover the basics and the description adds some scope context, warranting a 3.

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

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

The description is a single sentence that front-loads the key context (New Zealand open data catalogue) and directly explains the tool's purpose and optional behavior. There is no waste, and every phrase serves to inform the agent.

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 read-only tool with an output schema and clear annotations, the description is complete. It covers the entity type, the lookup method, and the optional datasets behavior. No additional return-value explanation is needed because the output schema is present, and the tool's simplicity does not require further contextual detail.

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 descriptions for its parameters (0% coverage), but the description compensates by explaining both: 'by ID' for the id parameter and 'optionally their list of published datasets' for include_datasets. This provides the necessary semantic meaning beyond the raw schema and is sufficient for an agent to understand parameter usage.

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

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

The description clearly states the tool's function: showing a full profile for a publishing organization by ID, including name, description, and optionally published datasets. It uses a specific verb+resource structure and is easily distinguished from siblings like organization_list (which lists organizations) and group_show (which shows groups).

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 implicitly conveys when to use this tool: when you have an organization ID and need detailed profile information, possibly including its datasets. It does not explicitly mention alternatives or exclusions, but the context (New Zealand open data catalogue) and the focus on a single organization by ID make the usage scenario 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 and idempotentHint=true, so safety is covered. The description adds the paginated nature and that it returns slugs/names, but it does not elaborate on pagination behavior or other edge cases. This is comparable to the get_calls calibration, resulting in a 3.

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, with the core purpose front-loaded. It avoids fluff and every sentence contributes to the tool's understanding.

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 an output schema, so return values need no explanation. The description covers purpose, usage, and basic behavior. The only minor gap is parameter semantics, but that is already scored separately; overall the description is sufficient for a simple list 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 schema has 0% description coverage, and the description only says 'paginated list' without explaining that 'limit' controls page size and 'offset' controls the starting position. The two parameters (limit, offset) remain semantically under-specified, and the description does not compensate for this gap.

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 returns a 'paginated list of all dataset slugs/names' from the 'New Zealand open data catalogue (data.govt.nz CKAN)', which is a specific verb+resource+scope. It also distinguishes itself from the sibling package_show by framing it as a precursor step: 'before fetching details with package_show.'

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

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

The description explicitly says to use this tool 'to enumerate available datasets before fetching details with package_show', providing clear context and naming a related alternative. It does not explicitly mention when not to use it (e.g., for searching, package_search), but it offers enough guidance for the primary use case.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral context such as pagination limits, default result counts, or special search syntax. With annotations covering the safety profile, the description still fails to add any new behavioral information.

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 four-word sentence with no wasted words. It is front-loaded and efficient, though extremely brief.

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 search tool with six parameters and no required fields, the description is insufficiently complete. It lacks usage guidelines, parameter semantics, and behavioral details. The presence of an output schema helps with return values, but the description still leaves significant gaps for an agent to know when and how to invoke 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?

Schema description coverage is 0%, and the description provides no meaningful explanation of the six parameters. The term 'faceted' hints at facet_field, but there is no explanation of 'q', 'fq', 'rows', 'start', 'sort', or 'facet_field'. The examples in the schema offer some hints, but the description itself does not compensate for the lack of schema documentation.

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

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

The description 'Full-text + faceted search' clearly indicates a search tool with specific capabilities. The name 'package_search' supplies the resource, making the purpose clear. It distinguishes from listing (package_list) and showing (package_show) tools, though it does not explicitly differentiate from other search tools like search_within.

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

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

No guidance is provided on when to use this tool versus alternatives such as package_list, package_show, or search_within. The description merely states what the tool does without any contextual, prerequisite, or exclusionary information.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context about the data source (NZ open data catalogue) and the response content (metadata fields, resources, license). This is consistent with annotations and provides extra behavioral clarity.

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, information-dense sentence. It front-loads the core purpose and lists the metadata fields without redundancy or unnecessary words, earning 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 lookup tool with an output schema, the description sufficiently covers the datasets scope (NZ data catalogue), the operation (full metadata by ID/slug), and the response content. The existence of an output schema means return format details are not needed in the description.

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

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

Schema description coverage is 0%, but the description compensates by explicitly stating the parameter accepts an ID or slug. The example 'nz-population-census' further illustrates a slug. This gives the agent the necessary semantics to invoke the tool correctly.

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

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

The description clearly states the tool returns full metadata for a dataset by ID/slug, listing specific fields (title, description, resources, organization, tags, license). This distinguishes it from sibling tools like package_search (which searches) and package_list (which lists all), 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 implies usage for fetching a known dataset's metadata by ID/slug, but it does not explicitly state when not to use it or recommend alternatives. There is no mention of exclusions or alternative tools, so guidance is only implicit.

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

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

The description goes well beyond the annotations, disclosing rate limits (5 per identifier per day), the claim_token mechanism for follow-up, the fact that it's free and doesn't count against tool-call quota, and that the team reads digests daily with signal affecting roadmap. These are significant behavioral traits not derivable from the minimal 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?

While the description is long (170+ words), every sentence earns its place. It's front-loaded with purpose, then flows logically into usage guidance, scope exclusions, claim_token behavior, and operational constraints. The density is appropriate for a tool with rich, non-obvious semantics.

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 low complexity but high semantic nuance, the description is complete: it covers what to report, what not to report, how to follow up, rate limits, quota implications, and processing cadence. No output schema exists, so the description's explanation of the claim_token return value fills that gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful enrichment: it explains the claim_token's dual use (filing vs. reading a reply), specifies that claim_token should be passed 'with no other arguments', and clarifies what context fields are for. It also details message best practices (specific, 1-2 sentences). 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 opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes this from sibling tools like ask_pipeworx by framing it as feedback exclusively for Pipeworx-served tools. The scope is crisply defined with concrete examples (bug, feature, data_gap, praise).

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 criteria for each feedback type and explicitly warns against using it for tools from other MCP servers, naming the alternative action ('file it with that server instead'). It even addresses edge cases like uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists') and what to avoid ('don't paste the end-user's prompt').

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 that the data is 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This adds valuable behavioral context about data source, privacy, and freshness that annotations do not cover. 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 front-loaded with the core purpose, then lists use cases and technical details. Every sentence adds value: purpose, return contents, use cases, data source/privacy, and caching. It is concise despite its length, with no fluff or repetition.

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

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

For a simple one-parameter tool, the description covers what it returns, the window options, caching behavior, and data provenance. No output schema is provided, but the description sufficiently explains the return contents (top tools, top packs, total call volume). Combined with strong annotations, the tool is fully contextualized.

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 provides 100% coverage for the single 'window' parameter, including enum values and a description. The tool description adds interpretive semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema, earning a score above the baseline of 3.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' The verb 'returns' and specific resources (tools, packs, call volume) make the purpose unambiguous. It also distinguishes itself from siblings by framing it as 'What other AI agents are calling on Pipeworx right now,' which is unique among the listed 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 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choices, and checking alignment with other agents' needs. This gives clear context on when to use it, though it does not name specific alternative tools to exclude. The absence of exclusions is a minor gap, but the use-case guidance is strong.

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 substantial behavioral context beyond the readOnly, openWorld, and idempotent annotations. It explains internal algorithms (Jaccard similarity threshold, placeholder fraction), response structure, and the fill check's interpretation (e.g., 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'). 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 well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary purpose. However, it is quite lengthy and includes detailed algorithm thresholds that might be more verbose than necessary for tool selection. Still, each sentence serves a purpose, so it earns a 4.

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 thoroughly covers return values, edge cases, and warnings. It details opportunities[], partition_check{}, fill_check behavior, and skipped_low_similarity information. This fully compensates for missing structured output documentation.

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

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

While the schema already covers both parameters 100%, the description adds significant meaning: it explains what each mode does with the parameter, provides concrete examples (e.g., 'fed-decision-may-2026'), and notes that full Polymarket URLs are also accepted for event. This enriches the schema's basic descriptions with actionable context.

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.' This clearly defines the tool's function and differentiates it from generic research or price-check tools by its unique method and output. The detailed mention of event/topic modes further narrows 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 usage instructions are provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event mode for specific markets and explicitly points to an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This covers both when and with what to use the 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description goes well beyond by detailing model families, Kelly sizing, slippage treatment, 24h-move warnings, tradeable-edge filters, caching behavior, and diagnostics to explain empty segments. This is far more transparent than 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 front-loaded with the purpose and use case, followed by structured segments for model families, response layout, and knobs. It is quite long and contains deep implementation details (e.g., alpha values, gate thresholds) that could be trimmed, but every sentence contributes meaningful context for a complex tool with 9 parameters and no output schema.

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 explicitly: top-level by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers filter behavior, caching, and why segments might be empty, making the tool fully comprehensible without requiring a separate schema or output docs.

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 rich per-parameter descriptions, so the baseline is 3. The description adds cross-parameter semantics not in the schema, such as why min_kelly does not filter partition arbs and how min_partition_leg_kelly applies to per-leg Kelly, helping the agent reason about knob interactions.

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

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

The description states exactly what the tool does: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is action-oriented, specifies the resource (Polymarket markets), and clearly differentiates from sibling tools by positioning it as a daily opportunity scanner rather than a pure arbitrage or tracking tool.

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

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

The description says it's 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' which is a clear when-to-use statement. It also provides a caveat about Fed bets being unreliable and excluded from ranking. However, it does not explicitly name alternative tools like polymarket_arbitrage or give a 'when not to use' beyond the Fed note, so it isn't a full 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?

Goes well beyond the annotations by detailing the response structure, calculation methodology (daily closes of edge_pp_net, net slippage, not intraday), interpretation of trends, and causes of snapshot gaps. This is rich, non-redundant context. 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 long but extremely well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence provides necessary information, especially given the lack of an output schema. It's front-loaded with purpose and avoids redundancy. Concision without being too terse.

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's no output schema, the description fully specifies the response fields (tracked, expired, snapshot_dates) and their semantics. It also covers limitations, data gaps, and parameter behavior. For a read-only telemetry tool with two simple params, 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 already covers 100% of parameters, so baseline is 3. The description adds meaning by explaining the 'window' as a snapshot family and clarifying defaults (days default 14, max 30; window default '1wk'). This adds enough contextual value to warrant a 4.

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 purpose: telemetry on edge persistence and decay built from polymarket_edges snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on edge age and trend, with a concrete example contrasting fresh vs. 3-week-old 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: evaluate how long an edge has existed and whether it's shrinking before trading. It also explains data availability (snapshots on cache-miss, TTL limits). However, it doesn't explicitly mention alternatives or when not to use this tool, so it's not a full 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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context: it walks the order-book ladder, returns top-of-book vs VWAP fill metrics, interprets size_usd differently by mode, returns a verdict (clean|degraded|cannot_fill), and identifies thin legs and forced directional risk. 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 densely structured into clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence contributes essential information for a complex tool with two modes and many return fields. It is not padded; the length is a function of the tool's complexity.

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

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

No output schema exists, so the description must explain return values. It does so comprehensively, listing specific fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, capture_ratio, thin_legs, etc.). It also covers edge cases like partial fills and forced directional risk, making the description fully complete for decision-making.

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 reinforces parameter meaning with mode-specific examples (e.g., 'size_usd default 1000 — max spend on buys, target proceeds on sells') and clarifies the side default in basket mode ('auto from partition sum'). While the schema already documents these details, the description adds narrative context that helps an agent reason about parameter interactions, though it does not introduce entirely new 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation. It also explains two distinct modes (single-market and basket), making the tool's 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 states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names specific sibling tools and provides exclusion logic (theoretical overround on thin books is not capturable, partial fills create directional risk). This is exactly the kind of actionable context needed.

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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: it discloses gross-vs-net fee treatment, the distinction between temporal_alignment_unknown and confirmed alignment, that unclassified legs are never paired, and that matching is keyword-based rather than source-based. This fully sets expectations about what the tool does and does not compute.

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 organized into clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes), and the lead sentence states the core purpose. Dense caveats like fee treatment and temporal alignment earn their place given the tool's interpretive complexity. Minor repetition of the identical-matcher and either-mode points keeps it from a 5.

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

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

Even though there is no output schema, the description covers the response structure, safety fields, compatibility codes, skipped-leg counters, and fee caveats in enough detail for an agent to call the tool correctly and interpret results. It also handles edge cases like unresolved temporal alignment and unclassified legs, making it complete for a complex comparison 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%, so the baseline is 3, but the description adds semantic value beyond the schema: it explains that explicit ticker/slug override the topic-mapped sides and that both modes run the identical token-overlap matcher. It also expands the `topic` enum with concrete shortcut values and clarifies that all parameters are optional together only in topic mode.

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

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

The opening sentence states a specific purpose: calculating the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly defines the two operating modes, the response content, and the condition under which the spread is meaningful. This makes it easy for an agent to distinguish the tool's core function from other market-analysis siblings.

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

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

The description gives explicit mode selection (`topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug`) and warns that pre-mapped shortcuts often return compatibility warnings and are not necessarily tradeable. It also instructs the agent to read the safety fields even when `matched_pairs>0`. It does not name sibling alternatives like `polymarket_arbitrage`, but the internal when/when-not guidance is strong.

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 safety profile is covered. The description adds useful behavioral context beyond annotations: it reveals the scoping mechanism ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual-mode behavior ('omit the key argument'). This enhances understanding without contradicting annotations.

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

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

The description is three sentences, each serving a distinct purpose: functionality, use-case motivation, and scope/companion tools. It is front-loaded with the primary action and contains zero filler.

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

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

For a simple tool with one optional parameter, strong annotations, and no output schema, the description fully covers the necessary context: what it does, when to use it, how scope works, and related tools. No significant 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?

The input schema already provides 100% parameter description coverage ('Memory key to retrieve (omit to list all keys)'). The description adds illustrative examples of key values ('user's target ticker, an address, prior research notes') but does not add substantive semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

The description opens with a specific verb 'Retrieve' and clearly identifies the resource ('a value previously saved via remember') while also covering the second mode ('list all saved keys'). It explicitly distinguishes itself from sibling tools 'remember' and 'forget' by framing recall as the retrieval counterpart.

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 tells the agent exactly when to use this tool: to look up stored context without re-deriving it. It also provides exclusions and alternatives by stating 'Pair with remember to save, forget to delete,' effectively naming when to use sibling tools instead.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds meaningful context: returned events include source, citation_uri, and raw payload; mark_read changes state for subsequent calls; the feed is persisted. This goes beyond annotations without contradiction.

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

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

Four sentences, each conveying necessary information. The first sentence states the core purpose immediately; subsequent sentences add return format, filtering, side effect, and alternative access 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?

With no output schema, the description compensates by listing return fields and payload contents. It covers filtering, marking read, and the URL fallback. All five parameters are either described or have schema coverage, and the tool's role in the subscription workflow is clear.

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 enriches semantics with an example type filter ('sec_8k') and explains the since parameter as an ISO timestamp filter. It also clarifies mark_read's effect. That 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 opens with 'Pull fired events from your subscription feed', clearly identifying the verb and resource. It distinguishes itself from sibling tools by focusing on the persisted feed and alert payloads, and even references an alternative endpoint, 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?

It states that polling works fine, suggesting a use case. It also offers a raw endpoint as an alternative access method. However, it doesn't explicitly say when not to use this tool versus other siblings, so clear context but no formal 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 mark this as read-only, idempotent, and non-destructive. The description goes beyond by revealing the fan-out to multiple data sources, the fallback mechanism (GDELT preferred, GNews when rate-limited or 5xx), and the USPTO soft-fail condition. It also explains the return structure (changes[] group by source, total_changes, citation URIs), which is not in 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 dense but well-structured, front-loaded with example queries and use cases. Each sentence adds information: source fan-out, fallback behavior, date formats, return payload, and alternative tool. It is longer than average but avoids redundancy, earning a high score rather than perfect because it could be slightly tightened.

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

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

For a complex multi-source tool, the description is remarkably complete. It covers input formats, source behavior, failure modes, and return shape. The lack of an output schema is compensated by describing the structured changes[] result and total_changes count. It also provides an explicit pointer to entity_profile for static-profile needs, making the context fully 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%, so baseline is 3. The description adds value by explaining `since` accepts both ISO dates and relative shorthand with examples ("7d", "30d", "3m", "1y"), and clarifies `value` as ticker or CIK. This is helpful context beyond the schema's basic type definitions, though the schema already covers the core 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 clearly states the tool's function: "change feed for a company in the last N days/weeks/months" and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool entity_profile by explicitly contrasting the use cases, satisfying the differentiation requirement.

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 opens with natural-language example queries that indicate when to use the tool, and explicitly says "Use entity_profile instead when you want the static profile... regardless of window." It also clarifies the fallback behavior between GDELT and GNews, providing clear usage context without needing to infer.

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, establishing safety. The description adds behavioral context by noting pagination via limit/offset and the 'most recently created or updated' ordering, which are not captured in the schema or 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, well-structured sentence that front-loads the data source and core function, then adds a use case. Every clause earns its place, with no redundancy or unnecessary detail.

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 read-only nature, the presence of an output schema, and robust annotations, the description sufficiently covers the tool's purpose, source, pagination, and use case. It is complete for the tool's complexity.

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

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

The input schema has no descriptions for limit and offset (0% coverage), so the description's phrase 'paginated by limit/offset' provides essential meaning for both parameters. However, it does not elaborate on details like default values, maximum limits, or exact semantics of offset, leaving some ambiguity.

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

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

The description clearly identifies the tool's function: listing datasets most recently created or updated in the New Zealand open data catalogue. It specifies the resource (data.govt.nz CKAN) and the pagination mechanism, which distinguishes it from generic package listing tools like package_list.

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: 'Use to monitor NZ government open data activity.' While it does not explicitly name alternatives or when-not-to-use scenarios, the intended context is well-defined and sufficient for selecting the 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?

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses key behavioral details: key-value storage scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. It also describes the mutation semantics consistent with readOnlyHint=false, adding value beyond the structured fields.

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

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

The description is four sentences, each serving a distinct purpose: what it does, when to use, how storage works, and related tools. It is front-loaded with the primary action and avoids redundant wording, making it 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 simple key-value store tool with no output schema, the description covers all essential aspects: purpose, usage triggers, persistence/scope details, and companion tools. The schema handles parameter documentation, so no critical context is missing.

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

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

Schema coverage is 100% with detailed descriptions for both key and value parameters, so the description does not need to add parameter-level detail. The mention of 'key-value pair' and examples like 'resolved ticker' adds slight reinforcement, but essentially repeats what the schema already conveys, matching 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 opens with 'Save data the agent will need to reuse later', using the specific verb 'Save' and identifying the resource as agent memory. It explicitly distinguishes from siblings by stating 'Pair with recall to retrieve later, forget to delete', clearly separating this save operation from retrieval and deletion 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 a clear 'Use when' clause with concrete examples (resolved ticker, target address, user preference, research subject), giving strong contextual guidance. It mentions related tools (recall, forget) for alternatives, but does not explicitly state when NOT to use this tool, leaving a small gap in exclusion guidance.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses degradable enrichment (EDGAR identifiers still return if GLEIF/OpenFIGI are unavailable), ambiguity behavior (returns figi_candidates and asserts nothing), and explicit unresolved-field behavior. It also explains internal endpoint cascading, none of which appears in the annotations.

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

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

The description is front-loaded with natural-language queries and the key 'use FIRST' instruction, and the SUPPORTED TYPES block is well organized. It is dense and long, but nearly every sentence carries new information rather than padding.

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

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

For a two-parameter, no-output-schema tool, the description covers return shapes (figi_candidates, unresolved, source-labelled identifiers, RxCUI citation), failure degradation, ownership output, and what not to pass in value. No critical invocation detail appears to be missing.

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

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

Although the schema documents both parameters at 100% coverage, the description substantially deepens their semantics: accepted ticker/CIK/ISIN/name input forms, drug brand/generic examples, ISIN-to-LEI behavior, and the crucial bond-issuer-name-only rule for value. This is far beyond a baseline schema-only score.

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

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

The description states the tool's job precisely: it resolves a user-spoken name to canonical identifiers (CIK, ticker, LEI, FIGI, RxCUI) that other tools require as input. It also says to use it FIRST whenever the agent has a name but needs an ID, which distinguishes it from the identity-consumer sibling tools in the context.

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 phrase 'Use FIRST whenever you have a name but need an ID' gives an explicit triggering condition, and the input instructions cover supported entity types and value formats. It does not name alternative sibling tools or list when-not-to-use conditions, so it falls just short of the top of the scale.

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, so the bar is lower. The description adds context about the source (data.govt.nz CKAN) and the returned metadata fields, which is useful. However, it doesn't disclose other behavior such as error handling, authentication requirements, or rate limits, which would be additional value.

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

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

The description is a single, well-structured sentence that front-loads the source and then specifies the exact resource and fields. It contains no fluff and earns its place.

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

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

For a simple single-parameter read-only tool with an output schema and strong annotations, the description covers the source, purpose, and parameter semantics. It is complete; the output schema handles return values, and annotations handle safety.

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

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

Schema description coverage is 0%, but the description compensates by explicitly stating 'by resource ID,' which clarifies the meaning of the single 'id' parameter beyond its name. The example in the schema reinforces this. Without a full schema description, this is sufficient.

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 metadata for a single resource by resource ID, listing specific fields (URL, format, size, description, last modified). It distinguishes itself from sibling tools by specifying 'resource' rather than package, group, or organization, 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 implies usage: if you need metadata for a specific resource ID, use this tool. It doesn't explicitly mention alternatives (like package_show for datasets) or state when not to use it, so it lacks the explicit exclusions needed for a 5. However, the context is clear enough for most 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 cover read-only, idempotent, non-destructive behavior, so the description adds value by explaining the probe process: it calls ai_visibility_check per entity, ranks results, and returns a structured output. This gives the agent insight into how the tool operates and what it returns. It does not disclose potential rate limits or costs associated with multiple probes, but this is beyond the minimum requirement 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 sentences: the first states the core function and process, the second provides a practical use case with an illustrative example. It is front-loaded, concise, and every sentence contributes meaningful information 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?

With no output schema, the description compensates by explicating the return format (ranked list with score, confidence, signal density). It also specifies the entity ordering, the use of ai_visibility_check, and the competitive audit context. Given the moderate complexity (4 params, 1 required), this is a complete and self-contained description.

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

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

Schema description coverage is 100%, and the schema already explains each parameter, including the special meaning of the first entity in the entities array. The tool description adds no additional parameter semantics beyond what the schema provides, so the 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 the tool's function with a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and explicitly distinguishes it from the sibling tool ai_visibility_check by focusing on side-by-side comparison and ranking. It also names the output format (ranked list with score, confidence, signal density), 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?

The description provides a clear use case ('competitive AI-marketing audits') and an example query, which tells the agent when this tool is appropriate. However, it does not explicitly mention when to avoid it or suggest alternatives (e.g., using ai_visibility_check for a single entity), so it stops short of full exclusions/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 substantial behavioral context beyond annotations: it explains the fan-out to two services, graceful degradation, potential 5-30s latency for first bundlephobia measurement, and the sources_failed field. It discloses NPM-only scope. No contradiction with the readOnly/idempotent annotations; the behavior is consistent with a read-only composite lookup.

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 every sentence contributes: purpose, usage trigger, return summary block, ecosystem scope, and failure behavior. It is front-loaded with the core purpose and remains information-rich without redundancy for 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 tool's high complexity and absence of an output schema, the description fully discloses the return format (summary fields, advisories, links, alternative versions), failure modes, and latency expectations. It also covers ecosystem limitations. No significant information gap remains for an agent to invoke or interpret results.

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

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

Schema coverage is 100% and already describes both parameters (package name with scoped-package acceptance, version default). The description adds meaning by tying parameters to the data sources and giving a concrete use-case example ('what does adding lodash cost me'), plus clarifying that version is optional in context. This is moderate added value over the schema, 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 specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly identifies what the tool does (composite scan across deps.dev and bundlephobia) and differentiates it from simpler siblings like package_show or package_search by emphasizing the combined, one-call nature.

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?

Guidance is explicit: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states when not to use (non-NPM ecosystems fall under deps.dev:version directly), providing clear exclusions and direction to 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial technical context: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and a 200K char cap with flagged truncation. It also discloses return format (offsets and similarity scores), going 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 three sentences, front-loaded with the core operation, then usage context, then technical caveats. Every sentence contributes unique information with 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?

For a tool with no output schema, the description adequately explains return values (passages with character offsets and similarity scores), parameter constraints (200K cap, truncation with flag), and the intended workflow (fetch → search within → ground). It fully equips an agent to use the tool correctly without additional documentation.

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 giving concrete examples for the query parameter (e.g., 'supply-chain risk') and clarifying the text parameter with use cases (SEC 10-K body, article). It also explains the limit indirectly as 'top-N' and constraints on text length, enriching schema-only 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 it performs semantic search inside a provided text, with the verb 'Semantic search' and resource 'INSIDE a fetched record.' It distinguishes from siblings by emphasizing it works on already-pulled text and pairs with a specific sibling (ask_pipeworx_grounded), making its unique scope obvious.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative/companion tool (ask_pipeworx_grounded) and explains how to combine them, providing clear context for selection alongside 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 goes well beyond the annotations. It specifies that anonymous/BYO accounts cannot persist subscriptions, requires OAuth authentication, details the always-on feed plus optional channels, explains phone verification and a 10/day SMS cap, and notes webhook auto-disabling after 10 consecutive failures. These are valuable behavioral disclosures not present in annotations, fully transparent about side effects and requirements.

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 compact and front-loaded, with the main action stated in the first sentence. Each subsequent sentence delivers necessary specifics about types, delivery channels, and constraints without fluff. It is appropriately sized for a tool with this complexity and maintains a logical structure.

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 (3 parameters, nested objects, no output schema), the description is remarkably complete. It explains the return value (subscription id), authentication requirements, type-specific params, delivery channels with verification and limits, and webhook signature details. There is no critical missing information for an agent to successfully invoke 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 has 100% parameter coverage with detailed descriptions for each type and delivery option. The tool description adds extra value by reinforcing examples, emphasizing the OAuth requirement, and providing cross-references to delivery constraints. While much is redundant with the schema, it adds meaningful context beyond it, justifying a 4.

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 begins with 'Create a proactive monitoring subscription to a live-data event stream,' which is a clear, specific verb-plus-resource statement. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of subscriptions, and further clarifies its scope with supported event types.

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 on when to use the tool: to set up monitoring subscriptions, with explicit prerequisites (OAuth account, verified phone for SMS, etc.). It does not explicitly mention when not to use it or name alternatives, but the purpose is unambiguous and supported by examples. This is a clear context without exclusions, meriting a 4.

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

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

The description goes beyond the annotations (which already indicate read-only, open-world, and idempotent behavior) by detailing what the tool returns (category-bucketed example questions with exact tool and argument shape), how it sources from the live catalog of thousands of tools, and how calling with no arguments vs. a `topic` changes the result. This provides substantial behavioral context and no contradictions.

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

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

The description is longer than average but every part serves a purpose: it gives example queries, explains the output structure, lists categories, and provides explicit usage guidance. It is front-loaded with example questions and then explains functionality. While not as concise as a two-sentence description, it earns its length for an onboarding tool.

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

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

Given that there is no output schema, the description adequately explains the return value: category-bucketed example questions with exact tool and argument shapes. It also lists all categories and covers both invocation modes (with and without `topic`). The tool is simple (one optional parameter) and the description covers all necessary aspects for correct 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 schema already provides 100% coverage, including a detailed description of the `topic` parameter listing all valid values and the omit behavior. The description adds only redundant examples ('finance', 'pharma', 'betting') and says 'e.g.', which does not materially increase understanding beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific language like 'onboarding entry point' and 'returns category-bucketed example questions', and it distinguishes itself from sibling tools by positioning it as the first tool to use when unsure what Pipeworx can do.

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 guidance on when to use: '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 how to adjust behavior by omitting or passing the `topic` parameter. However, it does not explicitly name alternative tools or state when not to use it, though the 'first' guidance implies a clear role.

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. The description adds context about the specific data.govt.nz catalogue and the taxonomy-browsing purpose, but does not disclose additional behaviors like pagination or rate limits. The added value is modest given the strong annotation coverage.

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 core purpose, and contains no filler. Every clause contributes useful information.

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

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

The tool has an output schema, rich annotations, and a clear primary use case, but the lack of parameter explanations for two of three parameters leaves gaps. The description could mention the effect of 'all_fields' or 'vocabulary_id' to make it fully self-contained.

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 clarifies the 'query' parameter but leaves 'all_fields' and 'vocabulary_id' unexplained. This is a significant gap for a tool with three undocumented parameters.

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

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

The description clearly states the tool lists dataset tags from a specific CKAN catalogue, with optional query filtering. It distinguishes itself from siblings by referencing package_search for filtering by tag, making its purpose specific and actionable.

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 'Use to browse taxonomy before filtering package_search by tag,' providing clear when-to-use context and naming the alternative tool for the subsequent step. This gives the agent a concrete usage flow.

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 this as read-only, idempotent, and non-destructive. The description adds value by specifying that the tool operates on the New Zealand CKAN catalogue and that include_datasets optionally enriches the response with tagged datasets. No contradiction exists.

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

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

The description is a single, front-loaded sentence that provides location context, the core action, and the optional behavior 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 a simple 2-parameter tool with an output schema and strong annotations, the description is sufficient. It explains the optional parameter and the data source, though it does not detail response structure (covered by output schema) or explicit sibling exclusions.

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

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

Schema coverage is 0%, but the description compensates by explaining that 'id' can be a name or ID, and 'include_datasets' includes the dataset list. This gives 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 the tool provides detail for a single tag by name/ID, optionally including datasets. It uses a specific verb ('show') and resource ('tag'), and is distinct from siblings like tag_list (list all tags) and package_show (dataset details).

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 needing details of one specific tag, rather than listing tags. It does not explicitly name an alternative, but the context is unambiguous given the sibling set. No exclusions are mentioned, but none are necessary.

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 ownership enforcement and the soft-delete behavior, noting that the row is deactivated and historical events remain available via recent_alerts. This adds value beyond the annotations (readOnly=false, destructive=false, idempotent=true) and provides important behavioral details.

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 with no redundancy. It front-loads the primary action and then provides key behavioral details efficiently.

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

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

For a 1-parameter tool with comprehensive annotations, the description covers all essential behavioral quirks: ownership, deactivation vs. deletion, and history preservation. No additional information is needed for an agent to safely and correctly invoke it.

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

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

The schema already fully documents the single parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' The description's phrase 'by id' adds no new semantic detail, so the baseline of 3 applies due to 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 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions, and the ownership enforcement clarifies 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?

The description provides clear context about when to use the tool (canceling your own subscriptions) and its implications (deactivation, history retention). However, it does not explicitly name alternatives or state when not to use it, but the context is sufficient.

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 hints. The description adds substantial context: explains the meaning of could_not_verify versus unsupported, mentions verification_error with stage/detail, notes the structured SEC/XBRL fast path vs grounded pipeline, and clarifies that could_not_verify is not evidence. This goes well beyond the structured annotations.

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

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

The description is dense but every sentence serves a purpose; it front-loads the intended usage with natural-language triggers, then details routing, return values, and error semantics. It is longer than strictly necessary but remains well-structured and scannable, earning a 4 rather than a 5.

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

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

Since there is no output schema, the description fully discloses return values (verdicts, actual value with citation, reasoning) and error semantics. It covers the complexity of routing between structured and grounded pipelines, and provides caller-facing warnings about could_not_verify. This is a complete picture for a tool of this complexity.

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

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

Input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds value by explaining how claim content affects routing (financial vs other) and notes the tolerance default cap ('capped at 5'), which provides semantic context 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 natural-language query examples and immediately states the tool's purpose: claim verification against authoritative sources. It clearly distinguishes itself from siblings by focusing on fact-checking with a verdict outcome, and even mentions replacing 4–6 sequential calls, making the 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes routing for financial vs non-financial claims, giving clear context. However, it does not explicitly mention when not to use it or name alternative tools, 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.