Wikidata

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by explaining payment implications (BYO key for Anthropic, billed directly), default model (Workers AI Llama-3.3-70b free), and return structure (per-model and combined view). 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 ~100 words, front-loaded with main purpose, then parameter details, output summary, and use cases. Every sentence is informative and concise 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?

Despite no output schema, the description explains the per-model response fields (score, confidence, signals, raw_response) and combined view. It covers all parameters, their roles, and the use case. Combined with annotations, it provides a complete understanding for the agent.

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

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

Schema has 100% description coverage, but description adds beyond schema by stating default model behavior, that `_apiKey` is optional and passed through to Anthropic, and that context helps disambiguate. This enriches the parameters' meaning.

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

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

The description clearly states the verb 'probe' and resource 'LLMs for what they know about business/brand/product/topic', and specifies the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like 'ask_pipeworx' by focusing on visibility measurement rather than direct Q&A.

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

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

Provides clear context for use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the `_apiKey` parameter for Anthropic probing. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, lowering the bar. The description adds compatible behavioral context beyond those: this is a dispatcher tool that routes to sub-tools, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. No contradictions with annotations, though error/out-of-domain behavior is not disclosed.

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

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

One dense but front-loaded paragraph: the most important routing rule ('PREFER OVER WEB SEARCH') comes first, and the START HERE / hand-off guidance is last. Length is justified for a default entry-point tool, and every sentence contributes, but the trailing sentence reads slightly garbled and the block would benefit from being split into scannable segments.

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 states what comes back (structured answer with stable pipeworx:// citation URIs), plus input expectations, behavior, when to use, and the main alternative. The notable gap is silence on the near-name siblings ask_pipeworx_beta and ask_pipeworx_grounded, which an agent must distinguish when selecting among available tools.

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 every non-required parameter is a documented alias of 'question', so the schema carries the parameter definitions. The description adds real value by teaching question formulation through trigger phrases, a domain list, and six worked examples showing acceptable question shapes — useful because the schema only says 'natural language'.

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

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

States a specific verb+resource: routes a natural-language question to the right one of 5,710 tools across 1,494 verified sources, fills arguments, and returns a cited structured answer. It explicitly positions itself against web search and names deep_research as an alternative, though it never distinguishes itself from the near-named siblings ask_pipeworx_beta and ask_pipeworx_grounded.

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?

Gives explicit when-to-use guidance: trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), a list of domains (SEC, FDA, FRED/BLS, USPTO, ATTOM, weather, etc.), and six concrete example questions. It also states when-not/alternatives: prefer it over web search, and use deep_research for broad/multi-part questions that need fan-out. The only gap is no guidance for the ask_pipeworx_beta/grounded variants.

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

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

Annotations already mark it read-only, idempotent, open-world, and non-destructive, but the description adds important live behavioral context: candidate routing improvements may be active, none are currently active, it currently matches ask_pipeworx exactly, and it does not fall back to anything. This goes well beyond the structured annotations and sets accurate expectations.

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

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

The description is front-loaded with the core identity and relationship to ask_pipeworx, and later sentences add current-state, usage, and no-fallback context. It is slightly verbose with the specific retirement date, but each sentence carries meaningful 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 complex beta router without an output schema, the description covers current behavior, relationship to the stable tool, usage intent, and experimental nature well. It relies on 'same response shape' rather than spelling out response fields, which is a minor gap but acceptable given the sibling reference.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters and aliases. The description only says 'same arguments' without adding new parameter-level detail, which is acceptable but does not go 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 identifies this as a beta version of ask_pipeworx and a universal router over 5,710 tools with the same arguments and response shape. It also distinguishes itself from its stable sibling by explicitly framing it as the experimental routing edge.

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

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

It gives direct guidance: use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This is an explicit when-to-use instruction with a named 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 (readOnly, idempotent, openWorld), the description discloses the return payload shape, all refusal reasons, the verbatim evidence requirement, and the extra LLM call cost. This is substantial behavioral context that annotations do not 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 dense but every sentence earns its place: purpose, mechanism, return contract, refusal semantics, usage guidance, and cost trade-off are all present and logically ordered. It front-loads the key purpose and behavior.

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 grounded Q&A tool with no output schema, the description fully specifies success and failure output shapes, the evidence requirement, when to use it, and when not to. Nothing essential is missing for correct invocation.

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

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

The schema already documents both parameters fully, including aliases and the natural-language expectation, so the description does not need to add much. Baseline 3 is appropriate since schema coverage is complete and the description adds no conflicting details.

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 grounded answer mode and explains that it extracts answers only from tool results, returning evidence and refusals. It also explicitly distinguishes it from ask_pipeworx, so an agent can tell them apart.

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 names the alternative (ask_pipeworx) and gives explicit selection criteria: use this when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. It also notes the extra cost trade-off.

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

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

The description extensively discloses behavioral traits beyond annotations: market resolution process, classifier fan-out, response shapes, resolver contract (market_match_confidence, alternatives), parent_event extractor, news fallback behavior, safety mechanisms (low-confidence short-circuits, closed market detection), spread warnings, and cancellation rule parsing. Annotations already indicate readOnly and idempotent, and the description adds rich behavioral context, making this tool highly transparent.

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 lengthy but well-structured, with sections and examples for classifiers, fan-outs, response shapes, and safety. It is front-loaded with the main purpose and input format. While every sentence adds value given the tool's complexity, the length could be reduced by condensing some example fan-outs. Overall, it earns its length but is not maximally concise.

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

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

Given the tool's complexity (3 parameters, no output schema, rich return structure), the description is exceptionally complete. It covers input formats, resolution process, response fields (result.market, result.analysis, result.evidence), resolver contract, parent_event handling, news fields with fallback, safety edge cases, and cancellation rule details. Without an output schema, the description effectively documents all output facets.

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

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

The input schema has 100% description coverage, but the tool description adds substantial meaning: it explains that 'market' accepts slug, URL, or question text (with examples), clarifies the 'depth' enum with 'quick' vs 'thorough' semantics and default, and details 'include_raw' usage with trade-offs (response size vs. full payload). This goes significantly beyond schema descriptions, making parameter semantics clear and actionable.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research, pull), the resource (Polymarket bet), and the scope (Pipeworx data). The examples and classifier list further clarify functionality. However, the description does not explicitly distinguish this tool from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage', which serve related but distinct purposes.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples of when specific fan-outs apply (e.g., BTC bet → coingecko + fred + gdelt+gnews). While it doesn't explicitly state when not to use the tool, the context implies alternatives exist for edge/arbitrage tasks. The guidance is clear and actionable.

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?

Description adds rich behavioral detail beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS + FDA data for drugs), sorting by primary metric, and citation URIs. No contradiction with readOnlyHint, idempotentHint, etc.

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

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

Description is efficient with front-loaded trigger phrases and compact sentences. Every sentence adds value, though slightly longer due to detailed behavioral info. Could use minor structural separation.

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 tool complexity (two entity types, data sources, sorting, no output schema), description is fully complete. Covers all necessary aspects for correct invocation and interpretation.

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

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

With 100% schema coverage, baseline is 3. Description adds meaning by explaining the enum values (company vs. drug) and what data each returns, plus examples for the values array. Adds substantial 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?

Description provides specific trigger phrases (e.g., 'Compare X and Y', 'rank these companies') and clearly states it compares 2–5 companies or drugs. It distinguishes from sequential single-pack lookups and explains the two 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. Also notes correct handling of off-calendar fiscal years, adding context for edge 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?

The description adds substantial behavioral context beyond the readOnly/openWorld/idempotent annotations: it explains the parallel decomposition across 5,710 tools, the findings packet shape, gaps[] for unanswered facets, the never-invents guarantee, contradictions[] for deeper depths, semantic excerpting, citation resolvability, and expected latency. This is exactly the kind of non-obvious runtime behavior an agent needs.

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 dense with genuinely useful details, and it front-loads the account requirement and the primary alternative. Some redundancy with the schema's depth enum exists, but for a tool with this much behavioral complexity the length is mostly justified and the key routing information is easy to find.

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 is no output schema, the description carries the full burden of explaining what the agent will get back, and it does so concretely: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], and contradictions[]. It also covers prerequisites, alternatives, latencies, and failure-adjacent behavior (never invented), making the tool safe to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by tying depth levels to account tiers, latency expectations, and the single-hop vs. gap-recovery vs. iterative-hop behavior. It also clarifies that the question parameter should be phraseable as broad/multi-part natural language, reinforcing the schema's own guidance.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's structured data sources' in a single call. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, making the tool's niche as a broad, parallel, structured-research tool 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?

Usage guidance is explicit: use it for 'broad/multi-part questions over structured data' and use ask_pipeworx instead for a single lookup or when not signed in. It also states the account/tier requirement up front, so an agent knows when the tool is unavailable and which alternative to route to.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it returns top-N tools with names, descriptions, full schemas with examples, and that results are callable directly—valuable context beyond annotations.

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

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

One well-structured paragraph with front-loaded purpose. Contains necessary detail but could be tighter; still very effective for agent consumption.

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

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

No output schema, but description fully explains what is returned (names, descriptions, schemas, examples). Covers default/max limit. All relevant behavioral aspects are addressed given the tool's simplicity.

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

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

Schema coverage is 100% so baseline is 3. Description adds context: clarifies that 'query' accepts natural language, lists aliases (task, q, search, description), and explains the limit parameter. This adds moderate value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific examples (SEC filings, FDA drugs, etc.) and explains that it returns relevant tools ready to call, distinguishing it from sibling tools that perform different functions.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies alternatives (e.g., if you already know the tool, skip).

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are already present. Description adds behavioral context: fans out across multiple sources, returns specific fields, patents soft-fail until May 2025, and details the data structure. 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 slightly verbose but well-structured: starts with example queries, then purpose, then what it returns, then limitations. Every sentence adds unique info. Could be trimmed slightly but efficient for the complexity.

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

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

No output schema exists, so the description must detail return values. It lists all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and their structure. Completely covers what the agent can expect.

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

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

Schema coverage is 100% (both parameters described). Description adds value by clarifying 'type' only supports 'company', 'value' accepts ticker or zero-padded CIK, and explicitly says names not supported—providing more practical guidance than the schema alone.

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

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

The description uses a specific verb ('returns full cross-source profile') and resource ('US public company'), and distinguishes itself from sibling tools like resolve_entity and chaining lookups. Example queries like 'Tell me about X' and 'company profile for Microsoft' make the purpose immediately clear.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also clarifies when NOT to use (names not supported, use resolve_entity first) and notes fallback behavior (patents sunset, GDELT→GNews fallback).

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, so the description's 'delete' aligns. However, the description adds no extra behavioral context beyond what annotations provide (e.g., whether deletion is permanent, what happens if key missing). It does not contradict annotations.

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

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

The description is two sentences, no redundant words, and front-loads the primary action. Every sentence is informative and earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, strong annotations), the description covers purpose and usage adequately. It lacks details on error handling or return values, but these are not critical for such a straightforward tool.

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

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

Schema coverage is 100% for the single parameter 'key' with description 'Memory key to delete'. The tool description does not add any additional meaning beyond the schema, so 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 states 'Delete a previously stored memory by key,' which uses a specific verb (delete) and resource (memory). It clearly distinguishes from sibling tools 'remember' and 'recall' which are for storing and retrieving memories.

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 conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also pairs with remember and recall, providing context. It does not explicitly state when not to use, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, indicating a safe read operation. The description adds behavioral detail: it performs an external fetch, extracts metadata, and returns standard markdown. This context complements the 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?

The description is three sentences plus a bulleted usage list. It is well-structured, front-loaded with the core action, and every sentence adds value. No redundant or vague statements.

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 2 parameters, no output schema, and rich annotations. The description covers purpose, behavior (fetch, extract, output), and usage scenarios. It could mention what happens on failure or for invalid URLs, but overall it is sufficient for the agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema's parameter descriptions; it merely restates the purpose. No additional detail on parameter usage or format is provided.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the process: fetches page, extracts title/description/key links, outputs markdown. It also lists three distinct use cases, differentiating it from sibling tools like '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 includes an explicit 'Useful for:' section that tells when to use the tool (client site, own project, competitor audit). While it doesn't explicitly say when not to use it or name alternatives, the context is clear enough for an agent to decide.

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?

This description goes beyond the readOnly/idempotent annotations by explaining the return payload in detail, including lastrevid and modified timestamp and their purpose. The provenance-pinning detail is especially valuable for agents deciding between live versus historical data. It does not cover edge-case behavior like missing IDs, but annotations already establish the safe read-only profile.

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

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

The description is two sentences, front-loaded with the core purpose and then detailed with meaningful return information. It is dense but not bloated. The only minor excess is some overlapping explanation of the revision field and its timestamp, yet each clause still earns its place.

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

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

For a single-parameter, read-only, idempotent fetch operation, this description is complete. It states the input format, gives concrete examples, explains the full output contents including version metadata, and the output schema and annotations already cover any remaining structural and safety details. Nothing an agent needs to call this tool correctly is missing.

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

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

The input schema already covers 100% of the parameter with examples (Q42, Q1764, P31). The description adds one extra concrete ID example (Q5) and reinforces semantics through full entity retrieval, but it does not materially enrich what the schema already states. This meets the baseline for high schema coverage without adding substantial clarity.

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

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

The description starts with a specific action and resource: 'Get full Wikidata entity by ID'. It clearly enumerates what 'full' means (labels, descriptions, aliases, claims, sitelinks, revision info), so the agent understands exactly what this tool returns. The by-ID scoping also sets it apart from broader tools like search_entities.

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

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

The phrase 'by ID' provides clear contextual guidance: this tool is for when an agent already knows a Wikidata entity ID and needs complete entity data. It does not explicitly mention when to prefer search_entities, resolve_entity, or compare_entities, but the ID-based usage is clear enough to avoid obvious mis-selection.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond those: the output is label-resolved rather than raw codes, and it discloses the lastrevid/modified metadata semantics for state-after-latest-edit questions. It does not go into error behavior for unknown Q-ids, so 4 rather than 5.

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

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

Three dense sentences with zero filler: the differentiator (human-readable labels), the routing callout (PREFER OVER get_entity), a concrete worked example, the revision-metadata caveat, and input sourcing are each given exactly one line. Informative and 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?

For a single-required-parameter tool with no output schema, the description fully substitutes for return-value documentation: it shows the JSON shape with an example, explains what lastrevid/modified mean, and covers the only ambiguity an agent faces (how to obtain a Q-id). Nothing essential 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%: the schema already defines id as a Wikidata Q-id with the Q42 example and the search_entities pointer. The description's 'Pass a Q-id from search_entities' reinforces the schema but adds no new meaning, so the baseline 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?

States a specific verb and resource: returns 'structured facts about a Wikidata entity' in 'HUMAN-READABLE form' with labels instead of raw P/Q codes. The example with Q42 clarifies exactly what the agent receives, and naming get_entity as the alternative distinguishes it from the closest sibling.

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 'PREFER OVER get_entity' for concrete query patterns — 'what is X's <attribute>', 'facts about X', 'X's date of birth / capital / population' — and tells the caller to pass a Q-id from search_entities. Routing and input sourcing are both spelled out.

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 safety (readOnlyHint, idempotentHint, destructiveHint false). Description adds return fields and scope, but no additional behavioral nuance beyond what annotations imply.

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

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

Two concise sentences, front-loaded with main purpose. No wasted words.

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

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

Given simple schema (1 optional param) and no output schema, description fully covers purpose, usage, return fields, and retrieval context.

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

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

Schema coverage is 100%, so description need not elaborate. It does not add meaning beyond the schema's parameter description.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says when to use: 'before adding more or to find an id to cancel', providing clear context and 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 annotations provide minimal information (all false hints), so the description carries the full burden and handles it excellently. It discloses rate-limiting (5/day), that it's free and doesn't count against quota, that filing without an account returns a token, that the team reads digests daily, and that signals affect the roadmap. No contradiction with annotations.

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

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

The description is relatively long, but each sentence earns its place: it covers scope, exclusions, token mechanics, rate limits, and a note on impact. It is front-loaded with the core purpose, and the structure flows logically from when-to-use to how-to-follow-up. Slightly over-length, but not wasteful.

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 fully by explaining the return behavior (claim_token and later status/change retrieval). It also covers edge cases (different MCP server, not sure which tool), making it complete for an agent to invoke safely and correctly.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds meaningful value by explaining the claim_token usage flow ('pass it back later as pipeworx_feedback({claim_token...})') and providing example pack/tool names in the context, which enriches, rather than repeats, the schema.

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

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

The description uses a specific verb ('Tell... something is broken, missing, or needs to exist') and clearly defines the resource (Pipeworx team) and the scope (tools served by this connection). It also distinguishes itself from all sibling tools, none of which are feedback mechanisms, and enumerates the exact feedback types (bug, feature, data_gap, praise).

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

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

The description explicitly states when to use (bug, feature gap, praise) and when not to use (for tools from a different MCP server), naming the alternative (file with that server instead). It also explains how to use the claim_token to follow up, making the usage guidance exceptionally 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds: data source (CF analytics-engine), no PII, caching behavior (5min-1h). Adds context beyond annotations, but could mention accuracy/limitations.

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?

Approximately 100 words. Front-loaded: what it returns first, then bullet-pointed use cases, then technical notes. No redundant sentences. Well-structured and easy to scan.

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

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

Given 1 optional parameter, no output schema, and rich annotations, the description covers: return format, use cases, data source, PII note, caching. 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?

Only one parameter (window) with 100% schema coverage. Schema gives enum and short description. Description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning 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?

Description clearly states it returns 'top tools, top packs, and total call volume' with specific windows (24h, 7d, 30d). Distinguishes from siblings like 'ask_pipeworx' (querying) and 'discover_tools' (general discovery). Verb+resource: 'Returns' + 'trending data'.

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

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

Provides three explicit use cases (discovering hot data, confirming canonical tool, aligning use case). Implies when to use (e.g., for current events). Lacks explicit when-not-to-use or alternatives, but the use cases are 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?

Goes far beyond annotations: explains internal logic (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (realizable vs theoretical edge). 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?

Thorough but efficient; each sentence adds value. Structured with clear sections for each mode and response details. Slightly verbose in technical explanations but overall well-organized and 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?

Completely covers inputs, modes, internal checks, response structure, and limitations. No output schema, but description details the response fields and fill check logic. Perfectly adequate given 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 has 100% coverage, but description adds significant meaning: explains event slug format with examples, topic mode behavior, cross-event scanning, and partition_check. Provides context not in schema.

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

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

The description clearly states the tool's purpose: find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling polymarket_fill_risk.

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: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also warns when not to trade based on fill check results and suggests polymarket_fill_risk for custom sizing.

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 beyond annotations by detailing three response segments, caching behavior, limitations (e.g., Fed bets excluded), and diagnostics. 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?

Well-structured with segments and knobs, but verbose with internal details (e.g., specific Greek letters) that could be omitted. Front-loaded with main purpose.

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

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

Thoroughly describes response format (by_segment, diagnostics) and how to interpret edge values. Compensates for lack of output schema with detailed behavioral explanation.

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

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

All 9 parameters are described with additional context beyond the schema (e.g., slippage_pp explains Polymarket fees, min_liquidity explains walking the book). Adds significant 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It identifies the specific resource and action, and distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explicitly says it's built for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. Provides context but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a baseline. The description adds significant behavioral context: it reads snapshots, returns tracked/expired arrays, explains gaps due to cache misses, TTL limits, and decay calculation. No contradictions.

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

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

The description is well-structured, starting with the core purpose, then detailing response fields and limitations. It is slightly verbose but each sentence adds information. Front-loaded with the key question the tool answers.

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

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

Given no output schema, the description thoroughly explains all three response arrays (tracked, expired, snapshot_dates) with subfields and semantics. It also covers limitations (TTL, snapshot start, decay calculation). The tool is complex, and the description is complete for effective 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 coverage is 100% with descriptions for both parameters. The description adds value by specifying defaults (14 days, '1wk'), clamp ranges (2-30), and clarifying the 'window' parameter as snapshot family. This information aids correct parameter selection.

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: providing edge persistence and decay telemetry from daily snapshots. The verb 'answers' and the specific question 'how long has this edge existed and is it shrinking?' make the purpose explicit. However, it does not explicitly distinguish this tool from sibling tools like polymarket_edges or polymarket_arbitrage, though the context implies differentiation.

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

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

The description provides clear context on when to use the tool: when needing to understand edge duration and decay. It gives a concrete example ('a fresh wide edge vs. a 3-week-old wide edge'). However, it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: requires one of market or event, walks the order book ladder, returns specific fields per mode, and highlights forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections for SINGLE-MARKET and BASKET modes. It front-loads the main purpose and then details behavior per mode. Every sentence adds value, though some details could be implied from 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?

Given the tool's complexity, no output schema, and important risk context (partial fills, unhedged positions), the description covers all necessary information: return fields, mode-specific behavior, usage guidance, and warnings. It is fully adequate for an AI agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond schema: explains the dual meaning of size_usd (spend vs target proceeds vs settlement notional), default side logic for baskets, and mode-specific behavior. This enriches understanding.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It differentiates from siblings like polymarket_arbitrage and polymarket_edges with explicit 'use this before' guidance.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns that theoretical overround may not be capturable and partial basket fills create unhedged positions.

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?

This is a heavily disclosed description: it covers response shape, compatibility_codes, per-entry flags, skipped counter semantics, temporal alignment, and the rule that unknown metric_type or match_subtype legs are never paired. It even tells the caller that compatibility fields can be non-empty even when matched_pairs>0, which is exactly the kind of behavior an agent needs to know. The annotations already mark it read-only, and the description adds substantial behavioral detail beyond that.

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

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

The description is long but densely informative; every section covers a real pitfall or required interpretation (modes, safety fields, skipped legs, temporal alignment, tradeability caveat). It is front-loaded with the core purpose and uses clear labels. It could be tightened in places, but the length is justified by the tool's complexity.

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

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

Given the tool's complexity, the absence of an output schema, and the many edge cases around compatibility, the description is remarkably complete. It tells the agent what response fields to expect, which codes can appear, what they mean, how skipped comparisons are categorized, and how to interpret alignment. Nothing critical is left for the agent to infer.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining what the topic shortcuts do, that explicit ticker/slug override the mapped side, and what kind of pairing each mode enables. This is useful, though the schema already covers the literal parameter roles.

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

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

The opening line states exactly what the tool computes: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes further than a generic fetch/list tool by naming the two venues and the concept of equivalent bet shapes, which clearly distinguishes it from siblings focused on Polymarket-only edges. The two explicit modes (topic shortcuts vs. custom ticker/slug) reinforce the 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 gives clear guidance on how to use the two modes and when the spread is meaningful: only when bet shapes are equivalent. It also cautions that most pre-mapped topics return compatibility_warning and that pre-mapped does not equal tradeable. However, it does not explicitly name alternative tools like polymarket_arbitrage or polymarket_edges or state when to prefer them, so it stops short of the highest bar.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and pairing behavior, going beyond annotations.

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

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

Two sentences, front-loaded with core purpose, no extraneous words. Efficient and to the point.

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 1 optional parameter, good annotations, and no output schema, the description fully covers usage, scoping, and pairing, leaving no gaps.

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

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

Schema has 100% coverage with description 'omit to list all keys'. Description reinforces this and adds context, providing meaning beyond the schema's property description.

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

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

Description clearly states verb (retrieve/list), resource (saved values/keys), and distinguishes from siblings like remember and forget. Specifies behavior for with and without key.

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 (look up stored context) and provides pairing with remember/forget. Lacks explicit when not to use, but context is clear.

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

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

The description contradicts the readOnlyHint=true annotation by describing mark_read:true which flags events as read, modifying state. Annotations indicate no state modification, but description reveals side effects, a serious inconsistency.

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, efficient paragraph that front-loads the main purpose. It covers key aspects like return structure, filtering, and mark_read without unnecessary words. Could be slightly more structured, but it's concise enough.

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

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

Given no output schema, the description explains return values (source, citation_uri, raw payload). It explains all parameters and side effects like mark_read. However, the contradiction with annotations reduces reliability, but the description itself is fairly complete for the tool's purpose.

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%, baseline 3. The description adds meaningful context: explains that 'type' filters by subscription type (e.g. 'sec_8k'), 'since' is an ISO timestamp, and 'mark_read' behavior. This goes beyond schema 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 pulls fired events from a subscription feed, with specific verb 'Pull' and resource 'fired events'. It differentiates from siblings by its specific focus on recent alerts from a subscription feed, which is distinct from other tools like list_subscriptions.

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

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

The description provides context on when to use (pulling recent alerts from subscription feed), mentions alternatives (the same feed via HTTP endpoint for scripts/dashboards), and notes that polling works fine. It could be improved by explicitly stating when not to use, but the guidance is clear.

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

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

Beyond the annotations (readOnlyHint, etc.), the description discloses key behaviors: the fan-out to multiple sources, the fallback logic, the USPTO reactivation dependency, and the return structure (changes grouped by source with counts and citation URIs). No contradictions with annotations.

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

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

The description is a single paragraph that packs in examples, source details, parameter info, and return structure. It is concise given the complexity, but could be slightly more structured (e.g., bullet points) for easier scanning. Still, every sentence earns its place.

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

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

Given the tool's complexity (multiple data sources, fallback, soft-fail), the description is complete. It covers purpose, usage, behavior, parameters, and return value structure (changes array, total_changes, citation URIs). No output schema exists, but the description adequately explains return values.

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 describes all three parameters (100% coverage), but the description adds valuable context: explanation of relative vs. ISO date formats for `since`, the note that `type` only supports 'company', and the relationship to `entity_profile`. This adds meaning beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company in a time window, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from the sibling tool `entity_profile`, which provides static profiles, avoiding confusion.

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

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

The description provides explicit guidance on when to use this tool vs. alternatives (e.g., 'Use entity_profile instead when you want the static profile'). It also explains the fallback behavior for news (GDELT preferred, GNews when rate-limited) and notes the USPTO soft-fail condition.

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

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

Annotations already provide idempotentHint=true. The description adds behavioral context: persistence (authenticated vs anonymous 24h), scoping by identifier, and pairing with recall/forget. Does not state what happens on duplicate keys (idempotent likely means overwrite) or error cases.

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

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

Well-structured: first sentence states purpose, then usage guidance, then persistence, then pairing. No wasted words; 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?

For a storage tool with no output schema, the description explains storage model, scoping, and retention. It could mention return value (e.g., confirmation or the stored key-value) and error handling, but it's largely complete given 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 clear descriptions. The description adds value by providing example keys ('subject_property', 'target_ticker') and emphasizing that value can be any text, enriching the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies key-value storage scoped by agent identifier, and distinguishes it from siblings 'recall' and 'forget'.

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

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

Provides explicit use cases ('discover something worth carrying forward') with examples. Implicitly advises when to use it over alternatives by pairing with recall/forget, but lacks explicit when-not-to-use 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?

Despite having readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds substantial behavioral detail: internal cascading through multiple endpoints, graceful degradation when LEI/FIGI sources are unavailable, and explicit handling of unresolved identifiers. This goes well beyond the annotations.

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

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

The description is long but well-structured, starting with user-phrase examples and then logically presenting supported types, fallback behavior, and internal mechanics. While every sentence adds value, the density may make it slightly harder to scan quickly, but the use of uppercase labels and clear segmentation helps.

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

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

With no output schema, the description does a good job of explaining what to expect: identifiers with source labels, an explicit 'unresolved' field, and the source-specific mappings. It covers edge cases like non-US issuers and graceful degradation. However, it does not detail the full response structure or any potential pagination, which would be helpful.

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 clear descriptions, but the description enriches them significantly. It provides concrete examples for value (ticker, CIK, ISIN, brand names), explains the nuances of each type (e.g., ISIN-to-LEI mapping), and clarifies input formats that the schema does not. This is far more than the schema provides.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific example queries and supported types. It distinguishes itself from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID,' making its role as an ID-lookup tool 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?

It provides explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and details the two supported entity types. However, it does not explicitly state when not to use it or compare with specific sibling tools like search_entities, but 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, providing useful behavioral context beyond annotations.

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

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

The description is four sentences, each adding unique information: purpose, mechanism, use case, and output format. No unnecessary words, front-loaded with the primary action.

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

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

Given no output schema, the description adequately explains the return format (ranked list with score/confidence/density). It also mentions the use of ai_visibility_check internally. Some details (e.g., meaning of score) are omitted, but overall 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 description coverage is 100%, but the description adds value by specifying that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema. This extra semantic justifies above baseline.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check for each, and ranks the results. It distinguishes itself from sibling ai_visibility_check (single entity) by explicitly mentioning multi-entity comparison.

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

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

The description provides clear context for use in competitive AI-marketing audits and gives an example query. It implies the tool is for multi-entity comparison but does not explicitly state when not to use it (e.g., for single entities, use ai_visibility_check).

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, safe. Description adds critical behavioral context: mentions fan-out to two services, partial failure with graceful degradation, and a 5-30s delay for new versions on bundlephobia. No contradictions.

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

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

Description is detailed but front-loaded with the core purpose. Some redundancy could be trimmed, but every sentence adds value. It is well-structured and informative.

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

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

Although no output schema, the description fully explains the return format including summary block fields, per-advisory detail, links, and alternative versions. Error handling is also mentioned. Given the tool's complexity, the description is highly complete.

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

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

Schema description coverage is 100% with clear descriptions for both params. Description does not add significant new 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 clearly states it's a composite check for evaluating npm packages, covering license, advisories, bundle size, etc. It distinguishes itself from siblings by specifying 'npm ecosystem only' and directing other ecosystems to a different 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?

Explicitly says 'Use whenever an agent asks is X safe / popular / small'. Also clarifies when not to use: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns specific fields and searches by label/alias, but does not elaborate on search mechanics, pagination, or language handling. The description provides useful context beyond annotations but is not extensive.

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

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

Three sentences, front-loaded with action and examples, no wasted words. Every sentence contributes to understanding the tool's purpose and output.

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 3 parameters fully described in schema, an output schema, and annotations covering behavior, the description is largely complete. It lacks explicit guidance on when to use this vs. specific siblings, but overall it is sufficient for an agent to select and 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 coverage is 100%, so baseline is 3. The description mentions 'by label or alias' and gives examples, but does not add meaning beyond what the schema already provides (e.g., limit, language). The description paraphrases the schema without adding new insights.

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

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

The description starts with a specific verb ('Search Wikidata entities by label or alias'), provides concrete examples, and mentions what it returns (IDs, labels, descriptions, aliases). It clearly distinguishes from sibling tools like get_entity (which retrieves by ID) and resolve_entity (which disambiguates).

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

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

The description states it is 'useful for finding the Wikidata ID of any concept', which gives clear usage context. However, it does not explicitly define when not to use or compare to alternatives like get_entity or resolve_entity, but the purpose implies it is for name-based lookup.

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?

Descriptions add details beyond annotations: return format (passages with offsets and scores), embedding model, window size, and a 200K char cap with truncation. No contradiction with annotations.

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

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

Three well-structured sentences: purpose, usage guidance, technical details. No unnecessary words.

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

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

Given the tool's complexity, annotations, and no output schema, the description fully covers what the tool does, how it works, and its limitations.

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 description adds concrete examples for query and clarifies text limit, enhancing the baseline.

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

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

The description clearly states the tool does semantic search inside a fetched record, specifies verb, resource, and scope, and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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 to use when the record is too big for the prompt and pairs with ask_pipeworx_grounded, providing clear when-to-use and 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 write operation, idempotent, non-destructive. The description adds substantial behavioral context: account requirement, always-on feed, optional delivery channels, SMS daily cap, webhook signing and secret behavior, auto-disable after failures. This goes well beyond annotations.

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

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

The description is detailed but well-organized: first sentence states purpose, then account requirement, then types, then delivery channels. It is front-loaded. While verbose, every sentence adds necessary context. Slightly trimmed could improve conciseness.

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

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

Given the tool's complexity (3 parameters, 2 required, nested objects, no output schema), the description covers purpose, return value, account prerequisites, type-specific parameters, delivery channel behaviors, and edge cases (SMS cap, webhook auto-disable). It is comprehensive 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 coverage is 100%, so baseline is 3. The description significantly enriches parameter meaning with examples (e.g., sec_8k items codes), real-world usage hints (e.g., phonenumber verification), and webhook signing details. This adds high value beyond schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specifies the action (create), resource (subscription), and distinguishes from siblings like list_subscriptions and unsubscribe.

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 context on when to use (setting up monitoring) and prerequisites (Pipeworx OAuth account). It details types and delivery options but does not explicitly contrast with alternative tools like recent_alerts or polymarket_edges. It offers good implicit 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description need not repeat safety. It adds value by describing the return format (category-bucketed examples with tool+argument shapes) and that it draws from a live catalog.

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 common phrasings, then explains functionality and usage. It is moderately lengthy but well-structured and 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?

For a simple tool with one optional parameter and no output schema, the description fully covers its purpose, usage context, and what it returns. No gaps.

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

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

Schema coverage is 100% with a description of the topic parameter. The description adds concrete examples ('finance', 'pharma', 'betting') and context on its effect, 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 returns category-bucketed example questions from a live catalog, and distinguishes it from siblings like ask_pipeworx by positioning it as the onboarding entry point.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you', explains how to call with no arguments for full spread or with a topic to focus, and mentions alternative meta-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?

Disclosures beyond annotations: ownership enforcement, deactivation not deletion, and that historical events remain available via recent_alerts. Complements annotations (idempotentHint=true, destructiveHint=false) 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?

Two sentences with no filler. Front-loaded with verb and resource. Every sentence provides essential 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 single-parameter mutation tool with no output schema, the description covers purpose, side effects, ownership, and data retention. No gaps.

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

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

Schema coverage is 100% with parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' Description adds no further parameter information, so 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 'Cancel a subscription by id', a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation 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?

Description includes ownership enforcement ('you can only cancel your own subscriptions'), providing context for when the tool is applicable. No explicit alternatives are given, but the sibling context makes it 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?

The description goes beyond the readOnly/idempotent annotations by explaining the semantic difference between could_not_verify (a system failure, not evidence) and unsupported (no source found). It also details the two execution paths (SEC EDGAR XBRL vs grounded pipeline) and the citation behavior, which is valuable operational context.

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

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

While lengthy, the description is well-structured with a purpose statement, usage guidance, behavioral caveats, and return-value explanation. It front-loads the core purpose and every sentence contributes necessary information—especially the IMPORTANT callout about could_not_verify.

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 thoroughly explains the verdict types and the error semantics. It also covers when to use the tool, the routing logic, and the efficiency benefit. This is complete for a complex verification tool.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters, including tolerance_pct's defaults and overrides. The tool description adds no new parameter semantics beyond what the schema states, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with example user phrasings and an explicit statement of what it does: checking factual correctness against authoritative sources. It distinguishes itself from siblings by covering the full verification pipeline and mentions it replaces multiple sequential calls.

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

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

It provides an explicit usage rule: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between financial and non-financial claims, indicating internal routing. It does not explicitly name alternatives or when-not-to-use, but the guidance is strong.

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

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

Annotations already mark this read-only/idempotent/non-destructive, and the description adds live-feed recency, newest-first ordering, exact returned fields (Q-id, revision ids, timestamp, user, comment, byte size), and cursor-based paging. No annotation 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?

Three sentences: what it returns, what questions it answers, and how results are shaped. Every sentence adds useful information and the key 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 rich annotations, a fully documented input schema, and an output schema, the description still adds ordering, live-feed behavior, and return-field details. Nothing needed to select or invoke the tool correctly 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 description coverage is 100%, so the schema fully documents all six parameters. The description adds little parameter-level meaning beyond mentioning the cursor for paging, which the schema already covers.

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 names a specific resource (Wikidata live MediaWiki recent-changes feed) and specific actions (newest items created or edited), and answers concrete example questions. The Wikidata qualifier separates it from the generic recent_changes sibling.

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 example questions provide clear context for when to use the tool, such as asking which QIDs were created today or what changed in the last hour. It does not explicitly state exclusions or name alternatives, so it stops short of a 5.

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