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 the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context: the tool routes internally, fills arguments, returns structured answers with stable citation URIs, and handles live news. This goes beyond the annotations without contradicting them.

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

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

The description is long but each segment earns its place: domain enumeration, routing behavior, trigger phrases, examples, and alternative-tool routing. It is front-loaded with the most important instruction (prefer over web search). Slight redundancy exists between "PREFER OVER WEB SEARCH" and later repetition that web search is not needed, but overall the structure is efficient.

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

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

For a broad routing tool with no output schema, the description covers the input domain, trigger phrases, examples, output format (structured answer with citation URIs), and the main alternative tool (deep_research). It does not differentiate from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, nor describe failure behavior when no source matches, but the coverage is strong overall.

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 question parameter and all its aliases are fully documented in the schema, so the baseline applies. The description adds many illustrative example questions, but these serve more as usage guidance than as additional parameter semantics such as formatting, constraints, or expected input shape.

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

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

The description explicitly states the tool routes questions to one of 5,767 tools across verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It clearly positions this as the preferred factual-answer tool over web search and names deep_research as the alternative for multi-part questions.

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

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

The description gives explicit when-to-use guidance ("PREFER OVER WEB SEARCH", "Use whenever the user asks..."), lists concrete trigger phrases and examples, and explicitly points to deep_research for broad multi-part questions. It also clarifies that breaking-news questions are already handled by this tool, making the routing decision unambiguous.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that this is the experimental edge, that candidate routing improvements are enabled live only when one is under test, that the last candidate was retired, and that it does not fall back to the stable router—it is a full working router. This is unusually rich, current, and honest behavioral context.

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

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

The first sentence establishes identity and scope, then current state, usage, and the no-fallback clarification follow in a logical order. The retired-date detail is slightly more than necessary, but each sentence serves a purpose and the key facts are front-loaded.

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

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

For a beta-variant tool, the combination of current-status details, explicit usage instruction, and rich annotations is enough to call it correctly. The response contract is deferred to 'same response shape' rather than described locally, so there is a small completeness gap, but the sibling context mitigates it.

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

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

All six schema properties carry descriptions, with the question field explicitly documenting natural-language input and its aliases, so schema coverage is complete. The description only says 'same arguments,' which adds contextual reassurance but does not further explain parameter semantics; 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?

The description clearly identifies the tool as the beta variant of ask_pipeworx with the same 5,767-tool universal-router surface, same arguments, and same response shape, which separates it from ask_pipeworx and ask_pipeworx_grounded at the surface level. It never states the underlying ask/answer behavior in its own right, but that is recoverable from the tool name and sibling context.

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

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

'Use it exactly like ask_pipeworx when you want the newest routing' is an explicit call condition, and the description adds that no candidate is currently active so it currently matches ask_pipeworx exactly. It does not enumerate when-not-to-use or how to prefer grounded/stable siblings, so the guidance is clear but not exhaustive.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: exact success return shape, listed refusal reasons, the rule that evidence must be a verbatim quote, and the extra LLM call cost. 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 information-dense but every sentence earns its place: purpose, routing behavior, return/refusal contract, use cases, and cost tradeoff. The most important identifier is front-loaded, and the comparison to ask_pipeworx is stated directly.

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 fully compensates by specifying the success response fields and the refusal object with all possible refusal_reason values. It also covers operational tradeoffs like the extra LLM call, making the tool safe and predictable to invoke.

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

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

The schema has 100% coverage and fully documents the six aliases for the single question parameter, so the description does not need to repeat parameter meaning. It adds only the high-level context that the tool routes and fills arguments, which is useful but not necessary 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 is a hallucination-resistant answer mode for high-stakes reads, with a specific verb and resource ('answer mode' / grounded retrieval). It explicitly differentiates itself from ask_pipeworx and ask_pipeworx_beta by describing the extraction constraint and refusal behavior.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and names the alternative: 'prefer ask_pipeworx for casual lookups.' This directly guides the agent away from the wrong sibling.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: auth/plan requirements, findings packet structure, explicit gaps[], contradictions[], hop field, stable pipeworx:// citations, semantic excerpting, and latency expectations. It also discloses the limitation of empty gaps[] for topics outside the structured 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 dense and informative, but runs long with several asides (signup URL, citation mechanics, semantic excerpting) that could be trimmed. It is front-loaded with the most critical decision-relevant information (account requirement and alternative tool), which helps navigate the length.

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

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

For a 2-parameter tool with full schema coverage, strong annotations, and no output schema, the description is complete: it covers when to use, what to expect, latency, edge cases, and the exact nature of the findings packet. The detailed description compensates fully for the absent output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds modest extra insight about depth levels (gap recovery and lead chasing), but largely reinforces the enum descriptions rather than introducing new 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call. It explicitly contrasts against open-web search and names the parallel routing to 5,767 tools, making it easy to distinguish from siblings like ask_pipeworx.

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

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

It explicitly says 'Best for broad/multi-part questions over structured data' and provides example questions. It also tells the agent to use ask_pipeworx instead when not signed in, and for breaking/current-news topics noting that deep_research would return mostly empty gaps[]. The depth-level guidance further clarifies when to use standard vs thorough.

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

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

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 already indicate readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior: fan-out sources, per-section response keys, sources_used/sources_failed semantics, soft-fail for the patent API sunset, expected empty FDA section for small-molecule-only companies, and resolved:false with notes for private companies. No contradiction.

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

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

The description is long, but nearly every sentence carries operational value, and the trigger examples plus 'ALWAYS PREFER' rule are front-loaded. It loses one point because the output section and source caveats could be tightened or bulleted without losing substance.

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

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

With no output schema, the description carries the full burden of return-value disclosure and meets it: it enumerates every response section, flags possible empty sections as expected, and explains input and failure modes. An agent has enough to invoke it and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by showing accepted value shapes (ticker, zero-padded CIK, name), noting that name strings resolve through SEC EDGAR, and clarifying that type='company' and type='ticker' are interchangeable.

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 verb+resource: build a full cross-source profile of a US public company. It opens with user-intent examples and explicitly differentiates itself from chaining single-pack SEC/XBRL/news lookups, so an agent can tell when this tool is the holistic option.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a clear when-to-use rule with an alternative class. It stops short of mapping all sibling tools (e.g., get_entity, compare_entities) to when-not-to-use conditions, so it isn't a 5.

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

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

Annotations already declare 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses significant behavioral details: Kalshi fees are not modeled, spreads are gross not net, compatibility_codes can be non-empty even when matched_pairs>0, and temporal_alignment null means unknown rather than aligned. It also explains when legs are skipped and what flags appear, giving high transparency about 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?

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes). It front-loads the core purpose and packs in necessary caveats; while a few concepts are repeated (e.g., identical matcher, temporal_alignment_unknown), the repetition reinforces critical warnings without being purely redundant.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, spread top_spreads_pp, compatibility warnings and codes, temporal alignment fields, fees_note, and skipped counters. It fully prepares an agent to interpret results and handle non-obvious cases such as unknown alignment and unverified pairings.

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

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

The input schema already covers all three parameters with 100% description coverage, so baseline is 3. The description adds value by explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, that explicit pairings run the same matcher as topic mode, and by enumerating the topic shortcuts in the property description itself.

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 purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from sibling Polymarket tools by focusing on Kalshi–Polymarket comparison, and it details two modes (topic shortcuts and explicit pairings) that define its scope.

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

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

The description gives clear context for when to use each mode: topic shortcuts for pre-mapped macros and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable, but it does not explicitly compare against sibling tools like polymarket_arbitrage or polymarket_edges, so exclusions are only implicit.

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

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

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds substantial behavioral detail beyond those hints. It discloses internal cascading lookups, graceful degradation of LEI/FIGI enrichment, explicit `unresolved` reporting, ambiguity handling via `figi_candidates`, and source labeling of identifiers. No contradiction with annotations exists.

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

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

The description is long but well-structured: it front-loads the core use case, then organizes supported types and edge behaviors under clear labels. Most sentences carry operational value, though some parenthetical explanations and examples could be trimmed without losing meaning. It earns its length due to the tool's complexity, but it 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?

With no output schema, the description carries the burden of explaining return semantics, and it does so thoroughly. It specifies what identifiers are returned for each type, how unresolved identifiers are surfaced, how ambiguity is handled, and how failures degrade. The tool is complex, and the description covers the operational knowledge an agent needs to call it correctly and interpret results.

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

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

Although the schema already describes both parameters, the description adds significant semantic value beyond it. It details accepted input forms for company type (ticker, CIK, ISIN, name), clarifies that only the entity name should be passed rather than the full noun phrase, and provides concrete examples like 'ozempic' and 'NEW YORK ST DORM AUTH'. This substantially improves an agent's ability to populate `value` correctly.

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

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

The description opens with concrete user phrasings and a specific action: resolving a user-spoken name to canonical identifiers. It clearly labels supported entity types and distinguishes itself from sibling tools by saying the identifiers it produces are what 'other tools require as input.' This is a specific verb + resource with strong sibling differentiation.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger condition. It also explains when the tool is preferable to manual lookups and covers edge cases like bond issuer names, but it does not name alternate sibling tools or state when to choose them instead. Clear usage context, but no explicit when-not-to-use guidance against alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. 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.