Country State City

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds that the tool returns per-model {score, confidence, signals, raw_response} + combined view, and that _apiKey is passed to Anthropic. It does not mention rate limits or cost, but adds meaningful 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 a single paragraph that efficiently conveys purpose, usage, return format, and parameter nuances. It front-loads the main action. A more structured format (e.g., bullet points for returns) would improve readability, but current version is not verbose.

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 and no output schema, the description covers return format sufficiently, explains the apiKey flow, and specifies default model. Minor omissions like error handling or timeout behavior exist, but the essential information for correct invocation 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?

Schema coverage is 100% with parameter descriptions. The description supplements by explaining the default model, the role of _apiKey, and gives examples for entity and context. This adds value beyond the schema, raising it 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 tool probes LLMs for knowledge about a business/brand/product/topic and returns visibility scores. It uses specific verbs like 'probe' and 'score', and names the resource. Though there is a sibling tool 'scan_competitor_ai_presence' that could overlap, the description does not explicitly differentiate, preventing 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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to provide _apiKey (for Anthropic) and defaults to Workers AI. However, it does not state when to avoid this tool or suggest alternatives like scan_competitor_ai_presence.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those: it routes across 5,743 tools and 1,500 verified sources, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. It does not disclose failure modes or caveats, but the annotation coverage lowers the bar.

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

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

The description is longer than average but information-dense: it front-loads the primary directive, lists supported domains, gives examples, states the default-entry position, and names escalation paths. Each sentence earns its place; the structure is scannable despite the length.

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

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

For a broad routing tool with no output schema, the description is remarkably complete: it defines the answer format (structured with citations), explains when to use it, when not to use alternatives, what it routes through, and provides representative example queries. An agent has enough context to invoke it correctly in most situations.

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

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

Schema description coverage is 100% and all six parameters are documented aliases of 'question', so the schema already carries the parameter semantics. The description reinforces natural-language phrasing and gives concrete examples, but it does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a clear verb+resource: ask a natural-language question and Pipeworx routes it to the right tool, returning a structured answer with citation URIs. It also explicitly differentiates itself from ask_pipeworx_grounded and deep_research by naming their distinct behaviors.

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

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

The description gives explicit when-to-use guidance: prefer over web search for data-oriented questions, use for 'what is', 'look up', 'get the latest', factual questions, and START HERE as the default entry point. It also names concrete alternatives for escalation: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions.

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

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

The description goes well beyond the annotations by disclosing that candidate routing improvements are live only when under test, that no candidate is currently active, and that results are compared against the stable router. It also manages expectations around experimental behavior while confirming operational parity with ask_pipeworx.

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

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

The description is detailed and well-structured, front-loading the beta relationship and current parity status. It is slightly long, but each clause contributes useful context about experimental risk, routing behavior, and how to use the tool.

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

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

For a complex router tool with no output schema, the description provides strong contextual completeness: it explains the beta status, current no-candidate state, exact parity with ask_pipeworx, and intended experimental use. An agent has enough information to decide when and how to invoke it.

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

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

Schema description coverage is 100%, with 'question' and all five aliases documented. The description mentions 'same arguments' but adds no substantive parameter detail beyond the schema, so the baseline 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 defines this as the beta version of ask_pipeworx: a universal router with the same 5,743 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx and names the sibling tool, so an agent can tell them apart.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that this is a full working router, not a fallback. However, it does not explicitly state when to prefer the stable ask_pipeworx or ask_pipeworx_grounded, leaving that to inference.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar for added context is high. The description goes well beyond by specifying the exact success return shape, the refusal rejection object with five concrete failure reasons, and the extra LLM call cost. This directly informs agent expectations about side effects, cost, and error modes.

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 clause earns its place: purpose, routing relation, extraction constraint, output contract, refusal semantics, use cases, and cost trade-off. It is front-loaded with the core purpose and then systematically builds behavioral detail without filler.

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

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

Despite having no output schema, the description fully documents the return payload and refusal variants, so the agent knows what to expect. It also explains the routing behavior, the single-extra-call cost, and when to select the sibling. Nothing necessary for correct invocation or outcome interpretation is missing.

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

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

The input schema covers 100% of parameters, including documenting all six aliases for the single required question parameter. The description adds no additional parameter-specific meaning, which is acceptable because the schema already carries the burden. A baseline 3 is appropriate.

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

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

The description opens with a precise verb-resource pairing: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly relates to ask_pipeworx while distinguishing itself by what it adds — grounded extraction and explicit refusal. An agent can distinguish it from the sibling tools immediately.

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

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

The description says exactly when to use it: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and a cost-based exclusion criterion, leaving no ambiguity.

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 provides extensive behavioral details beyond the annotations (readOnlyHint=true, etc.). It explains market resolution, classification, fan-out, response shapes, resolver contract with confidence levels, parent event extraction, news fallback behaviors, safety short-circuits for low confidence or closed markets, wide-spread illiquidity handling, and cancellation rules. No contradictions with annotations.

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

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

The description is long but front-loaded with the core purpose and usage. It efficiently packs many behavioral details into clearly separated sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value, though some details (e.g., candle-stick futures from 2026) could be streamlined. Overall, it is well-structured for the complexity.

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

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

Given the tool's complexity and lack of output schema, the description covers the return structure comprehensively (market, analysis, evidence, match confidence, parent events, news fields). It also documents error/edge cases (low confidence, closed markets, wide spreads). A minor gap is not enumerating all possible data sources, but the fan-out examples suffice.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mostly reiterates the parameter purposes from the schema. While the description provides examples of usage, it does not clarify parameter constraints or edge cases beyond what the schema already captures.

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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the inputs (market slug, URL, or question text) and explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which serve narrower purposes.

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

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

The description provides explicit use cases for when to use this tool ('Use for...'), giving clear context. However, it does not explicitly mention when not to use it or name alternatives among sibling tools, which would strengthen guidance. The examples effectively imply the tool is for comprehensive research, not quick checks or arbitrage.

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?

Annotated as read-only and non-destructive. Description adds behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, results sorted by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

Description is packed with useful information but is slightly verbose. It front-loads common queries effectively. Could be shortened slightly without losing clarity, but still highly efficient.

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

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

Given the complexity (two entity types, multiple metrics, fiscal year handling), the description covers all essential aspects: data sources, sorting, citation URIs, and efficiency gains. No output schema, but return format is adequately implied.

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

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

Schema has 100% coverage; description adds meaning by explaining what each entity type pulls (financials vs. adverse events/trials) and the constraints on the values array (min 2, max 5). Also clarifies usage of tickers/CIKs vs. drug names.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using verbs like compare, and lists common user queries. It distinguishes from sibling tools by advocating preference over sequential single-pack lookups.

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

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

Explicitly tells when to use: for comparison queries like 'X vs Y', 'rank these companies', and 'head to head'. It strongly recommends this tool over alternatives (ALWAYS PREFER over sequential lookups) and provides examples.

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. The description adds substantial behavioral context: parallel routing across 5,743 tools, returns findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, guaranteed fetchable citations, semantic excerpting, and expected latency ranges. It also notes empty gaps[] for topics outside the catalog. 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?

While long, every sentence carries essential information: account requirements, core function, usage guidance, depth modes, output structure, and performance expectations. It is logically ordered (account → purpose → usage → technical details) with no filler or 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?

This is a complex tool with no output schema, so the description must explain return values. It covers the full packet structure (evidence, confidence, source, citations, gaps, contradictions, hop), explicates depth behaviors, cites latency, and addresses edge cases (empty gaps for out-of-catalog topics). All necessary information for correct invocation and interpretation 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?

Schema coverage is 100%, and the description goes well beyond it. It explains the depth parameter's enum values in detail (quick vs standard vs thorough), including the gap-recovery and contradiction-scan behaviors, and clarifies that question can be broad/multi-part. This enriches the schema meaning significantly.

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

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

The description states a specific verb ('research') and resource ('Pipeworx's 1500 STRUCTURED data sources'), and explicitly distinguishes itself from open-web search and from the sibling tool ask_pipeworx. It names what it is not ('NOT open-web search') and what it is best for, making the purpose unambiguous.

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

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

Provides explicit when-to-use ('broad/multi-part questions over structured data') and when-not-to-use scenarios ('single lookup' → ask_pipeworx, 'BREAKING or colloquial CURRENT-NEWS' → prefer ask_pipeworx). It also explains depth tiers and account requirements, eliminating ambiguity about 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N tools with schemas and examples, ready to call directly, which provides useful context beyond annotations. No contradiction.

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

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

The description is front-loaded with purpose, then lists domains, then describes output, then gives usage advice. Every sentence is necessary and well-placed, no 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 the tool's role as a discovery tool among many siblings, the description covers purpose, usage, return value, and guidance. No output schema exists, but the return format is described in words. It is complete enough 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% with examples, so baseline is 3. The description does not repeat parameter details but the schema and curated examples in the input schema clarify the query parameter and its aliases. The description adds value by mentioning the return format, keeping it concise.

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 'Find tools by describing the data or task' and lists many specific domains, distinguishing it from sibling tools by positioning it as a meta-tool for discovery. It also explicitly advises to call it first when many tools are available.

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

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

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by domains, and 'Call this FIRST when you have many tools available and want to see the option set'. This tells the agent when to use and implies not to use if the tool is already known.

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, openWorld, idempotent, non-destructive), the description discloses important behaviors: parallel fan-out, soft-fail for USPTO patents sunset, empty fda_products as expected rather than an error, resolved:false for private companies, and sources_used/sources_failed as data-integrity signals. This is substantial value beyond what annotations provide.

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

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

The description is long, but it is dense and structured, with each clause adding necessary detail about sources, return fields, or failure semantics. It front-loads the core purpose before enumerating outputs. It could be slightly more scannable with bullet formatting, but there is little wasted prose.

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

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

For a complex tool with no output schema, the description effectively serves as the complete contract: it covers all inputs, all output sections, failure modes, resolution behavior, and interpretation guidance. Nothing an agent needs to know to call this correctly is missing.

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

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

The schema already covers both parameters fully (100% coverage), so the baseline is 3. The description adds meaningful examples — 'AAPL', '0000320193', 'Moderna' — and clarifies that 'company' and 'ticker' behave identically, plus explains name resolution via SEC EDGAR. This lifts it above baseline, though the schema already captures the core semantics.

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

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

The description opens with concrete example queries and a clear statement: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack SEC/XBRL/news lookups and enumerates its coverage across SEC EDGAR, XBRL, patents, contracts, FDA, hiring, news, and LEI, leaving no ambiguity about what the tool does.

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

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

It explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It also covers edge cases — private companies, name vs ticker input, and expected empty sections — giving clear guidance on when the tool is appropriate and how to interpret results.

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?

Discloses destructive nature ('Delete') consistent with destructiveHint annotation. Adds context about clearing sensitive data and pairing, though idempotentHint is not explained. Still, adds 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, front-loaded purpose, no unnecessary words. Every sentence adds value.

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

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

For a simple deletion tool with one parameter and no output schema, the description fully covers purpose, usage conditions, and relationships to sibling tools.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete.' Description adds no extra meaning beyond what schema provides, meeting baseline.

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

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

Description clearly states 'Delete a previously stored memory by key,' specifying the verb and resource, and distinguishes from siblings like remember 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?

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Mentions pairing with remember and recall, guiding the agent on alternatives.

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

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

The description adds behavioral details beyond the annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. The annotations already indicate a read-only, idempotent operation, and the description aligns with 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 concise and front-loaded: first sentence states the core function, then gives a brief process, output format, and use cases. Every sentence adds value 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?

The tool is simple with strong annotations and full schema coverage. The description covers purpose, process, output, and use cases, making it sufficient for an agent to use without additional 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?

The input schema has 100% description coverage for both parameters ('url' and 'max_links'), so the description adds minimal extra meaning beyond what the schema provides. It does not elaborate on parameter formats or constraints.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the exact verb and resource ('generate', 'llms.txt file'). It differentiates from sibling tools by its unique function, as no other sibling tool generates llms.txt files.

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

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

The description provides explicit use cases: getting a client's site indexed by AI, drafting for a project, or auditing competitor sites. It gives context for when to use the tool but does not include when-not-to-use or alternative tools.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds filtering behavior and examples but doesn't address rate limits, authentication details, or response format beyond what annotations provide.

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

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

Two sentences with no wasted words. The first sentence states the purpose and filtering capability; the second provides parameter examples. Front-loaded and efficient.

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

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

For a simple read-only lookup tool with full schema coverage, annotations, and an output schema, the description is complete. It covers all necessary context: what the tool returns, required parameters, optional filters, and usage examples.

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 all three parameters. The description adds concrete examples (e.g., 'US', 'CA') that are not in the schema, providing practical usage context beyond the bare parameter names.

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

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

The description clearly states the tool retrieves cities for a country with optional state filtering, using specific verbs and resource types. It distinguishes itself from sibling tools like 'get_states' and 'list_countries'.

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 required (country_code) and optional (state_code) parameters with examples (e.g., 'US', 'CA'). While it doesn't explicitly state when not to use or direct to alternatives, the context from sibling tools provides implicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond confirming it returns 'state names, codes, and types'. It is consistent with annotations and avoids contradiction.

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

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

The description is a single, efficient sentence that conveys all necessary information without any wasted words. It is well-structured and front-loaded.

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

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

For a simple lookup tool with comprehensive annotations and an output schema, the description is complete. It specifies input (ISO2 code) and output (names, codes, types), and the tool's behavior is fully understood.

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 clarifying that country_code is an ISO2 code and mentioning the output fields (names, codes, types), going beyond the schema.

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

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

The description clearly states 'Get all states or provinces for a country by ISO2 code' using a specific verb ('Get') and resource ('states or provinces'). It distinguishes from sibling tools like 'get_cities' and 'list_countries' by focusing on states/provinces.

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 specifies when to use the tool: to get states for a country by ISO2 code, with examples ('US', 'IN', 'BR'). It does not explicitly mention when not to use it or list 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 provide readOnlyHint, idempotentHint, etc. The description adds behavioral context like returning ~250 countries and specific fields, which goes beyond annotations without contradicting them.

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

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

Two sentences with no waste. The first sentence lists the purpose and data, the second gives a typical use case. Front-loaded and efficient.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description is fully adequate. It explains the return fields and typical use, covering all necessary 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 description coverage is 100% for the single parameter _apiKey, so baseline is 3. The description adds no extra meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'List' and resource 'countries', specifies exactly what data is returned (ISO codes, capitals, etc.), and distinguishes from sibling tools like get_cities or get_states.

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 mentions use cases like 'building dropdowns or validating country data', providing clear context for when to use. It does not explicitly mention when not to use, but the sibling tools are sufficiently different to avoid confusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds return fields (id, type, params, created_at, last_fired_at, fire_count). 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?

Two sentences: first states purpose and output, second provides usage guidance. No redundant text; every sentence adds value.

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

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

Given the tool has 1 optional parameter and annotations cover safety, the description adequately covers purpose, return fields, and use cases. Lacks detailed return schema but lists fields.

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 schema fully documents the include_inactive parameter. The description adds no extra meaning beyond what the schema provides; baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb (list) and resource (subscriptions). It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' It does not specify when not to use or name alternatives, but context is clear.

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

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

With all annotations set to false, the description carries the full burden of behavioral disclosure and delivers richly: it discloses rate limiting (5 per identifier per day), the claim_token workflow for later retrieval, and that the tool is free and excluded from quota. It also clarifies the two-mode behavior (filing vs. checking with claim_token), which is far beyond what annotations alone convey.

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 six sentences and front-loads the core purpose, but includes secondary details like roadmap impact and digest cadence that are informative yet slightly beyond the essential usage guidance. Still, every sentence adds value and none are redundant.

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

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

There is no output schema, so the description appropriately explains the claim_token return value and how to follow up on a filed report. Combined with schema-level details, it leaves no operational ambiguity for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter-level nuance. It explains the claim_token parameter's role in reading prior feedback and instructs users to avoid pasting end-user prompts into the message parameter, which goes beyond schema boilerplate.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource framing that immediately identifies the tool's purpose. It also distinguishes itself from sibling research/query tools by clearly positioning itself as a feedback channel specific to 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 explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and when not to use it (feedback about non-Pipeworx MCP servers), directing users to file elsewhere. It also provides clear scope guidance: 'Pipeworx tool names are the ones this connection lists.'

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. The description adds valuable behavioral details beyond annotations: no PII, derived from CF analytics-engine, cached 5min-1h depending on window, and returns specific fields (pack, tool, count). This fully discloses 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 exceptionally concise: three sentences plus a bullet list of use cases. Every sentence adds value, no fluff. Front-loaded with the core purpose, then expands on use and implementation 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?

For a simple tool with one optional parameter and no output schema, the description is thorough: it states the return type (top tools, packs, volume), use cases, data source, privacy, caching behavior, and window interpretation. Nothing essential is missing.

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

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

Schema coverage is 100%; the only parameter 'window' has enum values described. The description adds meaning beyond the schema, explaining the trade-off between short and long windows. This provides pragmatic guidance.

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

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

The description clearly states it returns top tools, packs, and total call volume over recent windows. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trends and popularity.

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 three use cases: discovering hot data sources, confirming canonical choices, and checking alignment with other agents' needs. It also explains window trade-offs ('shorter windows surface what's hot right now; longer windows show steady-state demand'). While it does not directly name alternatives, the context is clear and well-motivated.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and output structure. No contradictions.

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

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

The description is well-structured, starting with the main purpose, then explaining each mode, and concluding with technical details. It is front-loaded with key information. However, it is somewhat lengthy and could be slightly more concise, especially the fill check section.

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 modes, multiple checks, no output schema), the description fully explains the response structure (opportunities[] and partition_check fields) and edge cases (fill check, placeholder filter, similarity threshold). It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the effect of no args, providing examples for event slugs and topic questions, and detailing the different behaviors for each mode (e.g., partition_check for event, cross-event scanning for topic).

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and details both event and topic modes. This distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk, which focus on different aspects.

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 no args (trending_scan), event (single-event partition_check), or topic (cross-event scan). It recommends event for a specific market and explains that cross-event mode catches patterns missed by single-event mode. It also advises not to trade when realizable_edge_pp ≤ 0.

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 read-only, idempotent, non-destructive. Description adds extensive behavioral details: caching, response structure (by_segment, diagnostics), edge calculation, slippage, tradeable-edge filters. 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?

Very detailed and well-structured, but overly verbose. Some information could be streamlined or moved to schema descriptions. The density of technical detail may overwhelm some agents.

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 fully explains the response format (by_segment, fed_candidates, diagnostics) and all edge calculations. Also covers caching and tradeable-edge knobs. Highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for several parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains why min_kelly doesn't filter partitions). This adds value beyond the schema.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with price. Specific verb 'scan' and resource 'Polymarket markets'. Differentiates from siblings by focusing on edge discovery for daily betting, but doesn't explicitly name alternatives.

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

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

Provides clear context for when to use ('what should I bet on today') and how it works. Describes three model families and constraints. Lacks explicit when-not-to-use or direct sibling comparisons, but the context is sufficient for most agents.

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

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

Annotations already mark the tool as read-only and idempotent. The description goes beyond by detailing the response structure (tracked, expired, snapshot_dates), explaining how decay_pp_per_day is computed, and noting that snapshots are written on cache-miss. It also clarifies that decay numbers are from daily closes, not intraday.

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

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

The description is well-structured with sections for purpose, response breakdown, and limits. It is concise yet thorough, though slightly lengthy. Every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly explains the response format (tracked array with fields, expired array with lifespan, snapshot dates). It covers the key elements needed for agent understanding.

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

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

Schema coverage is 100%. The description adds defaults for days (14, max 30, clamp 2-30) and window (default '1wk', options '24hr', '1mo'), which is valuable 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: tracking edge persistence and decay over time from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends and decay metrics.

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

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

The description implies when to use it (e.g., assessing edge age and decay) and provides limits (60-day TTL, snapshot gaps). It does not explicitly state when not to use it or name 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds behavioral context: walks the ladder, returns specific fields like verdict, profit_usd, thin_legs. It warns about forced directional risk and partial fills. No contradictions with annotations. Could mention any rate limits or data freshness, but otherwise comprehensive.

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

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

The description is relatively long but well-structured with capitalized mode headers (SINGLE-MARKET, BASKET) and explicit use-case guidance. It front-loads the core purpose. Every sentence adds value, though some could be tightened. Overall effective for the complexity.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is thorough. It covers inputs, modes, defaults, outputs (including verdict, capture_ratio, thin_legs), and practical risks (partial fills, directional risk). No gaps remain for an agent to understand correct invocation.

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

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

Schema description coverage is 100%, so baseline 3. However, the description adds significant meaning beyond the schema: explains single-market vs basket mode, default side logic, interpretation of size_usd (max spend vs target proceeds vs settlement notional). This elevates clarity beyond 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 clearly defines the tool's purpose as a realizable-vs-theoretical edge check against CLOB order-book depth. It distinguishes two modes (single-market and basket) and states the verb 'check'. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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: '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 on thin books is not capturable, partial basket fills lead to unhedged directional positions) and provides requirements (one of market or event).

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 readOnlyHint/idempotentHint annotations, disclosing an extensive set of behavioral traits: the compatibility_warning/compatibility_codes safety fields, the full taxonomy of mismatch reasons, the rule that unknown metric_type/match_subtype legs are never paired, the gross-vs-net fee disclosure, and the skipped_cross_type/cross_subtype counters. It also clarifies the nuanced temporal_alignment semantics (null means 'could not be computed', not 'aligned'), which is exactly the kind of behavioral context agents need.

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

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

The description is long, but every section earns its place given the tool's complex safety semantics. It is front-loaded with the core purpose and mode overview, then uses CAPS-labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) to structure the dense detail. Some redundancy exists — e.g., temporal_mismatch appears in both the code list and the flags description — but the organization makes the length acceptable.

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 available, the description carries the full burden of explaining the return shape, and it does so thoroughly: per-venue leg prices, top_spreads_pp units (Kalshi − Polymarket, in percentage points), per-leg flags, compatibility codes, skipped counters, fees_note, and temporal_alignment structure. It even addresses the practical reality that pre-mapped topics are often not tradeable. An agent has everything needed to call the tool and interpret its response.

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 meaningful semantics beyond the schema: it explains that topic activates a pre-mapped shortcut list, that explicit ticker/slug overrides the mapped side, and that both modes run the identical token-overlap matcher. It also provides the full enum-like list of valid topic values in prose, which helps agents select valid inputs.

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

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

The description opens with a precise statement of the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming both the resource and the operation. It further differentiates from adjacent tools by framing the output as a probability spread with safety disclosures, which is distinct from pure arbitrage or edge-tracking. The two-mode explanation (topic shortcuts vs explicit ticker/slug) reinforces the clear purpose.

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

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

The description gives explicit usage guidance for the two parameter modes — when to use the pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug — and even warns that 'most pre-mapped topics return compatibility_warning today.' It does not explicitly name alternative sibling tools, but for a tool with this unique cross-venue focus, the mode-level guidance plus the caution about tradeability serves as adequate usage direction.

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 safe read-only behavior; description adds scoping detail (identifier-based) without contradicting annotations.

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

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

Three concise sentences, front-loaded with main purpose, no wasted words.

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

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

Simple tool with one optional parameter, no output schema needed; description fully covers use cases, scoping, and companion tools.

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

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

Schema covers 100% of the single parameter; description adds value by explaining the dual behavior of retrieving a specific key vs. listing all when omitted.

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

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

Clearly states the tool retrieves a value by key or lists all keys, distinguishing it from sibling tools like remember and forget.

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

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

Explicitly describes when to use (look up stored context) and pairs with remember/forget, but does not state explicit when-not-to-use scenarios.

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 and idempotentHint. The description adds valuable context: that each alert carries source, citation_uri, and raw payload, and explains mark_read behavior. 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?

Concise 4-sentence description, front-loaded with main purpose. Each sentence adds meaningful information with no 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?

Comprehensive for a read-only tool with good annotations: explains return value structure, filtering, mark_read side-effect, and alternative access endpoint. No output schema, so return value explanation is 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% (baseline 3). Description adds semantic info for type (example 'sec_8k'), since (ISO timestamp), and mark_read (flags read). Does not describe limit or unread_only, but adds value beyond schema for key parameters.

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

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

The description clearly states the tool pulls fired events from the subscription feed, a specific verb+resource. It distinguishes from siblings like 'list_subscriptions' which list subscriptions, not alerts.

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

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

Provides clear usage context: filtering by type and/or since, mark_read behavior, and mentions polling works. Also notes an alternative HTTP endpoint for scripts/dashboards, but does not explicitly exclude cases or compare with all siblings.

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), the description details fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and the inclusion of citation URIs. No contradiction with annotations.

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

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

The description is well-structured and concise, with every sentence providing necessary information. It covers purpose, usage, parameters, and disambiguation without redundancy, making it easy for an agent to parse.

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

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

Given the tool's complexity (multiple sources, fallback behavior, flexible date input) and the absence of an output schema, the description adequately explains the return structure (changes grouped by source, total_changes count, citation URIs) and directs to entity_profile for alternative needs.

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 significant value by explaining acceptable formats for 'since' (ISO date or relative shorthand) with examples, and clarifying that 'value' accepts tickers or CIK numbers. It also notes that 'type' currently only supports 'company'.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call', listing specific data sources and example queries. It explicitly distinguishes from the sibling tool entity_profile, ensuring the agent can correctly differentiate.

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 examples ('What's new with X', 'latest on Y') and when-not-to-use by directing to entity_profile for static profiles. This clear guidance helps the agent select the appropriate tool.

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

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

Adds key behavioral details beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour TTL for anonymous sessions. 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?

Four sentences, each earning its place: main purpose, usage guidance, storage details, and pairing with siblings. Front-loaded with core action.

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

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

For a simple write-only tool with two parameters and no output schema, the description covers purpose, usage, storage behavior, and lifecycle. 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?

Input schema covers both parameters fully (100% description coverage). Description reinforces 'key-value pair' but adds no new parameter details beyond schema examples.

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

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

Clearly states the verb 'save', resource 'data', and scope 'across this conversation or across sessions'. Distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall/forget. Lacks explicit 'when not to use', but usage context is well-defined.

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

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

Annotations already indicate read-only, idempotent, open-world behavior, and the description goes well beyond by disclosing graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, `figi_candidates` returned on ambiguous matches, per-source identifier labeling, and the internal cascade of lookups. 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 front-loaded with user-phrase examples and the crisp 'Use FIRST' directive, and the long body is dense with useful behavior. It is somewhat verbose and repeats some information already present in the schema, so it does not earn a perfect conciseness score, but it is appropriately sized for the tool's complexity.

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

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

This is a complex multi-endpoint tool with no output schema, and the description covers return expectations (`figi_candidates`, `unresolved`, source labels), failure/degradation behavior, input formats, and type-specific edge cases. Everything an agent needs to decide when to call it and how to pass parameters correctly 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?

Schema coverage is 100%, but the description adds substantial semantic guidance: pass the ENTITY NAME ONLY, use the issuer exactly as printed for bonds, never include trailing security-class words, and accept ticker/CIK/ISIN/name for companies versus brand/generic names for drugs. These details materially prevent incorrect invocation.

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

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

The description states a specific action — resolving a user-spoken name to canonical/official identifiers — and names the supported entity types (company, drug) with their concrete outputs. It also frames the tool as the first step when a name needs to become an ID required by other tools, which distinguishes it from sibling lookups 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and gives examples of when this is appropriate, including bond issuers and ISIN lookups. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it probes each entity with another tool and returns ranked output, but no additional behavioral details (e.g., rate limits, cost, or time impact) beyond what annotations cover.

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 of four sentences, front-loaded with the core purpose. It is concise but could be slightly more structured (e.g., separate output details). No unnecessary words.

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

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

Given no output schema, the description adequately explains the return values (ranked list with score, confidence, signal density). It does not cover edge cases like error handling or parameter interactions, but overall it is sufficient for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on parameter details beyond what the schema already provides; it only mentions entities and context in passing.

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, probes each with ai_visibility_check, ranks, and returns a ranked list with scores. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-marketing audit context and use of ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example. It implies usage for multi-entity comparison but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single-entity checks.

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 (readOnlyHint, idempotentHint, openWorldHint), the description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and efficiently conveys guidance, return details, limitations, and behavior. While dense, every sentence is meaningful; could be slightly more concise but current length is acceptable.

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 lists return fields (summary block, per-advisory detail, links, alternative versions). It also covers edge cases (NPM-only v1, partial failures) and implicit requirements (network access). Complete for a 2-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted for 'package' and that 'version' defaults to latest when omitted. This justifies a score above baseline.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages across deps.dev and bundlephobia. It uses specific verbs ('scan') and resources ('dependency') and distinguishes itself from siblings like 'scan_competitor_ai_presence' by its unique function.

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 guides when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem limitations and alternatives (deps.dev:version for non-NPM).

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

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

The description adds significant behavioral details beyond annotations: explains embedding model, window size, character cap (200K) with truncation and flagging, and that each passage includes an offset for verification. 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 (~100 words) and well-structured: starts with purpose, then usage guidance, then technical details. Every sentence adds value with no 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 the tool's complexity (3 parameters, no output schema), the description covers return values (top-N passages, offsets, scores), truncation behavior, and integration with siblings. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, providing baseline 3. The description adds examples for query and extra context for text (e.g., SEC 10-K body), enhancing usability without repeating schema details.

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

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

The description clearly states the tool performs semantic search within a provided text, returning top passages with offsets and scores. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining the pairing and use case for large records.

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 this tool when the record is too large for the prompt, thereby saving context. It mentions pairing with ask_pipeworx_grounded and technical caps, but 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?

The description discloses behaviors beyond annotations: requires Pipeworx OAuth account (not anonymous/BYO), SMS cap of 10/day, webhook auto-disable after 10 failures, and webhook signing secret returned once. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

The description is front-loaded with the core action, then prerequisites, then type details, then delivery channels. Every sentence provides necessary information without fluff. It is well-structured for an agent to parse.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is highly complete. It covers types, parameters, delivery options, prerequisites, rate limits, webhook signing, and auto-disable behavior. The absence of output schema is compensated by mentioning the return of subscription id and webhook secret.

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: explains the first three enum values with examples (sec_8k, polymarket_edge, fred_series) and provides detailed usage for delivery channels (email, sms, webhook) including constraints and webhook HMAC verification. However, two enum values (patent_grant, clinical_trial) are not described in the description, only in schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns a subscription id. This distinguishes it from sibling tools like list_subscriptions (listing) and unsubscribe (removal).

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

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

The description provides clear context on when to use (creating subscriptions) and includes prerequisites (requires Pipeworx OAuth account) and type-specific details. However, it does not explicitly mention when not to use or direct to alternatives, though the purpose is self-evident given sibling names.

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 destructiveHint=false. Description adds valuable context: output structure (category-bucketed example questions with tool+argument shapes), that it draws from a live catalog, and that it can be called with no arguments. 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?

Somewhat long but front-loaded with common user queries, then explains output and usage. Structured logically. Could be slightly tighter but no redundancy.

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

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

With no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shapes). Covers the main use case, parameter, and onboarding purpose. No major gaps.

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

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

Schema coverage is 100% with description for the topic parameter. Description further explains the topic parameter with examples ('finance', 'pharma') and the effect of omitting it ('full spread'). Adds meaning beyond schema.

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

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

The description uses a specific verb ('returns category-bucketed example questions') and identifies the resource ('Pipeworx capabilities'). It distinguishes from siblings like ask_pipeworx by focusing on onboarding and discovery of what to ask.

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 to use this tool FIRST when unsure of Pipeworx's capabilities or to learn how to call meta-tools. Provides context for the optional topic parameter but lacks explicit when-not-to-use instructions.

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

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

The description discloses that the row is deactivated, not deleted, and historical events remain available via recent_alerts. This adds value beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by clarifying the non-destructive nature.

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, then constraints and side effect. No wasted words; every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, constraints, and data lifecycle (deactivation, not deletion). It references a sibling tool (recent_alerts) for historical access, making it 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%, and the description adds that the id is a uuid returned by subscribe, which provides semantic context linking to the sibling tool. This is helpful beyond the schema's simple type 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?

The description clearly states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 context by stating ownership enforcement (can only cancel own subscriptions) and that the id comes from subscribe. However, it does not explicitly mention when not to use this tool versus alternatives like forgetting or deactivating through other means.

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 far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing internal behavior: structured SEC EDGAR + XBRL path for company-financial claims, grounded pipeline for others, exact percent-delta math, and the meaning of each verdict. Critically, it clarifies the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source), which is essential for correct interpretation. 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?

Although the description is long, every sentence adds value. It is front-loaded with example queries and a clear purpose, followed by routing details, return values, and caveats. The structure is logical and the length is justified given the tool's complexity (two pipelines, multiple verdicts, error semantics). No filler or 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?

The description is comprehensive for a complex claim-verification tool with no output schema. It covers input semantics, processing steps, return values (verdict types with meaning), citation format, and error handling. It also provides usage guidance for two distinct claim categories, making it complete for the agent to invoke and interpret results 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% with each parameter having a description. The tool description enhances this by providing concrete example claims, explaining that tolerance_pct overrides the implied tolerance, and giving a specific use case (1–2 for hallucination detection). This adds meaning beyond the schema's basic 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 states the tool performs natural-language claim verification against authoritative sources, with examples like 'fact check' and 'verify the claim that…'. It clearly distinguishes itself from generic query tools by focusing on fact-checking and even outlines two distinct verification paths (SEC EDGAR fast path vs. grounded pipeline), setting it apart from sibling 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates use cases for company-financial claims vs. other factual claims, explaining the routing logic. While it doesn't mention exclusions, it gives clear context and even notes it replaces multiple sequential calls, which helps the agent select this tool over alternatives.

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