Singstat Sg

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: default model is free, Anthropic requires BYO API key, and details the return structure. No contradictions.

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

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

Two sentences, front-loaded with core purpose, zero waste. Every clause adds value, including optional API key note and return structure.

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

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

No output schema is present, but the description explains return fields (score, confidence, signals, raw_response) and combined view. Parameter documentation is strong. For a 4-parameter read-only tool, this is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: default model details, API key usage, and context disambiguation purpose. This elevates the score.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It uses specific verbs (probe, score) and resource (visibility per model), and is distinct from siblings like 'compare_entities' or 'entity_profile'.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not list when not to use or alternatives, but the context is clear and sufficient for correct 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 signal read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context by explaining the routing behavior and the stable pipeworx:// citation URIs, which go beyond annotation coverage. No contradictions with annotations were found.

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

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

The description is front-loaded and informative, but it contains clear redundancy: the 'even if web search could also answer it' clause, the example list, and the 'START HERE' instruction appear twice. This duplication means not every sentence earns its place, making the text unnecessarily bloated.

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 meta-tool with no output schema, the description explains what it does, what it returns in the form of structured answers with citations, and gives ample examples. It does not cover edge cases or failure modes, but for an agent deciding to invoke it, the essential context is present.

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

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

The schema already documents all six parameters, all aliases for 'question', at 100% coverage, so the baseline is 3. The description adds semantic value with trigger phrases and examples of what makes a good question, which helps the agent populate the parameter 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 defines a specific action: routing natural-language questions across 5,798 tools and 1,517 sources, then returning structured answers with citation URIs. It clearly states the resource and scope, but it does not explicitly distinguish itself from the ask_pipeworx_beta and ask_pipeworx_grounded sibling tools, so it falls short of a 5.

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 strong when-to-use guidance, including 'PREFER OVER WEB SEARCH', a list of domains and trigger phrases, and multiple concrete examples. However, it never states when not to use it or mentions alternative tools other than web search, so the exclusion side of the guidance is missing.

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, and the description adds meaningful context: beta status, candidate routing improvements enabled live, no active candidate right now, and comparison against the stable router. This goes well beyond the structured annotations and helps an agent understand the experimental nature and current behavior.

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

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

The description is a bit longer than necessary but every sentence carries relevant information about the beta status, current behavior, usage, and fallback. The key distinction from ask_pipeworx is front-loaded, and the closing sentence reinforces that this is a fully functional router.

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

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

For a tool with a simple one-question input schema and no output schema, the description is complete: it states the response shape matches ask_pipeworx, explains the current routing state, and gives clear usage direction. An agent has enough context to invoke it correctly and understand what will happen.

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 every parameter described as an alias for the single 'question' parameter. The description adds only that the tool accepts the same arguments as ask_pipeworx, which is useful context but not necessary because the schema already fully documents the parameters.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing the experimental routing edge and explicitly naming ask_pipeworx as the comparison 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?

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router to decide merges. It also clarifies the current state — no candidate is active — so an agent knows behavior currently matches ask_pipeworx exactly.

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 explains the grounded behavior, return contract, and refusal reasons. It discloses that the tool returns evidence verbatim, confidence, source, fetched_at, and a refusal_reason when data does not directly answer. It also communicates the extra LLM call cost, which is material behavioral context not visible in annotations or schema.

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

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

The description is dense but every sentence earns its place: it defines the mode, explains the routing and extraction behavior, gives the return shape, lists refusal cases, specifies high-stakes use cases, and notes the cost tradeoff. The most important decision information is front-loaded in the first sentence.

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

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

Since there is no output schema, the description compensates by fully specifying both the success response and the refusal response, including refusal_reason enumerations. It also covers the sibling relationship, use cases, and cost tradeoff. For an agent to select and correctly invoke this tool, 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 description coverage is 100%, with the single 'question' parameter and its aliases already documented in the schema. The free-text description adds that the tool 'fills arguments' automatically but does not add parameter-level semantic detail beyond the schema. The baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by emphasizing grounded extraction only from the tool result. It names a specific verb/resource relationship: the tool answers questions by routing to sources, fetching data, and extracting evidence. The purpose is immediately understandable and differentiated from related tools.

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

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

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative condition: 'prefer ask_pipeworx for casual lookups.' It names ask_pipeworx directly as the sibling alternative, making the decision boundary concrete 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: low-confidence resolution short-circuits with status, market_closed_or_inactive handling, illiquid wide spread warnings, resolution-rule risk parsing, response shapes, resolver contract, parent event extraction, news fallback fields, and safety checks. 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 comprehensive but verbose, containing several paragraphs with extensive examples and technical details. It is well-organized with sections but could be more concise. Some repetition exists (e.g., resolution paths described twice).

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 thoroughly explains return values: response shapes (result.market, result.analysis, result.evidence), resolver contract (confidence, score, alternatives, suggestions), parent event extractor, news fields with fallback mechanisms, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. Covers nearly all aspects of complex behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: for the 'market' parameter, it specifies slugs, URLs, or question text; for 'depth', explains quick vs thorough; for 'include_raw', describes when to use true vs false. This goes well beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and scope (one call). It also provides example queries and distinguishes itself from sibling tools by focusing on a single bet with fan-out to data packs.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also describes the internal workflow (resolve, classify, fan-out) to help the agent understand when to call it. However, it does not explicitly state when not to use it or name alternative tools for comparison, though the sibling list is provided externally.

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, and non-destructive behavior. The description adds detailed behavioral info: specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), off-calendar fiscal year handling, and sorting by primary metric. 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 dense but well-front-loaded with key phrases and examples. Every sentence adds value, though a minor redundancy exists (e.g., repeating 'type="company" pulls...'). Still, it earns its length.

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

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

Despite no output schema, the description mentions return format ('paired data + pipeworx:// citation URIs'). It covers both entity types, data sources, and edge cases (off-calendar fiscal years). Adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: 'type' enum values are explained with what data they pull (revenue/net income/cash/debt for company; adverse events/approvals/trials for drug), and the 'values' parameter format is clarified (tickers for company, names for drug).

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 performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, using clear verbs like 'compare' and specific resources ('companies or drugs'). It distinguishes itself from sibling tools like entity_profile by focusing on 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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong usage guidance. It also includes example queries ('which is bigger...') and implies when not to use (avoid sequential lookups).

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses account requirements, paid tier conditions, non-open-web grounding, parallel tool routing, the exact findings-packet shape (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), the citation_uri fetchability guarantee, semantic excerpting of large records, and expected latency (15-60s, up to ~90s for thorough). No contradiction with annotations.

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

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

The description is long but appropriately so for a tool of this complexity. It is front-loaded with the most critical constraint (account required) and the core differentiator (NOT open-web search), then proceeds through output structure, depth semantics, citation behavior, and latency. Every sentence conveys operational information; the only minor redundancy is mentioning ask_pipeworx twice, but each instance serves a different routing context.

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

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

With no output schema, the description fully covers return values: findings packet fields, gaps[] for unanswered facets, contradictions[] for standard/thorough, hop field, citation_uri only when fetchable, and semantic excerpting. It also covers edge cases like unfetchable citations and slow responses. An agent has all the information needed to invoke the tool and interpret results.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the enum values. It explains that depth:'standard' re-angles unanswered gaps and adds contradictions[], depth:'thorough' chases leads from the first pass and costs money, and that the 'question' parameter can be broad/multi-part natural language. This contextualizes the parameters for decision-making far better than the schema alone.

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

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

The description names a specific verb-resource pair: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It details the mechanism (decompose into facets, route to 5,798 tools in parallel, return findings packet) and explicitly distinguishes itself from open-web search and ask_pipeworx. Concrete examples like 'compare X and Y's regulatory + financial exposure' make the intended use unmistakable.

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

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

The description states both when to use and when to use alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx instead', and 'If you are not signed in, use ask_pipeworx instead'. It also guides depth selection by noting that 'thorough' requires a paid plan and that standard/thorough add gap recovery and contradictions scanning.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by explaining output format and readiness. No contradiction with annotations.

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

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

The description is concise (about three sentences) and front-loaded with the core purpose. Every sentence serves a purpose: defining the tool, listing domains, and explaining the return value. No wasted words. Excellent structure.

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

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

Given that there is no output schema, the description adequately explains what is returned (top-N tools with schemas). It also covers the 'when to use' aspect. It lacks details on error handling or empty results, but for a discovery tool this is sufficient. Scores 4.

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%, baseline 3. The description adds value by providing usage examples (e.g., 'analyze housing market trends', 'look up FDA drug approvals') and explaining that multiple aliases (task, q, description, search) all map to the query. This helps the agent understand parameter usage beyond the formal schema. Scores 4.

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

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

The description clearly states the tool's purpose: to find/discover relevant tools by describing a data or task. It uses specific verbs ('browse, search, look up, discover') and explicitly contrasts with sibling tools by instructing 'Call this FIRST'. It distinguishes itself well from the many domain-specific siblings.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search...' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly state when not to use, but the context strongly implies it is for discovery before using other tools. Scores 4 for clear context without exclusion criteria.

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/idempotent annotations, the description discloses parallel fan-out across sources, sources_used/sources_failed semantics, empty-section meaning, SEC EDGAR name resolution, private-company resolved:false behavior, GDELT→GNews fallback, and URI formats. No contradiction with annotations.

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

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

Front-loaded with user intents and a clear preference rule, and densely packed with return-shape details that compensate for the missing output schema. However, the single long run-on paragraph becomes somewhat repetitive near the end, especially where it restates schema content.

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

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

Since there is no output schema, the description carries the full burden of explaining return values, and it does so well: resolved identifiers, recent_filings URIs, fundamentals fields, sources_used/sources_failed, empty-section semantics, and failure modes are all covered. An agent has enough context to call and interpret the tool correctly.

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

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

Schema coverage is 100% and the schema already fully documents both parameters, including accepted forms and the interchangeable behavior of type. The description mostly restates this with examples; the added resolved_from/resolved_to and private-company notes are output-behavior details rather than new input semantics.

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

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

States a specific verb and resource: "full cross-source profile of a US public company in ONE parallel call," supported by concrete example queries. It clearly distinguishes itself from chaining single-pack SEC/XBRL/news lookups and frames the tool as the holistic-view 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?

Explicitly instructs "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view," giving agents a direct when-to-use rule. It also covers the main input edge cases: ticker, CIK, company name, and private-company behavior.

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 destructiveHint=true and idempotentHint=true. Description adds 'delete' which matches, but doesn't elaborate on effects or return behavior. Minimal added value 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, direct and to the point. No redundant information. Every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose and usage but omits what the tool returns (e.g., success confirmation). Adequate but could be more 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 covers the only parameter fully (100% coverage). Description mentions 'by key' but adds no new detail beyond the schema's 'Memory key to delete'.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying the verb, resource, and method. References siblings 'remember' and 'recall', providing context on how it fits in the tool family.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. While it doesn't list when not to use, it pairs with siblings, implying alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, confirming safe, idempotent, read-only behavior. The description adds valuable context: the process (fetches page, extracts title/description/links), output format (standard markdown, single text blob), and deployment location (site-root/llms.txt). 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?

Three sentences, each serving a distinct purpose: action definition, process summary, and use cases. No redundant words, front-loaded with key verb and resource.

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 2 non-nested parameters and no output schema, the description fully covers input, process, output format, and usage context. It explains how the output should be used (dropped at site-root/llms.txt) and for whom (AI crawlers). 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%, so baseline is 3. The description enhances both parameters: for 'url' it provides an example, for 'max_links' it states default (25) and max (50). These details add practical 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?

The description clearly defines the tool's action (generate), resource (llms.txt file), and target (any URL). It distinguishes from siblings by specifying 'production-ready' and the exact output format, which is unique among 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?

Explicitly lists three practical use cases (client index, own project, competitor audit) that help an agent decide when to invoke. Lacks explicit 'when not to use' or direct alternative tool references, but the use cases are sufficient for 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns specific fields and usage context, which is useful but not heavily 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: first front-loads action and fields, second provides usage guidance. No wasted words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, rich annotations), the description adequately covers purpose, return fields, and usage 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% with a single optional boolean parameter fully described. The description does not add extra meaning beyond the schema, earning the baseline score.

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

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

The description clearly states the verb 'List' and resource 'caller's active subscriptions', and specifies returned fields. It distinguishes from sibling tools like subscribe/unsubscribe by mentioning review and cancellation use.

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 to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use the tool, though it doesn't explicitly 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 are all false, so the description carries the burden, and it delivers richly. It discloses the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and maintenance ('The team reads digests daily'). This goes well beyond the annotations.

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

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

The description is longer than ideal but each sentence earns its place—purpose, usage, exclusions, token flow, roadmap impact, rate limit, and cost are all relevant. It is front-loaded with purpose and structured logically, though slightly verbose in the middle sections.

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

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

Given the tool's moderate complexity and no output schema, the description covers all essential context: what it does, when to use or avoid, how to structure feedback, the claim_token follow-up mechanism, and privacy (don't paste end-user prompts). No critical information is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine value beyond the schema: for claim_token, it explains the exact invocation pattern ('with no other arguments'), and for message, it adds 'don't paste the end-user's prompt' which is not in the schema. These semantics help an agent use parameters 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 explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings by clearly limiting scope to 'tools served by this Pipeworx connection' and excluding other MCP servers. This provides a specific verb + resource + scope, and contrasts with sibling tools 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?

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use exclusion: 'if the tool came from a different MCP server... file it with that server instead.' Even includes a disambiguation for identifying Pipeworx 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?

Beyond annotations (readOnly, idempotent, etc.), the description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and that it's self-aggregating. 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?

Two sentences followed by bullet points. Every sentence adds value without redundancy. Front-loaded with the core action, then use cases and context. No fluff.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description provides complete context: what it returns, use cases, caching, privacy, and data source. Annotations richly cover behavioral hints. Nothing missing.

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

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

The schema covers the 'window' parameter with enum descriptions (100% coverage). The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaningful behavioral guidance 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 it returns 'top tools, top packs, and total call volume' over a window. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on trending signals rather than listing all tools or answering 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?

Three concrete use cases are listed (discovering hot data sources, confirming canonical tools, seeing use case alignment). While it doesn't explicitly say when not to use it or mention alternatives, the guidance is clear and actionable for an AI agent.

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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral context: fill check logic, semantic anchor similarity filter, partition filter with placeholder fraction, and warning against trading when realizable edge ≤ 0. 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?

Well-structured with clear sections for modes, filters, and response format. Every sentence adds value, though some technical details (like Jaccard threshold) could be compressed. Length is justified by complexity.

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

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

No output schema, but description fully details response structure (opportunities array, partition_check, fill check). Covers error conditions (skipped_low_similarity, placeholders_filtered) and trade advice, making it complete for agent use.

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 significant meaning: explains each parameter's purpose, provides example values (e.g., 'fed-decision-may-2026'), and notes that full URLs are accepted. Goes well beyond basic 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection across events.

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

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

Provides explicit guidance on when to use each mode: no args for trending scan, 'event' for specific markets, 'topic' for cross-event scanning. Also directs users to polymarket_fill_risk for custom sizing, making selection 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, etc. The description adds valuable context: caching behavior ('Cached 1h at the KV level'), response structure including diagnostics, and how edge is calculated. 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 quite long (over 400 words) and dense with technical details. While well-structured with sections, it could be more concise. The front-loaded purpose sentence is helpful but the overall length may hinder quick parsing by an agent.

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

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

Given the complexity and no output schema, the description is remarkably complete. It explains the three model segments, response top-level fields (by_segment, fed_candidates, _diagnostics), knobs, and even diagnostics for empty segments. It covers all necessary context for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds context on how knobs like min_liquidity and max_spread_pp filter tradeable edges, and explains the purpose of min_partition_leg_kelly. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool scans top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies the models used and segments, making it distinct from siblings like polymarket_arbitrage which likely focus on pure arbitrage.

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

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

The description mentions 'what should I bet on today' as a use case, but does not explicitly state when not to use it or provide alternatives. Given the sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker), more explicit guidance would help differentiate.

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 no destructiveness. The description adds significant behavioral context: it uses daily snapshots, tracks time-series, computes trend and decay, handles expired opportunities, and notes limits (60-day TTL, snapshot enablement). No contradiction with annotations.

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

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

The description is dense with information but front-loaded with purpose. Every sentence contributes value, but it could be slightly more concise by trimming redundant phrasing while retaining all key details.

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

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

Given the complexity of time-series tracking and lack of output schema, the description fairly completely covers response fields (tracked, expired, snapshot_dates) and limits. Minor gaps like missing pagination or examples are acceptable for this type of 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% with descriptions for both parameters. The description adds value by specifying defaults, clamp ranges, and the meaning of window families. It also explains the response structure, which is not in the schema.

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

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

The description clearly identifies the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis and answering a specific question about edge longevity.

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

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

The description explains when to use the tool (to assess if an edge is fresh or aged) and provides context about what differentiates a fresh wide edge from an old one. However, it does not explicitly state when not to use it or mention alternatives like polymarket_edges for raw snapshots.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are non-contradictory. The description adds behavioral details: walks the order-book ladder, returns specific fields like slippage_pp and forced_directional_risk, and warns about the dominant loss mode (unhedged directional positions from partial basket fills). This goes 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 thorough but slightly verbose. However, it is well-structured with capital labels (SINGLE-MARKET, BASKET) and bullet-like lists within prose. Every sentence adds value, but could be tightened slightly without losing meaning.

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

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

Despite lacking an output schema, the description fully documents return values for both modes: for single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.). It also covers edge cases like forced_directional_risk. The tool is complex, and the description is complete.

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

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

Even with 100% schema coverage, the description adds meaning: explains default size_usd (1000), clamp range (10-1,000,000), how size_usd is interpreted differently for single-market vs basket, and the auto-detection logic for side in basket mode. This significantly enriches 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 precisely states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth'. It clearly distinguishes between single-market and basket modes, and specifies the exact use cases (e.g., before acting on arbitrage signals). This leaves no ambiguity about what the tool does and how it differs from siblings.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable on thin books, partial basket fills create unhedged directional risk). This is exemplary usage context.

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

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

Even with readOnlyHint=true already set, the description adds substantial behavior beyond annotations: spreads are gross because Kalshi fees are not modeled, matches are keyword-based and unverified, compatibility warnings can be present even when pairs are returned, and unclassified legs are never paired. This is exactly the kind of non-obvious behavior an agent needs to trust the result.

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

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

The description is long, but the complexity justifies the length. It is front-loaded with a one-sentence summary, then modes, response shape, safety fields, and fee caveats. There is some redundancy in how compatibility fields are enumerated, but every paragraph 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 no output schema, the description does a remarkable job of covering output semantics: leg-level prices, top_spreads_pp, compatibility codes, temporal alignment behavior, skipped-counter fields, and the standing fee disclosure. An agent has enough information to invoke the tool and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining that topic auto-fetches a pre-mapped event, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matching logic. It falls short of 5 because, with 0 required parameters, it never states what happens if no parameter 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 first sentence states the resource clearly: a cross-venue spread between Kalshi and Polymarket for the same resolving question. The description is not a tautology and clarifies what kind of delta is meaningful. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage, so it misses the top score on this dimension.

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 rich usage context: two invocation modes, override semantics, and the warning that pre-mapped topics are often not tradeable. It does not explicitly state when to choose this tool over alternatives, but the mode guidance is clear enough for an agent to decide how to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and pairing with remember/forget, providing useful context beyond annotations. No contradictions.

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

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

Efficient, well-structured three sentences. Front-loaded with purpose, then usage details. 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?

For a simple tool with one optional parameter and no output schema, the description fully covers usage, scoping, and relationship to siblings.

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

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

Schema coverage is 100% with one optional key parameter. Description adds that omitting key lists all keys, which is not in schema description, adding significant 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?

Description clearly states the tool retrieves a value saved via remember or lists all keys, distinguishing it from sibling tools (remember, 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?

Explicitly states when to use (look up context stored earlier) and mentions pairing with remember/forget. Lacks explicit when-not or alternatives, but the context is clear enough.

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 states that setting mark_read=true flags events as read, modifying state. However, annotations declare readOnlyHint=true and idempotentHint=true, indicating no state change. This is a direct contradiction, leading to a score of 1 and annotation_contradiction=true.

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 concise sentences, starting with the main purpose. Each sentence adds essential information: return fields, filtering, mark_read behavior, and alternative access. 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 no output schema, the description sufficiently explains the return structure (source, citation_uri, raw payload). It covers key behaviors like mark_read and unread_only. Missing details on default ordering or error conditions are minor 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. The description adds value by explaining the effect of mark_read and providing examples like 'sec_8k' for type. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed.' It specifies the resource (fired events/alerts) and action (pull), and distinguishes from siblings like 'list_subscriptions' which lists subscriptions rather than events.

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 usage context: filtering by type and since, managing read status with mark_read, and mentions an alternative URL for scripts and dashboards. It lacks explicit when-not-to-use compared to other tools, but the context suggests it's for reading existing alerts.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds substantial behavioral context: it makes one parallel call, fans out to multiple sources, soft-fails for patents due to API sunset, accepts ISO date or relative shorthand, returns structured changes grouped by source. 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 moderately long but efficient. It front-loads with example queries, then concisely details behavior, parameters, and return structure. Every sentence adds value. A very minor reduction for slight verbosity in the source listing, but overall well-structured.

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

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

Despite no output schema, the description details return structure: 'changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It also mentions soft-fail for patents and the parallel call behavior. For a tool with multiple data sources and no output schema, this is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%. The description adds meaning beyond the schema: explains `type` is limited to 'company', `value` can be ticker or CIK, and `since` accepts ISO date or relative shorthand with a recommendation ('30d' or '1m'). It also clarifies the window semantics in context.

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

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

The description starts with concrete example queries ('What's new with X', 'latest on Y'), then clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It specifies data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from sibling `entity_profile`. The purpose is unmistakable.

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

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

The description explicitly tells when to use `entity_profile` instead ('when you want the static profile... regardless of window'). It also clarifies the tool handles multiple sources in one call, with fallback behavior (GDELT→GNews). No mention of when not to use beyond the sibling alternative, but that is sufficient for clear 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 indicate idempotentHint=true and destructiveHint=false, and the description adds behavioral context: key-value storage, scoping by identifier, and retention details (persistent for authenticated users, 24 hours for anonymous). No contradiction with annotations.

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

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

The description is a single paragraph that covers purpose, usage, paired tools, and retention. It is reasonably concise and front-loaded with the main function, though it could be slightly more terse.

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

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

With only two simple required parameters and no output schema, the description adequately covers the tool's behavior: it explains what it stores, how it is scoped, and how it integrates with other tools. No significant gaps.

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

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

Schema coverage is 100% (both parameters described). The description adds value by providing example keys (e.g., 'subject_property', 'target_ticker') that clarify usage beyond the schema's generic descriptions.

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

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

The description clearly states the tool's purpose: saving data for reuse across conversations and sessions. It provides specific examples (resolved ticker, target address, user preference) that distinguish it from sibling tools like 'forget' and 'recall'.

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 advises using the tool when discovering something worth carrying forward and mentions pairing with 'recall' and 'forget'. It differentiates persistence between authenticated and anonymous sessions, offering clear context for when 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?

The description goes well beyond the readOnly/idempotent annotations by revealing multi-source cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, behavior on ambiguous matches (returns figi_candidates rather than asserting), explicit unresolved fields, and how ISINs map to legal entities. This is exactly the kind of behavioral context an agent needs and the annotations alone do not provide.

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

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

The description is dense and front-loaded with user query examples, but it is somewhat sprawling with long parenthetical clauses and run-on sentences. Every sentence adds value, though the structure could be tightened with clearer separation of behavior, supported types, and input constraints.

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 multi-source tool with no output schema, the description is remarkably complete: it covers supported entities, accepted input forms, return fields, ambiguous-match behavior, unresolved identifiers, and degradation. An agent has enough context to invoke this tool correctly in almost all described scenarios.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it gives concrete examples for both type and value, explains ticker/CIK/name variations, and warns against passing full noun phrases for bond issuers. This materially improves correct parameter usage.

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

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

The description states a specific, concrete job: resolve a user-spoken name to canonical/official identifiers that other tools require as input. It goes beyond a generic verb by enumerating supported entity types and the kinds of user phrasings it handles, making its role distinct from siblings like entity_profile or compare_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?

It gives explicit usage context: 'Use FIRST whenever you have a name but need an ID,' which clearly indicates when an agent should reach for this tool. It does not explicitly name alternatives or specify when not to use it, but the supported query patterns and input examples provide strong situational 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, destructiveHint. The description adds behavioral context: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. This enriches understanding 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 purpose, no wasted words. Every sentence adds value: main action, internal method, example use case, output details.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers the tool's purpose, internal behavior, and output format. It explains the probing mechanism and return metrics, which is sufficient without an output schema.

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

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

Schema description coverage is 100% with each parameter described. The description adds extra meaning: first entity treated as 'subject' for narrative, rest as competitors. Provides example for 'context' parameter. Adds value beyond schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verb and resource. It distinguishes from sibling tool ai_visibility_check by focusing on multiple entities and ranking. Example use case enhances clarity.

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 it's useful for competitive AI-marketing audits and explains when to use (comparing your brand + N competitors). It lacks explicit when-not-to-use or alternative mentions, but the context is clear enough for an agent.

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, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: it fans out to two external services, returns a structured summary block with specific fields, per-advisory details, links, and recent alternative versions. It also discloses that bundlephobia's first measurement can take 5-30 seconds and that sources_failed will list timeouts gracefully.

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 and front-loaded with the core purpose. Each sentence adds value: high-level purpose, details of what is checked, usage examples, ecosystem limitation, and failure behavior. No redundant information.

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

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

Given the tool's complexity (fans out to two services, returns structured data, handles partial failures), the description covers all necessary aspects: exact return fields (summary block), advisory details, links, recent versions, timing on bundlephobia, and fallback for other ecosystems. Since there is no output schema, the description adequately explains the return format.

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 mentioning that scoped packages (e.g., @types/node) are accepted for the package parameter, and that the version parameter defaults to the latest published version. This extra context justifies a score above the baseline of 3.

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

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

The description clearly states the composite check for npm packages, specifying it fans out to deps.dev and bundlephobia for license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It distinguishes from siblings by noting the npm ecosystem limitation and fallback for other ecosystems, making the purpose specific and actionable.

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

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

Explicit when-to-use guidance is given: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also specifies when not to use it (non-npm packages) and points to the alternative fallback (deps.dev:version directly). Partial failure handling is clearly explained.

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

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

Adds context beyond annotations: specifies search domain (SG stats), keyword-based search, and output format. Annotations already cover safety and idempotency, so description enhances behavioral understanding.

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 with no filler. Efficiently conveys core functionality and relationship to sibling tools.

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?

Simple tool with complete annotations and schema. Description explains output and ID usage. No need for more given low 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% with descriptions for both parameters. Description provides examples but adds limited new meaning beyond schema. 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?

Description clearly states it searches Singapore official statistics tables by keyword, returns resource ids and titles, and distinguishes from siblings by mentioning table_data and table_metadata.

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

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

No explicit when-to-use or when-not-to-use for alternatives, but implies use to get resource IDs for table_data and table_metadata. Lacks guidance on when to prefer this over other search tools.

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

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

Annotations already mark the tool as read-only, idempotent, etc. The description adds technical details: BGE embeddings, 500-char windows, 200K char cap with truncation flagging, providing 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 two sentences plus a technical note, front-loaded with the core action and use case. Every sentence serves a purpose 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?

Given no output schema, the description adequately explains return content (passages with offsets and scores) and notes technical limits. It covers the main context needed for correct invocation.

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

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

Schema coverage is 100%, and the description adds value with default/range for limit, examples for query, and a constraint on text size (200K chars). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('search'), resource ('inside a fetched record'), and details on output (passages with offsets and scores). It distinguishes from siblings by mentioning the 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?

The description explicitly advises using when the record is too large for the prompt and explains how it reduces context usage. It also notes pairing with ask_pipeworx_grounded, though it does not explicitly list 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description confirms it creates a subscription (write, non-destructive, idempotent). It adds behavioral details: webhook secret returned only once, auto-disable after 10 failures, SMS cap, phone verification requirement. 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: first sentence states purpose and return value, then requirements, then type-specific details, then delivery channels. Every sentence adds value without redundancy. Front-loaded with key information.

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

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

Given no output schema, the description explains the return value ('new subscription id'). It covers all parameters with examples, side effects (webhook secret one-time), and constraints (sms cap, phone verification). The tool's complexity (multiple types, delivery channels) is fully addressed.

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 goes far beyond: it explains each type's params with syntax examples, delivery channel options with constraints, webhook signing mechanics, and phone verification requirement. This adds significant 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The scope (types, delivery channels) is explicit.

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 specifies when to use (creating a subscription for live data events) and requirements (Pipeworx OAuth account). It gives detailed type examples. While it doesn't explicitly state when not to use, the context and sibling tool names imply alternatives for modification and listing.

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

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

Annotations already declare readOnlyHint=true and non-destructive, so tool is safe. Description adds useful context about returning live example questions with exact tool calls, but doesn't add new behavioral constraints. 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?

Description is packed with information but front-loaded with user queries. Slightly long but every part is useful; minor improvement could trim redundant phrasing.

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 discovery tool with one optional param and no output schema, description explains return structure (category-bucketed examples with tool calls) adequately. Could mention output format type 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 coverage is 100% and description adds value by listing example values for topic and explaining omission behavior, going beyond the schema 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 it's an onboarding entry point that returns category-bucketed example questions, distinguishes from sibling tools like ask_pipeworx by being the first-use tool. Includes specific verbs and examples.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and gives context for when to call (agent just connected). Mentions alternatives implicitly via '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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return structure (Data with row array of series containing dated columns). 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 three sentences: first sentence gives core purpose and data structure, second explains filtering, third covers pagination. It is front-loaded and concise with 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?

Despite no output schema, the description explains the return format (Data with row array of series containing dated columns). It covers filtering and pagination. Parameter count is 7 but required only 1, and schema provides descriptions. The description is sufficient for correct usage.

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

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

Schema description coverage is 100%, so all parameters are described in the schema. The description mentions timeFilter and between specifically but does not add substantial meaning beyond the schema. 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 fetches time-series data rows for a Singapore statistics table by resourceId, distinguishing it from sibling tools like search_tables (which retrieves IDs) and table_metadata (likely metadata). It also describes the returned data structure.

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

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

The description explains when to use (after getting resourceId from search_tables) and how to filter time periods with timeFilter or between and paginate with offset/limit. It does not explicitly state when not to use or provide alternatives, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral detail: the result location under 'Data.records' and the specific fields returned (theme, subject, frequency, period coverage, variables/series). This adds value beyond annotations, though it could mention error handling or data limits.

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

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

Two concise sentences. The first sentence captures the core purpose and required input, the second tells where to find the result. No superfluous words, well-structured.

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

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

Given the tool's simplicity (1 parameter, no output schema, but rich annotations), the description is fairly complete. It lists the types of metadata returned and the location. Missing details like data format or pagination, but these are minor for such a tool.

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

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

Schema description coverage is 100% for the sole parameter 'resourceId', with a clear description and example. The tool description repeats the example but does not add new semantic information. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the verb 'Get' and the resource 'structure/metadata for a Singapore statistics table'. It also tells how to obtain the required resourceId from the sibling tool 'search_tables', making the purpose unambiguous.

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

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

Explicitly instructs to 'get ids from search_tables', which tells the agent when to use this tool (after obtaining a resourceId). It does not explicitly state when not to use, but the context is clear. A more detailed exclusion would improve it further.

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 non-destructive (destructiveHint false). Description adds valuable detail: deactivation (not deletion) preserves historical events via recent_alerts, enriching behavioral understanding 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 efficiently convey main action, constraints, and behavioral nuance. No redundant information; every sentence earns its place.

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

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

Covers key aspects: ownership, soft-deletion, and linkage to recent_alerts. No output schema needed for this simple idempotent tool. Could mention error handling or return value, but overall complete for the use case.

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

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

Schema covers 100% of parameters with a clear description ('Subscription id (uuid) returned by subscribe'). Description does not add further parameter semantics, so baseline score of 3 is appropriate.

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

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

The description clearly states the action (Cancel) and resource (subscription by id). It distinguishes from siblings like subscribe and list_subscriptions by specifying ownership enforcement and soft-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?

Explicitly states ownership enforcement (only cancel own subscriptions), providing clear usage boundaries. Lacks explicit mention of alternatives, but the context is sufficient for agent decision-making.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the two-pipeline routing (SEC EDGAR for financial claims vs. grounded pipeline for others), the exact verdict options, and the critical distinction between 'could_not_verify' and 'unsupported'. It also explains the verification_error payload and how to interpret non-results, which is essential behavioral context not captured by annotations.

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

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

The description is longer than the ideal two-sentence example but front-loads the purpose with concrete examples and use cases. Each subsequent section (pipeline routing, verdict types, error semantics, efficiency claim) earns its place with actionable details. It is well-structured and avoids repetition, though it could slightly trim redundant phrasing.

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

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

Given the tool's complexity (two pipelines, nuanced verdicts, error states) and the absence of an output schema, the description thoroughly covers return values, verdict semantics, and error handling. It also states the efficiency advantage over sequential calls, making it self-contained for an agent to invoke and interpret results.

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

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

The schema already provides descriptions for both parameters (100% coverage). The description adds significant nuance: tolerance_pct overrides the wording-implied tolerance with a default cap of 5, and is explicitly useful for hallucination detection where material errors must be refuted. It also explains claim routing based on claim content, enriching the semantic understanding of the 'claim' parameter.

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

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

The description explicitly states it performs natural-language claim verification against authoritative sources, using specific verbs like 'fact check' and 'verify the claim'. It distinguishes from sibling tools by focusing on factual claim checking and noting it replaces 4–6 sequential calls, making its purpose unambiguous.

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

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

It provides clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other claims, and describes when to use a custom tolerance for hallucination detection. However, it does not explicitly name alternative sibling tools or state when not to use it beyond the general claim focus.

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