Sgd

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 behavioral context: default model (free), costing model for Anthropic (users pay directly), and the return format. This complements the annotations well.

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 highly efficient 4-sentence paragraph. It is front-loaded with the core action, then progressively adds key details (default model, API key use, return format, use cases). No superfluous text.

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 adequately describes the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers the tool's purpose, parameters, and use cases, making it complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the supported models for the 'models' parameter ('workers-ai', 'anthropic') and clarifying that _apiKey is passed through to api.anthropic.com, with cost implications.

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 precise verbs ('Probe', 'score visibility') and specifies the resource ('one or more LLMs'). It clearly distinguishes the tool from siblings by focusing on cross-model visibility scoring, with specific use cases like AI-marketing audits.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter (only for Anthropic). However, it doesn't mention when NOT to use this tool or suggest alternative tools, which would have earned a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context: it fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call'. It doesn't cover failure modes or latency, but the annotation coverage makes that acceptable.

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 segment earns its place: preference instruction, domain list, trigger phrasing, examples, routing rules, and tier availability. The most important guidance ('PREFER OVER WEB SEARCH') is front-loaded, and the escalation paths are clearly separated.

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

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

Despite having no output schema, the description states what the agent will receive ('structured answer with stable pipeworx:// citation URIs'), covers the full breadth of supported domains, and explains when to use sibling tools. An agent has enough information to decide when and how to invoke this tool correctly.

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

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

Schema description coverage is 100%, and every parameter is an alias for 'question' with a description. The description provides natural-language examples but adds no meaning beyond what the schema already conveys, so the baseline of 3 is correct.

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

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

The description names a clear verb ('routes') and a concrete resource: a question-answering tool over 5,724 tools across 1,497 verified sources. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as the tools to use when stronger evidence or broader fan-out is needed.

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

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

Usage guidance is explicit and actionable: 'PREFER OVER WEB SEARCH', specific trigger phrases ('what is', 'look up', 'find', 'get the latest'), and concrete examples. It also tells the agent when to step up to alternatives, covering both hallucination-resistant grounded answers and multi-part deep research.

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

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

Description discloses that routing improvements are enabled live when under test, that no candidate is currently active, and that it is a full working router—not a stub or fallback. This adds meaningful context beyond annotations (readOnly, openWorld, idempotent, non-destructive) and clarifies the experimental yet functional nature of the tool. No annotation 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 somewhat wordy but information-dense: it explains what the tool is, its experimental behavior, current status, usage, and that it is fully functional. The sentences are logically ordered and front-loaded, though the date and fallback explanation could be trimmed without losing essential meaning.

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

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

For a complex universal router with no output schema, the description is quite complete: it specifies the tool's relationship to ask_pipeworx, current experimental state, and that the response shape matches the stable version. It does not detail the output structure, but referencing ask_pipeworx's response shape partially compensates for the missing output schema.

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

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

Schema description coverage is 100% and all six parameters (question plus five aliases) are already documented clearly. The description adds no new parameter semantics beyond saying 'same arguments,' so the baseline of 3 is appropriate; the schema carries the parameter burden.

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

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

Description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,724 tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx by emphasizing its experimental edge and live-testing role, though it relies on understanding 'router' and 'ask_pipeworx' jargon.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It names the primary alternative (ask_pipeworx) and the condition for choosing this beta. It does not mention other siblings or when not to use it, but the guidance is directly actionable.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behavioral constraints: the answer is extracted ONLY from the tool's returned data, refusals are explicit, and the exact refusal_reason enum is provided. This gives the agent a precise behavioral contract 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 dense but every sentence earns its place: it defines the mode, explains routing, specifies the output contract, gives use cases, and names the tradeoff with the sibling. The most decision-relevant phrase, 'hallucination-resistant answer mode for high-stakes reads', is front-loaded. No fluff 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?

Despite having no output schema, the description provides a complete return contract including success shape, refusal shape, and the enum of refusal reasons. Combined with the annotation hints, an agent has everything needed to invoke the tool correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already defines all six parameters as aliases for the same natural-language question. The description adds no new parameter-level semantics, but it doesn't need to. Baseline 3 is appropriate when the schema carries full coverage.

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

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

The description identifies a specific mode ('hallucination-resistant answer mode for high-stakes reads') and clearly separates it from the sibling ask_pipeworx by describing its guaranteed extraction behavior and refusal protocol. An agent can determine exactly what this tool does and how it differs from the non-grounded version.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on'), gives concrete domains (financial verdicts, legal claims, medical lookups, public statements), and names the alternative for casual use ('prefer ask_pipeworx for casual lookups'). It even quantifies the tradeoff with an extra LLM call, which is actionable routing 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds extensive behavioral details: fan-out logic, response shapes, edge cases (low confidence, closed markets, wide spreads), resolution-rule risk, and safety short-circuiting. No contradictions.

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

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

Description is very long (multiple paragraphs) with exhaustive detail. While front-loaded with purpose, subsequent sections could be more structured (e.g., bullet points). Every sentence adds value, but overall verbosity reduces conciseness.

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

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

No output schema exists, so description must compensate fully. It does: explains response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields with fallback logic, and safety checks. Covers all relevant behavioral aspects and edge cases.

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

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

Input schema has 100% coverage with descriptions for each parameter. The description adds meaningful context: explains what `market` accepts (slug, URL, question text), `depth` enum options with defaults, and `include_raw` purpose and size implications. Schema does the heavy lifting, but description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists inputs, steps, and outputs, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a specific bet research use case.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides usage examples. Lacks explicit when-not-to-use or alternative tool suggestions, which would push it to 5.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive nature. Description adds valuable behavioral context: parallel execution, handling of off-calendar fiscal years, sorting by primary metric, and provision 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 front-loaded with natural language triggers, then explains behavior, entity-specific outputs, and performance benefits. 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?

Given the tool's complexity (parallel lookup, multiple data sources, dynamic sorting), the description covers all essential aspects. It mentions output format (paired data + URIs) despite no output schema.

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

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

Schema has 100% coverage with descriptions. Description adds further meaning by detailing what data is pulled for each type (company: revenue, net income, cash, debt; drug: FAERS counts, FDA approvals, trials) and constraints like maxItems 5.

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: side-by-side comparison of 2-5 companies or drugs. It provides example natural language triggers and explicitly distinguishes itself from siblings by replacing 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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use based on entity type and provides specific data sources for each.

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, but the description goes far beyond: it discloses account/auth requirements, depth-specific behavior (gap recovery, contradiction scans, hop counts), the 'never invented' gaps[] guarantee, semantic excerpting, citation fetchability, and expected latency (15-90s). This extensive behavioral context is a model example of transparency that complements annotations without contradiction.

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

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

The description is long (several hundred words) but every sentence earns its place — it covers account requirements, usage context, alternatives, depth behavior, output format, and timing. It's front-loaded with the most critical info (account sign-in) and uses clear structural breaks (semicolons, capitalization, parentheticals). While not a model of brevity, the complexity of the tool justifies the length, and there's no redundant 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?

Given no output schema, the description fully explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It also covers failure modes (empty gaps for non-catalog topics), performance expectations, and the second-hop iteration behavior. An agent has everything needed to decide when to invoke this tool and what to expect.

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

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

Schema coverage is 100% with good per-parameter descriptions, but the tool description adds substantial meaning beyond the schema: it explains how 'question' decomposition works, what the depth enum actually controls (facets count, hop logic, contradiction scans, paid tier), and the exact trade-offs between quick/standard/thorough. This is valuable supplementary semantics that the schema alone wouldn't convey.

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 1497 structured data sources), explicitly contrasts with open-web search, and names the sibling tool it is not (ask_pipeworx). It clearly differentiates its scope for broad/multi-part questions, making it impossible to confuse with alternatives like ask_pipeworx 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?

Provides explicit when-to-use (broad/multi-part structured data questions), when-not-to-use (breaking news, single lookups), and names the alternative (ask_pipeworx) with the condition for each. Also specifies the account requirement and which depth levels require payment, leaving no ambiguity for the agent.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds context that results are 'ready to call directly, no second schema lookup needed,' providing extra behavioral info beyond annotations. No contradictions.

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

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

Description is front-loaded with the main purpose, uses bullet-like listing for domains, and every sentence adds value. No fluff.

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

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

For a discovery tool with high-quality annotations and schema, the description covers purpose, return value, and usage context completely. No output schema needed as return is described adequately.

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

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

Schema coverage is 100%, so baseline is 3. Description gives example queries but does not significantly add meaning beyond the schema's aliases and 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 finds tools by describing data or task, lists specific domains, and explains what it returns (top-N tools with names, descriptions, schemas). It distinguishes from siblings by advising to call this first for browsing.

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

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

Explicitly states use case: 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' Could be improved by stating when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description goes beyond by detailing internal fan-out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specific return fields (cik, filings, fundamentals, patents, news, LEI), and known limitations (USPTO PatentsView API sunset May 2025 with soft-fall behavior). 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 front-loaded with example queries and key instruction ('ALWAYS PREFER...'). It is detailed but each sentence provides essential information. Minor wordiness can be excused given the complexity of the tool; still very effective and well-structured.

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

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

No output schema exists, so description fully compensates by enumerating return components (cik, company_name, recent_filings with URIs, fundamentals with specific fields and sorting, patents, news, LEI). It also covers edge cases (patents sunset, soft-fall, name not supported). The description leaves no ambiguity about what the tool returns and its limitations.

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

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

Schema coverage is 100% and description adds significant meaning beyond schema: explains 'type' is limited to 'company' for now, and 'value' accepts ticker or zero-padded CIK, not names, with explicit example ('AAPL' or '0000320193'). It also cross-references resolve_entity for name lookup, which aids correct parameter selection.

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

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

Description starts with concrete example queries and clearly states 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from sibling tool 'resolve_entity' by noting that names must be resolved first. It also explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', providing clear purpose and differentiation.

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

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

Description provides explicit when-to-use guidance: 'when the user asks for a holistic view'. It also gives when-not-to-use: 'names not supported (use resolve_entity first if you only have a name)'. Additionally, it warns about patents sunset and soft-fall behavior, and specifies the need for ticker or CIK input.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds 'clear sensitive data' as motivation but doesn't disclose additional behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with the action. No wasted words; every sentence serves a purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage context, and relationships. 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?

With 100% schema description coverage, the schema already documents the 'key' parameter as 'Memory key to delete'. The description does not add meaning beyond that, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by focusing on deletion.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with siblings 'remember and recall', giving clear context and alternatives.

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

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

Discloses the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. Aligns with annotations (readOnlyHint, idempotentHint) and adds details beyond them, such as the output being a single text blob ready to deploy.

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?

Efficiently structured in three sentences: purpose and format, process, use cases. No unnecessary words, and critical information is front-loaded.

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

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

Given two parameters with full schema and no output schema, the description adequately covers the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and usage context. No gaps for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the schema descriptions for 'url' and 'max_links' (including default and max values) but does not add new semantic information 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 tool generates a production-ready llms.txt file for any URL, specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes from siblings by listing specific use cases such as indexing, drafting, and auditing.

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

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

Explicitly lists three distinct use cases: getting a client's site indexed, drafting for own project, and auditing competitor sites. This provides clear context on when to use this tool and implicitly guides away from using it for unrelated tasks handled by 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds valuable context: it lists the returned fields (standard name, systematic name, SGDID, description, locus type, aliases), and states 'Keyless' indicating no authentication required. 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: two sentences that front-load the purpose and then provide essential details (acceptable identifiers, returned fields, keyless). No wasted words.

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

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

Given no output schema, the description fully explains the return values. It also covers input variants and keyless access. For a simple lookup tool, the description is complete and leaves 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 description coverage is 100%, with the schema already listing acceptable identifier types. The description reiterates this but adds the context that it is for yeast genes. This adds minimal new semantic value beyond the schema.

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

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

The description clearly states it looks up a single yeast gene/locus, specifying the organism (S. cerevisiae) and the source (SGD). It distinguishes itself from sibling tools like search_genes (for multiple genes) and get_gene_go (for GO annotations) by being a single-gene lookup.

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

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

The description implicitly indicates usage for single gene lookups vs search_genes for multiple. The note 'Keyless' informs that no API key is needed. However, it lacks explicit when-not-to-use instructions or direct sibling comparisons.

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, non-destructive behavior. The description adds that it returns GO terms with aspect and evidence, which is useful context beyond annotations.

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

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

The description is two sentences covering purpose, input, and output without 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?

Given no output schema, the description explains the return format (GO id, aspect, evidence). The parameter is well-documented. Adequate for a straightforward retrieval 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%, and the description adds examples of acceptable ID formats (systematic name, gene name, SGDID), enhancing the schema description which already lists them.

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 retrieves Gene Ontology annotations for yeast genes from SGD, specifying the species, database, and return type. This distinguishes it from siblings like 'get_gene' (general info) and 'search_genes'.

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 'Keyless' and accepts multiple ID formats, providing clear input guidelines. It does not explicitly contrast with alternatives but implies usage for GO annotations specifically.

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, destructiveHint, idempotentHint, openWorldHint. Description adds that it lists active subscriptions by default and returned fields, but doesn't add significant behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action and output, 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?

No output schema, but description explains return fields. Usage context provided. Simple tool, fully covered.

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

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

Schema covers 100% of the single parameter (include_inactive) with a clear description. Description does not add extra meaning beyond listing it.

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 'List the caller's active subscriptions' and lists returned fields (id, type, params, etc.). Distinguishes from siblings 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?

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.'

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

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

Annotations are all false, providing no safety or side-effect insight, so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), the claim_token flow for anonymous filing, that it's free and doesn't count against quota, and that the team reads digests daily — all meaningful behavioral context beyond structured fields.

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

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

Although longer than typical descriptions, every sentence adds necessary guidance: when to use, scope exclusions, message crafting, token mechanics, and rate limits. The structure flows logically from purpose to usage to follow-up, and the 'Not sure?' line proactively addresses ambiguity.

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

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

The tool has no output schema and all parameters optional, so the description must explain the full contract. It covers return behavior (claim_token), how to check resolution status, rate limiting, and scope boundaries, making it fully usable without guessing. This is unusually complete given the tool's nuance.

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, but the description adds value by explaining how to frame the message ('don't paste the end-user's prompt') and by demonstrating the claim_token usage ('pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's terse parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly delineates this from sibling tools by framing it as feedback rather than a query or research tool, and further clarifies scope by restricting to tools served by this Pipeworx connection.

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: for bugs, feature/data gaps, or praise, with concrete examples like 'wrong/stale data (bug)'. It also gives a clear exclusion rule: don't report issues from other MCP servers, and helps disambiguate by telling the agent to check Pipeworx tool names in the connection list.

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

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

The description goes beyond basic annotations to disclose caching (5min-1h), data source (CF analytics-engine), privacy (no PII), and time-window semantics (hot vs steady-state). This provides rich behavioral transparency.

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

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

The description is moderately concise with a clear structure: core function, use cases, additional details. It is front-loaded with the main action. However, the bullet-point use cases could be slightly more compact.

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 covers purpose, use cases, data source, caching, and privacy. It mentions the three return components (top tools, top packs, total call volume) but does not specify the exact JSON structure. Given the tool's simplicity and lack of output schema, this is acceptable but not fully complete.

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

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

Schema description coverage is 100% with clear enum descriptions. The tool description reiterates the window options but does not add new parameter-level semantics beyond what the schema already provides. Thus, the description adds minimal value for parameter understanding.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) over configurable windows. It lists three specific use cases that distinguish it from query tools like ask_pipeworx or discovery tools like discover_tools.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical tools, checking alignment). While it doesn't explicitly mention alternatives or when not to use, the context is clear and the use cases are 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 confirm read-only, idempotent, non-destructive. Description adds behavioral details: Jaccard similarity threshold ≥0.30, partition filter dropping placeholder slugs, fill check against live CLOB depth with explicit trade advice.

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

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

The description is long but well-structured: overview, mode explanations, additional features, response format, fill check. Every sentence adds value, though some details (e.g., Jaccard threshold) could be slightly condensed.

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 multiple modes and internal logic, the description covers all key aspects: mode behavior, semantic filtering, partition checks, fill check, and response structure. It references a sibling tool for custom sizing.

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?

Both parameters are described in the schema; the description adds extensive context: what event and topic do, accepted formats (URLs), and internal logic (walks child markets, searches related events).

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It explains three modes (no args, event, topic) and distinguishes from sibling tools focused on edges or fill risk.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains trade-offs and even when not to trade (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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial detail: three response segments, caching (1h), Fed bets excluded from ranking, diagnostics for empty segments, and edge metrics (edge_pp_net, kelly_fraction, etc.). 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 and detailed, front-loading purpose but then diving into extensive detail on segments and knobs. Could be more concise, but the structure is logical with clear sections and plain language.

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 9 parameters, no output schema, and complex behavior (three segments, diagnostics, caching, Fed notes), the description is remarkably complete. It explains all behaviors, filters, and edge cases, leaving little ambiguity for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explaining how parameters interact (e.g., min_kelly vs. min_partition_leg_kelly) and provides usage context for tradeable-edge knobs. Adds meaningful extra information.

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

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

The description opens with a clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by explicitly naming Pipeworx and its unique data disagreement approach.

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

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

The description states it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It also explains knobs for filtering. Lacks explicit when-not-to-use guidance but provides clear context.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich detail: the structure of tracked[], expired[], snapshot_dates[], and limitations like snapshot TTL and decay from daily closes. 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 with a clear intro, response sections, and limitations. It is somewhat long but every sentence contributes value. Front-loaded with the key question.

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 (time-series, decay, expiration) and no output schema, the description thoroughly explains the response fields, including edge cases like gaps and median lifespan. It covers 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 coverage is 100% with descriptions for both parameters. The description adds default values and clamp range (already in schema), but does not significantly enhance parameter understanding 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 starts with 'Edge persistence and decay telemetry' and explicitly states the tool answers 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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 (to assess edge freshness), but does not explicitly state when not to use it or offer alternatives. It contrasts fresh vs aging edges, providing good context.

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

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

Annotations already declare read-only and idempotent, but the description adds valuable behavioral details: walking the ladder, returning verdicts like clean/degraded/cannot_fill, and identifying forced directional risk. No contradictions with annotations.

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

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

The description is well-organized with clear mode sections and emphasis, but it is somewhat verbose. Every sentence adds value, but could be tightened slightly without losing clarity.

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

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

No output schema, but the description enumerates all key return fields for both modes, covering top_of_book, VWAP, slippage, and risk metrics. Lacks explicit error handling details, but overall complete for a complex 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%, but the description adds significant meaning: explains the dual meaning of size_usd (spend vs target proceeds in single-market, settlement notional in basket), clarifies default side logic for baskets, and specifies clamp ranges beyond the schema's brief comments.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check using live order-book depth, distinguishing between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage by focusing on capturability of theoretical edges.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500, and explains the risks of partial fills and uncapturable overround. Provides clear when-to-use guidance and rationale.

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 readOnlyHint/openWorldHint annotations by disclosing compatibility codes, the meaning of temporal_alignment nulls, unclassified legs never being paired, skipped_cross_type and skipped_cross_subtype counters, and the fact that spreads are gross because Kalshi fees are not modeled. These are genuinely useful behavioral details that help an agent interpret output safely.

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

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

The description is long but appropriately dense for a complex tool with safety disclosures. It is front-loaded with the core purpose, then organized into modes, response fields, compatibility codes, and caveats, so an agent can scan it. Slight redundancy in repeated 'both modes' and 'either mode' reminders keeps it from being a 5.

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?

Even though there is no output schema, the description enumerates the response surface thoroughly: per-venue leg prices, top_spreads_pp, compatibility_warning and compatibility_codes, temporal_alignment semantics, fees_note, skipped counters, and low_confidence_pairs. For a tool with this many edge cases, the description gives enough context to call it correctly and interpret results.

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

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

The input schema already documents all three parameters at 100% coverage, so the baseline is 3, but the description adds real semantic value by explaining that topic is a pre-mapped shortcut list, that explicit ticker/slug override the mapped side, and that both modes run the identical token-overlap matcher. This clarifies how parameters interact beyond their individual 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 identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific and meaningful purpose. It does not explicitly distinguish itself from nearby siblings like polymarket_arbitrage, but the resource and behavior are specific enough that an agent can understand what it does.

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

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

The description provides concrete usage context via TWO MODES: topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug, and it warns that most pre-mapped topics currently return compatibility warnings so pre-mapped does not mean tradeable. It does not explicitly contrast this tool with sibling tools such as polymarket_arbitrage or polymarket_edges, so the when-vs-alternatives guidance is not fully explicit.

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, and destructiveHint=false. The description confirms these by stating it retrieves saved values and lists keys. It adds behavioral context about scoping to an identifier (anonymous IP, BYO key hash, or account ID), which is not in 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 sentences convey functionality, usage examples, and scoping without waste. The first sentence front-loads the core action. Every sentence adds unique 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 one-parameter read-only tool with full annotation coverage, the description covers what, when, how (parameter behavior), and context (scoping, partnering tools). No information is missing for effective use.

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

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

The input schema has 100% coverage with a description for the single parameter 'key'. The description explains omitting key lists all keys and relates key to previously saved values. This adds meaningful context beyond the schema's basic 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 explicitly states the tool retrieves a value saved via remember or lists all keys when omitted. It uses specific verbs ('retrieve', 'list') and resources ('value', 'keys'). It distinguishes from sibling tools like remember (save) and forget (delete) by mentioning them as partners.

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 concrete examples of when to use the tool (look up target ticker, address, research notes) and implies not to use it for re-deriving context. It guides pairing with remember and forget. However, it lacks explicit 'do not use when' statements.

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

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

Annotations declare readOnlyHint=true, implying no data modification. The description, however, explicitly states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones', which is a mutation of the feed state. This is a direct contradiction between description and annotations, severely undermining transparency.

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

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

The description is remarkably concise: three sentences that cover purpose, return format, filtering, and polling behavior. Every sentence adds value with no redundancy. The paragraph is front-loaded with the core action and then efficiently expands on specifics.

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 and the absence of an output schema, the description adequately covers return fields (source, citation_uri, payload), all parameters (type, since, mark_read, unread_only, limit), and behavioral notes (polling, alternative endpoint). No critical information is missing for an agent to use this 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%, but the description adds meaning beyond the schema: it explains the effect of mark_read (flags read to exclude from next call) and clarifies that unread_only returns events with null read_at. These details help the agent understand parameter behavior beyond the schema's terse 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 starts with a clear verb ('Pull') and resource ('fired events from your subscription feed'), specifying return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like 'list_subscriptions' and 'subscribe' by focusing on alert retrieval, and even mentions an alternative REST endpoint for scripts/dashboards, clarifying its role within MCP.

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

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

The description states 'Polls work fine', indicating suitability for polling scenarios, and notes the same feed is available at a REST endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, offering an alternative. However, it does not explicitly exclude usage in other contexts or compare with siblings for when not to use.

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

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

Beyond annotations (readOnly, idempotent), describes concrete behavior: parallel calls to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail caveat. Also mentions return structure.

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

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

Well-structured with examples upfront, but slightly verbose. Every sentence adds value, though could be tightened slightly.

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?

Fully self-contained: covers sources, fallback, parameter formats, return structure (changes grouped, total_changes, citation URIs), and caveats (USPTO sunset). No output schema, so description compensates completely.

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?

Adds significant value over schema: provides examples for since (ISO/relative), explains value can be ticker or CIK, and clarifies type is limited to 'company'. Schema coverage is 100% but description enriches understanding.

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

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

Clear verb+resource: 'change feed for a company' with example queries. Explicitly distinguishes from sibling entity_profile, which provides static profile.

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

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

Provides explicit guidance: when to use (dynamic changes) vs when to use entity_profile (static profile). Also gives usage tips for the since parameter (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

Annotations already indicate write behavior (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds valuable context: memory is scoped by identifier, authenticated users get persistent storage, anonymous sessions retain for 24 hours, and the tool is meant to be paired with recall/forget. 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 three sentences, each adding essential information. It is front-loaded with the primary purpose, immediately followed by usage guidance and behavioral details. 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?

Given the simplicity of the tool (2 required params, no output schema), the description fully covers purpose, instructions, behavioral aspects (persistence, scoping), and integration with sibling tools. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds practical context for parameter usage: suggests naming conventions (e.g., 'subject_property') and clarifies that values can be any text. This goes 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 clearly states the tool saves data for reuse, specifying the verb 'save' and resource 'key-value pair'. It distinguishes from siblings 'recall' and 'forget' by name, and provides concrete examples of use cases (resolved ticker, target address, etc.), making the purpose unmistakable.

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

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

The description explicitly states when to use: 'when you discover something worth carrying forward' and gives example scenarios. It pairs the tool with recall and forget, implying the intended workflow. It does not explicitly list when not to use, but the context is clear enough for an agent to decide.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral detail: graceful degradation of LEI/FIGI enrichment, ambiguity handling via figi_candidates, explicit unresolved fields, source labeling for identifiers, and the ISIN-to-LEI mapping behavior. This greatly helps an agent anticipate edge cases.

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

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

The description is long but extremely dense and front-loaded with example usage. Every sentence provides operational value—mapping input types to outputs, explaining ambiguity behavior, describing graceful degradation, and giving concrete examples. The structure is appropriate 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?

The description is comprehensive for a tool with only two parameters and no output schema. It covers when to use it, what inputs are accepted, what each supported type returns, how ambiguous cases are handled, how failures are reported, and how the tool behaves under external service outages. An agent has enough context to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema: it clarifies that the value must be the entity name only, warns against including trailing security-class words, explains the difference between company and drug values, and details what each type resolves to. This meaningfully compensates for anything the schema leaves implicit.

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

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

The description clearly states the tool's function: resolving a user-spoken name to canonical/official identifiers needed by other tools. It gives concrete example queries ('What's the ticker for…'), names the resource (entity names to identifiers), and distinguishes itself from potential peers by emphasizing it is the first step when an ID is needed.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains supported entity types and the acceptable input forms (ticker, CIK, ISIN, company name, brand/generic drug name). It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds 'Probes each entity with ai_visibility_check' and describes return structure (ranked list with score, confidence, signal density). No contradictions.

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

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

Two sentences plus a usage example and return description. Every sentence is informative and no redundancy. Front-loaded with main purpose.

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

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

No output schema, but description explains return format (ranked list with score, confidence, signal density). Parameter descriptions are clear. Minor gap: no mention of error handling or timeouts, but acceptable for this complexity.

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

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

Schema coverage is 100% with descriptions. Description adds value: first entity treated as 'subject', rest as competitors; context disambiguates common names; models: omit for default workers-ai. This is beyond schema.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side' with specific verb 'probes, ranks, surfaces'. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different comparison).

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

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

Provides explicit use case: 'competitive AI-marketing audits' with example 'does Claude know about us as well as our competitors?'. No explicit when-not-to-use or alternatives, but context from sibling tools implies appropriate scope.

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 valuable behavioral context: 'Partial failures degrade gracefully', specific timeout (5-30s for bundlephobia), and that sources_failed will list timeouts. 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 reasonably concise given the tool's complexity. It front-loads the main purpose and organizes information logically (what it does, when to use, limitations, behavior). Could be slightly more compact but still effective.

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

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

Given the complexity of the tool, no output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, inputs, behavior on failure, ecosystem scope, and output structure. It leaves no major gaps for an agent to understand how to use this tool effectively.

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 good descriptions for both parameters. The description adds clarity that scoped packages are accepted and reiterates the default version behavior, but does not add entirely new semantic information 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 it's a composite check for npm packages, fanning out across deps.dev and bundlephobia. It uses specific verbs ('Scan Dependency') and resources ('npm package', 'deps.dev', 'bundlephobia'), and is distinct from all sibling tools which cover other domains like research, betting, or tool discovery.

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 it ('is X safe / popular / small' or 'what does adding lodash cost me') and provides a clear alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minor context about return fields (name, category, href) and the database authority, but doesn't disclose additional behavioral traits like pagination or rate limits, which would add 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?

The description is two sentences, front-loaded with the core functionality. Every sentence adds value without redundancy or fluff. Extremely 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 search tool with no output schema, the description covers the database, searchable entities, and return fields. Minor gaps: no mention of pagination, default limit, or ordering, but overall sufficient for basic usage.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the free-text nature and 'Keyless' hint, but adds no new semantic details beyond the schema. 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 states the tool searches SGD for genes and other entities via free-text query, specifying the authoritative resource and entity types. It distinguishes itself from sibling tools like get_gene by being keyless (free-text) versus key-based retrieval.

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

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

The description implies usage for free-text searches via 'Keyless' but does not explicitly state when to use this tool versus alternatives like get_gene or give when-not scenarios. The guidance is vague, leaving the agent to infer context.

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

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

Discloses key behaviors beyond annotations: uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag, returns offsets and similarity scores. Annotations only provide readOnly, idempotent, openWorld hints; description adds rich operational detail.

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 a single paragraph but well-structured: purpose sentence, use case, technical details. Could be slightly tighter but no waste; front-loaded with key action.

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

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

Given complexity of semantic search, large text handling, and no output schema, description is thorough: explains truncation, embedding model, window size, offset purpose, and pairing with sibling tool. Covers all aspects an agent needs 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% and description adds value: for text states max ~200K chars, for query gives natural-language examples, for limit states range 1-20 with default 5. This clarifies usage beyond 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document usage.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use or alternatives for records that fit, but provides clear context.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context: returns a new subscription id, requires OAuth account, details on delivery channel behavior (webhook signing, auto-disable after 10 failures, SMS cap). 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 lengthy but well-structured, front-loaded with the main purpose and then expanding into details. While every sentence adds value, it could be more concise by grouping or using bullet points, but the density of information is high.

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

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

Given 3 parameters with nested objects, multiple types, no output schema, and 100% schema coverage, the description compensates fully. It covers examples, constraints, prerequisites, return value, and delivery behavior. The tool is complex, and the description leaves no gaps.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema. For 'type', it explains each enum value with real examples. For 'params', it provides per-type JSON structures. For 'delivery', it adds behavioral details (e.g., webhook signing, SMS verification requirement, cap).

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 creates a proactive monitoring subscription to a live-data event stream, using the verb 'Create' and specifying the resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides explicit guidance on when to use the tool (proactive monitoring), supported types with detailed examples, delivery channels, prerequisites (OAuth account, phone verification for SMS), and constraints (SMS cap, webhook auto-disable). No alternatives explicitly named, 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and that passing a topic focuses the results. 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 with trigger phrases upfront, followed by a clear explanation of output and usage. While slightly long, every sentence adds value, and it is front-loaded with key purpose and usage.

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 what the tool returns (category-bucketed example questions with tool+argument shapes) and how to use it. It also mentions the live catalog and meta-tools, making it complete for an onboarding tool.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning beyond the schema by listing example values for topic (finance, pharma, etc.) and stating that omitting topic gives a cross-category spread, which aids understanding of parameter behavior.

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

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

The description clearly states the tool is an onboarding entry point for new agents to learn what questions to ask, explicitly listing trigger phrases and positioning it as the first tool to use. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it returns example questions with tool+argument shapes.

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 guidance: use this tool first when unsure about Pipeworx capabilities, call with no arguments for full spread or pass a topic to focus. It implicitly tells when to use it (first) and what it's for, though it doesn't explicitly state when not to use 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 annotations: ownership enforcement and deactivation (not deletion). Annotations already indicate destructiveHint=false, but the description elaborates meaningfully. No contradiction with annotations.

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

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

Two sentences with no wasted words. The action is front-loaded and each sentence adds necessary context. 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?

No output schema exists, but the description explains the effect of the tool (deactivation) and the persistence of historical events. It does not mention return value or error cases, but for a simple cancellation tool this is adequate.

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 parameter 'id' is described in the schema. The description does not add additional meaning beyond what the schema already provides, meeting 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 action ('Cancel a subscription by id') with the specific resource (subscription) and the required identifier. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement and explains the deactivation behavior, giving clear context for when to use. It does not explicitly state when not to use or mention alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description goes far beyond this by explaining the two distinct execution paths, the exact meaning of each verdict (especially the critical distinction between 'could_not_verify' and 'unsupported'), and the presence of verification_error. It warns callers not to treat 'could_not_verify' as evidence, which is crucial behavioral context not inferable from annotations.

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

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

The description is long but well-structured: it front-loads the purpose with trigger phrases, then covers routing, return format, and critical caveats. Every sentence contributes useful information, though some redundancy exists (e.g., listing six paraphrases of 'verify'). The length is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly explains return values (verdict list, actual value, citation, reasoning), error semantics, and the 'unsupported' case. It even explains that the tool replaces multiple sequential calls, giving the agent a full mental model of its behavior. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so both parameters are already well-documented. The description adds valuable context for tolerance_pct (override behavior, default, and use case for hallucination detection) and gives concrete claim examples. This exceeds the baseline for high coverage, but does not fully compensate for missing output 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 identifies the tool as natural-language claim verification with specific trigger phrases ('Is it true that…', 'fact check'). It distinguishes between two processing paths (SEC EDGAR fast path for company-financial claims vs. grounded pipeline for everything else), which differentiates it from siblings like ask_pipeworx_grounded or compare_entities. The verb 'verify' plus resource 'claim' is specific and unambiguous.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear trigger examples. It explains the structured vs. grounded routing logic, but does not explicitly name alternative tools or say when NOT to use it. Still, the guidance is strong enough to steer an agent correctly.

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