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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond these: it routes queries to sub-tools, fills arguments, returns stable pipeworx:// citation URIs, and is a single fast call that works on every tier. It doesn't discuss error handling or rate limits, but with annotations covering safety, this is not a major gap.

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 front-loaded with 'PREFER OVER WEB SEARCH' and is structured logically with usage rules, examples, and alternatives. However, it is somewhat longer than necessary: the example queries duplicate those in the schema, and phrases like 'even if web search could also answer it' add marginal value. Still, every major sentence contributes to decision-making.

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

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

With no output schema, the description compensates by explaining that the answer is a structured result with pipeworx:// citation URIs. It covers when to use, when not to use (via alternatives), provides concrete examples, and mentions compatibility across tiers. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

The input schema covers 100% of parameters (question plus five aliases) with clear descriptions. The description does not add new parameter-level semantics beyond what the schema already provides; it only gives usage examples, which are already present in the schema's examples. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's function: it routes factual questions to one of 5,366 tools across 1,396 sources and returns a structured answer with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases, making its unique purpose unmistakable.

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

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

Explicitly instructs to prefer this tool over web search for a broad category of questions, and provides precise 'when to use' guidance with trigger phrases like 'what is', 'look up', 'get the latest'. It also names alternatives and exactly when to step up: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. This is exemplary usage guidance.

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

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

The description goes beyond the annotations by explaining the beta nature, that routing improvements are 'enabled live whenever one is under test,' and that currently no candidate is active. It also clarifies that this is a full working router, not a stub, which adds valuable behavioral context beyond the read-only and idempotent hints.

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

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

The description is front-loaded with the key purpose, and each sentence adds relevant detail (same tools, no active candidate, usage guidance, experimental status). While slightly verbose with specific counts (5,366 tools) and a date, the structure is coherent and compact enough for the information conveyed.

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 universal router with no output schema, the description adequately covers what it does, its relationship to ask_pipeworx, current status, and fallback behavior. The lack of return-value details is mitigated by referencing the identical response shape to ask_pipeworx, making it sufficiently complete.

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

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

The schema is fully covered (100%) with all parameters documented as aliases for 'question,' and the question parameter has a clear natural-language description. The description adds minimal param info beyond saying 'same arguments' as ask_pipeworx, so the baseline of 3 for full schema coverage 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 is a 'Beta version of ask_pipeworx' and identifies it as a 'universal router' with the same 5,366 tools and response shape. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded by framing it as the experimental edge, making its purpose unmistakable.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that when no candidate is active, 'this currently matches ask_pipeworx exactly,' giving clear context for when to choose this over the stable alternative.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false), the description discloses detailed behavior: it only answers from tool results, returns a structured response with evidence and confidence, and provides explicit refusal reasons (not_in_source, no_tool_match, etc.). 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 dense but well-structured, front-loading the purpose and then progressively explaining process, return format, use cases, and trade-off. Every sentence earns its place; length is justified by the tool's complexity.

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

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

The description fully covers what an agent needs: what the tool does, how it operates, exact return schema, refusal reasons, when to use it, and cost comparison. Given no output schema, it adequately explains return values and edge cases.

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 the question parameter and its aliases clearly described. The description adds no parameter-level detail, but none is needed given the high schema coverage, 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 clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource (tool results from routing). It distinguishes itself from sibling ask_pipeworx by emphasizing evidence, verbatim quotes, and refusal behavior.

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

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

Explicit guidance is provided: use when answers will be quoted/cited/acted on and facts must not be invented; avoid for casual lookups, preferring ask_pipeworx. It also notes the extra LLM call cost, helping the agent choose appropriately.

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

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

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses decomposition into facets, parallel routing, gap[] handling, contradiction detection, hop fields, semantic excerpting, latency expectations, and the requirement for paid accounts on certain depth levels. This adds rich behavioral context and does not contradict any annotation.

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

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

The description is long (around 300 words) and formatted as a dense paragraph, which reduces skimmability. However, nearly every sentence contributes operational or usage-critical details, and the information density justifies the length. It is front-loaded with the account gate, which is essential for agent decision-making.

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

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

For a complex tool with no output schema, the description thoroughly specifies the return value structure (findings packet with evidence, confidence, source, fetched_at, citations), gap[] and contradictions[] fields, hop semantics, and expected time ranges. This gives an agent all the context needed to invoke the tool and interpret results.

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

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

The input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds value by explaining the practical implications of depth levels (e.g., thorough requires payment, standard adds gap-recovery hop) and clarifying that the question can be broad or multi-part. It goes slightly beyond the schema's descriptions.

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

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

The description clearly states the tool performs multi-source grounded research across Pipeworx's 1,396 structured data sources, using decomposition and parallel tool routing. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making its purpose and scope unambiguous.

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

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

The description provides explicit guidance: use for broad/multi-part questions, prefer ask_pipeworx for single lookups or breaking/current-news topics, and notes account prerequisites with a fallback for unsigned users. It names the alternative tools and describes when deep_research would underperform.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: parallel fan-out across sources, the patents API sunset with soft-fail behavior, and the specific return fields with URIs. It doesn't contradict annotations.

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

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

The description is a single dense paragraph but is exceptionally information-rich, covering purpose, usage, data sources, outputs, and limitations. It could be slightly more compact, but nearly every sentence carries actionable detail, so it earns its length.

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

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

With no output schema, the description thoroughly explains return values (CIK, filings with URIs, fundamentals, patents, news, LEI) and a notable failure mode (patents soft-fail). It also covers input constraints and a resolution alternative, providing a complete picture for a read-only 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 covers both parameters fully (type with enum, value with description and name-not-supported note). The description adds examples ('AAPL', '0000320193') but doesn't introduce new semantics beyond the 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 states a specific verb+resource: 'full cross-source profile of a US public company'. It distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and explicitly notes 'use resolve_entity first' for names, setting it apart from resolution and comparison tools.

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

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

It clearly defines when to use ('Tell me about X', 'research Acme', etc.) and gives an explicit alternative for unsupported input ('use resolve_entity first if you only have a name'). It also advises preference over chaining separate lookups, which is direct usage 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 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?

All annotations are false, so the description carries the full burden. It adds valuable context: the tool is rate-limited to 5 per identifier per day, is free and doesn't count against tool-call quota, and that the team reads digests daily. This goes beyond simple 'send feedback' and helps the agent understand consequences.

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, with the first sentence stating the purpose, the second offering use-case guidance, and the third covering constraints. Every sentence contributes information; no filler or repetition exists.

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

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

Given the tool's moderate complexity (3 params, one nested, no output schema), the description completely covers what the tool does, when to use it, how to phrase feedback, and rate limiting. It leaves no ambiguity for an agent to invoke it correctly.

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

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

The input schema already provides 100% coverage of all parameters with descriptions and enum explanations. The description adds extra semantics for the message parameter (e.g., 'Describe the issue in terms of Pipeworx tools/packs') and for context, providing guidance that complements rather than duplicates 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 clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling data-retrieval tools by focusing on feedback submission.

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 when a tool returns wrong/stale data...' and also provides guidance on what not to do ('don't paste the end-user's prompt'). It also mentions rate limits, giving the agent operational constraints.

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 already declare readOnly, idempotent, and non-destructive. The description goes much further by detailing the compatibility_warning cases, temporal_alignment, and skipped_cross_type/subtype counters. It explicitly states when the result is meaningless, which is crucial behavioral context beyond the annotations. No contradiction.

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

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

Although long, the description is highly structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, final warning). Every sentence earns its place by adding a distinct fact or caution, and the most important purpose is front-loaded.

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

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

With no output schema, the description carries the burden of explaining return values. It enumerates key response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and explains their meaning and implications, making it self-sufficient for an agent to 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 covers all three parameters with descriptions and an enum-like list for topic. The description adds meaning by explaining the two modes, that explicit ticker/slug override the topic-mapped side, and provides concrete examples like 'fed' and 'KXFED-26OCT.' This exceeds the baseline schema-only understanding.

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

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

The description opens with a specific verb-resource pairing: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explains the 2-25pp spread phenomenon.

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

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

The description explains two modes (topic shortcuts vs explicit ticker/slug) and gives explicit warning conditions: 'compatibility_warning fires in two cases' and 'aligned:false means spreads are mathematically meaningless across the temporal gap.' It also cautions that 'pre-mapped ≠ tradeable.' However, it does not explicitly name alternative tools for when not to use this one.

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?

Annotations already declare read-only, idempotent, and non-destructive. Description adds behavioral context: cascades through multiple lookup endpoints, auto-disambiguates, and produces 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?

Front-loaded with concrete example queries, then organized into supported types and returns. Slightly dense but every phrase adds value; no wasted sentences.

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 carries the full burden of explaining returns—and it does: specific fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand for drug) are enumerated. Also covers input acceptance and internal cascade.

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 includes parameter descriptions, but the tool description adds meaningful format guidance: ticker/CIK/name examples for company, brand/generic names for drug, and output mapping for each type beyond schema.

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

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

Clear verb-resource pairing ('resolve a user-spoken NAME to the canonical/official identifier'), supported types enumerated, and differentiates from sibling tools by being the prerequisite ID lookup. Examples in description all reinforce purpose.

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

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

Explicit instruction: 'Use FIRST whenever you have a name but need an ID.' Also states it replaces 2-3 manual lookups, giving unmistakable context for when to invoke this tool over alternatives.

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

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

Annotations already indicate read-only, idempotent, 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 indicate a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description goes beyond this by disclosing the internal routing logic (SEC EDGAR + XBRL fast path vs. grounded pipeline), the exact return components (verdict, actual value with citation, reasoning), and the tolerance_pct override behavior for hallucination detection. This provides rich operational 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 long but every sentence contributes information: examples, routing logic, return values, and benefit. It is front-loaded with natural-language triggers followed by usage guidance. While slightly verbose, it is well-structured for a complex tool and avoids 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 2 parameters and no output schema, the description is thoroughly complete. It explains purpose, when to use, processing paths, return values, and tolerance behavior. It even communicates the underlying methodology (percent-delta math, verbatim evidence) and outcomes (verdict types), leaving no critical 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 description coverage is 100%, so the schema already fully explains both parameters. The description adds some context (e.g., tolerance_pct relevance to hallucination detection) but mostly repeats what the schema says. Baseline 3 is appropriate because the schema carries the burden, and the description adds marginal value.

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

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

The description states a specific verb ('validate') and resource ('natural-language claim verification against authoritative sources'), with concrete query examples ('Is it true that...', 'fact check'). It clearly distinguishes this tool from generic research tools by focusing on claim verification and describing two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for other claims).

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 whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use guidance. It does not explicitly mention when not to use or name alternative tools, but the high-level purpose is unambiguous and the description notes it 'Replaces 4–6 sequential calls,' implying it is the preferred consolidated tool for this task.

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