Tldr Pages

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate those. The description adds value by disclosing the default model, the requirement for a BYO Anthropic key, and the cost implication ('you pay Anthropic directly'). It also clarifies that the tool returns per-model data and a combined view. No contradictions with annotations.

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

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

The description is a single paragraph with no unnecessary words. It front-loads the core action ('Probe one or more LLMs for what they know...') then adds details about default model, key usage, return format, and use cases. Every sentence earns its place.

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

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

Given that there is no output schema, the description adequately describes what is returned: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' Combined with the full schema coverage and safety annotations, the description provides sufficient context for an AI agent to use this read-only 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% (all 4 parameters have descriptions in the input schema). The description adds minor context like 'Default model is Workers AI Llama-3.3-70b (free)' and 'Useful for...' but does not significantly enhance parameter understanding beyond the schema. Following the baseline rule, a score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe), resource (LLMs), and output (visibility score). It also distinguishes from siblings by mentioning specific use cases like AI-marketing audits and pre-launch brand checks, which are not explicitly covered by sibling names like scan_competitor_ai_presence or compare_entities.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass the _apiKey for Anthropic probing and notes the default model. However, it does not explicitly state when not to use this tool or compare it to specific sibling alternatives like scan_competitor_ai_presence, so it lacks explicit exclusions.

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 behavior. The description adds meaningful behavioral context: it routes to many tools, fills arguments, and returns stable pipeworx:// citation URIs. The phrase about 'hallucination... algorithms' is ambiguous but not contradictory to the annotations.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and includes useful domain lists, triggers, and examples. It is somewhat long and contains minor redundancy in the 'START HERE' sentence, but most content earns its place.

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

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

For a high-complexity router with no output schema, the description covers what the tool does, when to use it, what to pass, and what kind of answer to expect. It would be more complete with explicit guidance on sibling alternatives and edge cases, but it is adequate for correct selection and 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 all parameters documented as aliases for 'question'. The description adds value by clarifying that the agent only needs to supply a natural-language question and that the tool will fill the underlying arguments itself. The examples also help the agent understand acceptable query formulations.

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

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

The description clearly identifies the tool as a question router that 'routes the question to the right one of 5,710 tools across 1494 verified sources' and returns structured answers with citations. It distinguishes itself from web search but does not differentiate among sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It provides strong triggers and examples, but does not state when to prefer sibling alternatives such as ask_pipeworx_grounded or 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: live candidate status, the fact that no candidate is currently active, the current exact match to ask_pipeworx, and the experimental edge. It does not go into rate limits or exact routing failure behavior, but the core operational traits are well disclosed.

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

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

The description is four sentences and quite dense, front-loading the beta relationship and current status. The 2026-07-26 date is specific and useful for current behavior, though it may age poorly. Overall, every sentence contributes to selection or safe invocation.

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

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

For a beta router variant with no output schema, the description tells the agent enough: same arguments, same response shape, current equivalence to ask_pipeworx, and when to prefer this variant. It could be more explicit about the response format, but referencing the stable sibling's response shape covers most of the gap.

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

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

Schema description coverage is 100%, so the input schema already documents each parameter. The description points to 'same arguments' as ask_pipeworx but does not add deeper parameter-level semantics; the baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, a universal router with the same 5,710 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by explicitly stating it carries candidate routing improvements.

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

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

It explicitly instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router to inform merges. The 'Falls back to nothing' clarification prevents the agent from treating it as a thin wrapper or a stub.

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

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

Goes well beyond the annotations by disclosing that answers are extracted only from tool results, that refusals are explicit with specific refusal_reason values, and that this mode costs one extra LLM call. The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are consistent with this behavior, with no contradiction.

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

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

The description is dense and information-rich, front-loading the core purpose and then covering return shape, refusal cases, usage guidance, and cost trade-off. It is longer than strictly necessary, with details like the exact tool/source counts, but every sentence contributes to correct invocation and selection.

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

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

Given there is no output schema, the description fully documents both success and refusal return shapes, including the refusal_reason enum. It also covers routing behavior, use cases, and the cost comparison with ask_pipeworx, giving an agent everything needed to invoke 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?

Schema description coverage is 100%, so the input schema already documents the parameters. The description adds only generic context about routing and argument filling, not parameter-specific meaning; the baseline of 3 is appropriate.

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

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

The description states a specific purpose: a hallucination-resistant answer mode for high-stakes reads, with explicit behavior ('EXTRACTS the answer using ONLY what the tool result contains'). It also distinguishes itself from ask_pipeworx by naming the sibling and the cost/refusal trade-off, so an agent can tell them apart.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples. It also states when not to use it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: fan-out logic, resolver contract, parent extractor, news fields, safety mechanisms, and resolution-rule risk, far exceeding annotation info. No contradiction.

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

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

The description is long but every sentence adds value. It is well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with core purpose. Slight conciseness improvement could be made, but appropriate for 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?

Tool has 3 params, no output schema, but high schema coverage. Description is extremely thorough, covering resolution behavior, edge cases, safety, and response fields. Leaves little to guess, 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 coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema: explains 'market' can be slug, URL, or question text with examples; details 'depth' and 'include_raw' effects. This adds value beyond 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 clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison), distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

Explicit usage examples are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also mentions when not to use (e.g., low-confidence matches, closed markets), offering clear guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive. Description adds the data source (GitHub tldr-pages index), output shape (names + count), and its role as a pre-page lookup. No contradictions.

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

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

Three sentences, front-loaded with the core action and filters. The second sentence states output, the third gives workflow context. No filler, though slightly dense.

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 an output schema exists, the description needn't detail return types. It covers what the tool does, source, filters, and output count, making it self-contained.

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 no descriptions or enums, but the description compensates by listing valid platform values (common, linux, osx, windows, android, sunos, freebsd) and specifying language as ISO 639-1. This gives agents the needed parameter constraints.

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

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

Clearly states it lists command-line utilities from the tldr-pages index, filtered by platform and language, returning names and a count. The phrase 'before fetching a page' distinguishes it from the sibling 'page' tool.

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

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

Provides clear context for when to use it: to see which shell commands tldr documents for a platform before fetching a page. It doesn't explicitly name alternatives like 'page' or 'platforms' but implies the workflow.

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

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

The description adds significant context beyond annotations: it makes a single parallel call, replaces many sequential lookups, returns sorted results, and includes citation URIs. Annotations already indicate readOnly, openWorld, idempotent, non-destructive. No contradiction; description enriches understanding.

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

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

Description is packed with useful information and front-loads with examples and user query patterns. It is slightly longer than minimal but every sentence earns its place. Structure is logical: user triggers, action, type-specific details, result format.

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, description explains return value (paired data + citation URIs, sorted by primary metric) and covers all necessary aspects: what each type retrieves, max entities, and efficiency benefit. Complete for this tool's complexity.

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

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

Schema coverage is 100%, but description greatly expands meaning. It explains type='company' retrieves latest 10-K data from SEC EDGAR/XBRL with specific metrics and proper fiscal year handling, while type='drug' pulls FAERS data. Values array is accompanied by examples and constraints. This far exceeds schema alone.

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

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

Description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides specific user query examples ('compare X and Y', 'which is bigger') and distinguishes itself from sequential single-pack lookups. The verb 'compare' and resource 'entities' are well-defined.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear when-to-use directive. It also explains when to use type='company' vs type='drug' with data sources. However, it does not explicitly state when not to use the tool or mention alternatives beyond sequential lookups.

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

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

Annotations already cover readOnly/openWorld/idempotent safety, and the description adds substantial behavior beyond them: mandatory account/payment requirement for depth:'thorough', latency bounds (15-60s, up to ~90s), the gaps[] never-invented guarantee, contradictions[] scanning for standard/thorough, semantic excerpting (not head-truncated), and the citation_uri fetchability contract. No contradiction with annotations — readOnlyHint aligns with its research-only behavior.

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

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

It is front-loaded with the critical account requirement and alternative, and no sentence is pure filler — but it is a single dense run-on paragraph that is hard to scan, and it partially duplicates the schema's depth descriptions rather than only supplementing them. The confusing 'third hop instead of a second hop' phrasing signals inadequate editing.

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

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

Given the absence of an output schema, the description fully compensates by spelling out the return contract (verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation, gaps[], contradictions[], hop field, citation_uri). Auth prerequisites, timing, depth semantics, and behavior on unanswerable facets are all covered — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value by giving example questions, clarifying that broad/multi-part questions are the intended input, and tying the depth parameter to cost (paid plan) and latency. However, the hop explanation ('thorough re-angles in a third hop instead of a second hop') is confusingly worded and somewhat muddles the schema's cleaner depth semantics.

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

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

The description names a specific operation ('grounded multi-source research'), a concrete resource ('Pipeworx's 1494 STRUCTURED data sources' via 5,710 tools), and a distinctive mechanism ('decomposes your question into focused facets, routes each... IN PARALLEL'). It explicitly differentiates from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx as the alternative, so an agent can distinguish this tool without opening any schemas.

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 ('Best for broad/multi-part questions over structured data') with concrete example prompts, and explicit when-not-to-use ('For a single lookup use ask_pipeworx instead') plus a conditional route ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). The auth/tier precondition is stated up front, leaving no ambiguity about eligibility.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds valuable behavioral context: returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain output utility.

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: purpose first, then use-case list, then return format, then usage advice. It is slightly longer than minimal but every sentence adds value. Efficient use of space given the tool's complexity.

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

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

Given the tool's role as a discovery tool with no output schema, the description adequately explains what it returns (top-N tools with full schemas) and how to use it. It doesn't cover ranking details, but the main purpose and output are clear. Completeness is good for the 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 all parameters described, so the baseline is 3. The description does not add new meaning beyond what the schema provides; it mentions aliases but that is already in schema. The schema includes two example inputs, which are helpful but not part of the description itself.

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

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

The description clearly states the verb+resource: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, financials, FDA drugs, etc.) and differentiates from sibling tools by advising 'Call this FIRST when you have many tools available.' This makes the purpose unambiguous and distinct.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It implies not to use when a specific tool is already known, but doesn't name alternative tools for that case. Still, clear guidance is provided.

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 safe, idempotent read. The description adds behavioral context: fans out across multiple sources, patents API sunset soft-failure, and parameter constraints. No contradictions with annotations.

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

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

The description is front-loaded with examples and a clear purpose. While lengthy, every sentence adds value, though minor redundancy exists (examples could be trimmed 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?

Given no output schema, the description comprehensively covers what each source returns (filings with URIs, fundamentals sorted, patents notice, news fallback, LEI). Could note error handling for missing entities.

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 both parameters (100% coverage). The description adds meaning by clarifying value format (ticker or CIK), type limitation (only 'company'), and explicitly warns against using names.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It includes example queries and details output components, distinguishing it from chaining individual 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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use it: 'names not supported (use resolve_entity first).'

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about using it for sensitive data but doesn't elaborate on side effects or error handling, providing minimal additional behavioral insight.

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 short sentences that front-load the action and then provide usage guidance. No unnecessary words.

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

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

For a simple one-parameter destructive tool, the description covers the action, intended use cases, and relationships to sibling tools. It is fully adequate without an output schema.

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

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

Schema coverage is 100% with a well-described 'key' parameter. The description does not add new semantic information beyond what the schema provides.

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

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

The description clearly states the verb ('Delete') and resource ('a previously stored memory') and distinguishes from siblings by the action of deletion versus storage or 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?

Explicitly states when to use the tool: when context is stale, task is done, or clearing sensitive data. Also suggests pairing with sibling tools 'remember' and 'recall'.

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

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

Description adds significant detail beyond annotations: explains the fetch-extract-emit process, output format, and deployment location. No contradictions with annotations.

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

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

Two concise sentences. First sentence clearly states main function, second adds use cases and output context. No unnecessary words.

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

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

No output schema, but description explains output as 'single text blob' and deployment location. Annotations cover safety. Sufficient for the tool's simple nature.

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 both parameters with descriptions (100% coverage). Description does not add new parameter details beyond schema, so baseline score is appropriate.

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

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

Description uses specific verb 'generate', names resource 'llms.txt', and explains purpose for AI crawlers. Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation.

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

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

Lists three explicit use cases (client indexing, own project, competitor auditing) but does not mention when to avoid using this tool or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds useful details like listed fields and the include_inactive parameter effect.

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 purpose, no filler. Every sentence adds value.

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

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

For a list tool with one optional parameter and good annotations, the description effectively covers return fields, usage context, and parameter semantics.

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

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

Schema covers 100% of parameters; description adds context by explaining the include_inactive parameter's purpose beyond the schema description.

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

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

Explicitly states 'List the caller's active subscriptions' and lists returned fields, clearly distinguishing from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'Render tldr page', which is consistent but does not provide behavioral details beyond what annotations 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?

Single, front-loaded sentence with zero wasted words. Every word is necessary.

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, an output schema exists, and annotations cover safety, the description is complete enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 67%; the 'command' parameter lacks a description. The tool description 'for a command' clarifies that this parameter expects a command name, adding meaning beyond the schema. Language and platform descriptions are provided in the schema.

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

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

The description clearly states the tool's action ('Render tldr page') and its target ('for a command'). This is specific and distinguishes it from all sibling tools, which cover different domains.

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 when to use: when a user wants a tldr summary of a command. It does not explicitly state alternatives or exclusions, but given the unique purpose, it's sufficiently clear.

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

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

Beyond annotations, the description discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), return behavior (claim_token), and team response cadence ('reads digests daily'). This adds valuable context that annotations do not convey. 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 longer than average but every sentence serves a purpose—covering scope, alternatives, use cases, token claiming, limits, and cost. It is front-loaded with the core purpose and structured logically. Slight redundancy in explaining claim_token twice, but overall efficient for the complexity.

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

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

Given 4 parameters with nested objects and no output schema, the description adequately explains return values (claim_token, status, changes) and operational constraints (rate limits, quota). It also covers edge cases like distinguishing Pipeworx tools from other servers, making it complete for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter semantics by explaining claim_token usage in detail ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising on message content ('don't paste the end-user's prompt'). It also clarifies context fields implicitly by referencing 'which tool, pack, or vertical this relates to.'

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

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

The description explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific resource (Pipeworx team) and the action (tell/feedback), and distinguishes it from sibling tools by making it the designated channel for reporting issues about Pipeworx-provided 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 provides explicit when-to-use guidance: bug reports, feature requests, data gaps, praise. It also clearly states when NOT to use it ('if the tool came from a different MCP server... file it with that server instead') and gives practical instructions like 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.'

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, idempotentHint, and non-destructive. The description adds value by disclosing caching duration (5min-1h), data source (CF analytics-engine), and privacy (no PII). No contradiction with annotations.

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

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

Three sentences plus bulleted use cases, with no redundant words. Information is front-loaded and well-organized. 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?

While the description covers purpose and usage well, it lacks explicit detail on the output format (e.g., structure of returned data). For a tool with no output schema, this is a gap. Still, it's adequate for a simple trending query among many siblings.

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

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

Schema coverage is 100% for the single parameter 'window'. The description restates enum values and adds context about short vs. long window interpretation. This adds marginal value beyond the schema, 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 it returns 'top tools, top packs, and total call volume' over a recent window, with specific verb ('Returns') and resource ('what other AI agents are calling on Pipeworx'). It distinguishes from siblings by focusing on trending data derived from other agents, not general search or 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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. However, it does not mention when not to use this tool or contrast it with alternatives like discover_tools or search, which could be improved.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond this: it is 'derived from the tldr-pages index published on GitHub' and 'Returns the sorted set,' disclosing the source and ordering behavior.

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

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

The description is three sentences, each earning its place: (1) states the primary list operation and enumerates the platforms, (2) explains the returned sorted set and its relation to other tools, (3) gives a practical usage example. 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?

For a simple no-parameter tool with an output schema, the description is complete. It covers what the tool does, the source of the data, the return behavior (sorted set), and how to use it when invoking other commands. Nothing essential is missing.

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

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

The tool has zero parameters, so baseline is 4. The description doesn't need to explain parameters, and the input schema fully covers the empty parameter set. The description reinforces the purpose rather than adding parameter-specific semantics.

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

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

The description clearly states the tool's function: 'List the platform keys present across the tldr-pages cheatsheet collection' and 'Returns the sorted set of platform values that the page, commands, and search tools in this pack accept.' It uses a specific verb and resource, and distinguishes itself from sibling tools by positioning as the source for platform values used by other 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 provides clear context for when to use the tool: 'Answers which platform value to pass when looking up a tldr command cheatsheet.' While it doesn't explicitly name alternatives or exclusions, the context is sufficient to guide selection among 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?

The description discloses detailed behavioral traits: internal checks (monotonicity, partition_sum, Jaccard similarity, placeholder filtering, fill check against CLOB depth). It aligns with annotations (readOnlyHint, openWorldHint, etc.) and adds value beyond them by describing response structure and trade feasibility.

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

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

The description is front-loaded with the main purpose and modes, but it is quite long due to detailed logic explanations. Every sentence adds value, but there is some redundancy (e.g., repeated emphasis on not trading when realizable edge <=0). Still, it is well-structured for its 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 complete: it explains call patterns, internal algorithms, edge cases (e.g., placeholder filtering, low similarity), response structure, and cross-reference to polymarket_fill_risk. With no output schema, the description adequately covers return values and trade decision logic.

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 description adds substantial meaning: explains how 'event' walks child markets and checks ordering, and how 'topic' searches related events and applies similarity filters. It also describes response fields (gap_pp, suggested_trade, etc.) beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the method, distinguishes from siblings like polymarket_edges and polymarket_fill_risk, and covers the unique functionality of arbitrage detection.

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

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

The description provides explicit usage guidance: call with NO args for trending scan, use 'event' for specific market slug, and 'topic' for cross-event scanning. It explains when each mode is appropriate and includes a prerequisite (Jaccard similarity >=0.30) and a do-not-trade condition (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?

Provides extensive behavioral detail beyond annotations: explains model families, edge calculation, tradeable-edge knobs, caching, and empty-segment diagnostics. No contradictions with annotations.

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

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

Front-loaded with purpose, but the description is very long and dense. Could be more concise while retaining key details.

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

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

Despite no output schema, the description fully explains response structure (by_segment, diagnostics), caching, and edge cases like Fed bets. Complete for the 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?

All parameters have schema descriptions (100% coverage), and the tool description adds context on usage and defaults, e.g., min_kelly filters small opportunities, min_partition_leg_kelly for partition arbs.

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

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

Clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', specific verb+resource, distinguishes from siblings like polymarket_arbitrage.

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

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

Explicitly built for 'what should I bet on today' and saves paging hundreds of markets, but lacks direct alternatives or when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: source from daily snapshots, response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, daily closes, not intraday), and interpretation of decay numbers. No contradiction.

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

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

The description is well-structured: starts with a one-liner purpose, then a question/answer framing, followed by a detailed response format with bullet points. It is somewhat verbose but each sentence adds value; could be slightly tightened.

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 the return format (tracked, expired, snapshot_dates) and their fields (e.g., first_seen, trend, decay_pp_per_day). It also covers limitations and assumptions (60-day TTL, daily closes). No gaps.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window) including defaults and constraints. The description adds only minor elaboration (e.g., 'lookback' for days) but does not significantly enhance 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 clearly states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, distinguishing it from siblings like polymarket_edges which likely give current edges only. The scenario 'a fresh wide edge and a 3-week-old wide edge are different trades' illustrates the unique value.

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

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

The description gives a concrete use case ('how long has this edge existed and is it shrinking?') and implies when to use (to distinguish new vs. old edges). It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral details: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about thin books and forced directional risk. No contradiction with annotations.

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

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

The description is front-loaded with the purpose, uses structure (SINGLE-MARKET and BASKET sections), and every sentence contributes value. However, it is somewhat verbose and could be slightly more concise. Still, it is well-organized for a complex tool.

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

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

Despite lacking an output schema, the description enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains both modes. It covers parameters, edge cases, and risks, making it complete for an agent to decide when to use the tool.

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

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

Schema description coverage is 100%, and the description adds significant extra meaning: it explains the two modes (single-market vs basket), default values for side and size_usd, interpretation of size_usd for buys vs sells, and the concept of settlement notional in basket mode. This exceeds the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It uses a specific verb and resource, and distinguishes between single-market and basket modes. The sibling tools include polymarket_arbitrage and polymarket_edges, and the description explicitly differentiates 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?

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also implies when not to use it (smaller trades) and explains the risks of partial basket fills converting an arb into an unhedged directional position.

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

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

The annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond those by explaining matching behavior: unknown metric_type/match_subtype legs are never paired, compatibility fields can be non-empty even when matched_pairs>0, and the premapped_pairing_unverified code is always set in topic mode. It also discloses skipped counters and the temporal alignment semantics, which gives the agent a realistic picture of the tool's outputs and limitations.

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

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

The description is long, but it earns its length by covering modes, response semantics, safety fields, compatibility codes, skipped-leg behavior, and important caveats. It front-loads the core purpose and mode selection before diving into safety flags. It could benefit from bullet points or section breaks, but there is very little 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?

Because there is no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and skipped counters. It also gives operational guidance such as reading compatibility fields even when matched_pairs>0, making this a complete and self-sufficient description for a read-only analysis 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?

All three parameters are already documented in the input schema (100% coverage), so the baseline is 3. The description adds value by providing concrete examples (KXFED-26OCT, fed-decision-in-june-825), listing the exact topic values, and clarifying that explicit ticker/slug parameters override the topic-mapped side. This goes slightly beyond the schema without duplicating 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?

The description opens with a clear statement of purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further clarifies scope by describing the two modes (topic shortcuts vs explicit ticker/slug), which makes the tool's resource and operation concrete. It does not explicitly distinguish itself from sibling tools like polymarket_arbitrage, but the intended function is 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 gives clear guidance on how to select a mode: use topic for the 10 pre-mapped macro shortcuts, or use explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that pre-mapped topics often produce compatibility warnings and are not automatically tradeable, which helps set expectations. It does not explicitly compare against sibling tools, but the mode guidance is strong enough to be actionable.

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

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

Description details retrieval behavior, listing behavior, scoping, and pairing, complementing annotations that indicate read-only and idempotent. No contradictions.

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

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

Three focused sentences: function, usage examples, and scoping. 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?

Fully explains purpose, usage, parameters, and scope for a simple tool with one optional parameter and clear annotations.

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

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

Schema already covers the key parameter with its omit-to-list behavior; description adds context about typical use cases (ticker, address, notes) and scoping, providing marginal added value over schema.

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

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

Clearly identifies the tool as retrieving saved values or listing keys. Distinguishes from siblings remember and forget via explicit mention.

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

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

Explicitly states when to use (look up stored context) and how (omit key for list). Provides context: scoped to identifier, pairing with remember/forget.

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

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

The description contradicts the readOnlyHint annotation by stating mark_read:true flags events as read, modifying state. This is a direct contradiction, warranting a score of 1 per rubric.

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 efficient, front-loading the main purpose, then detailing parameters, and ending with an alternative. Every sentence serves a purpose with no redundancy.

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

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

Given no output schema, the description describes return fields and provides an alternative HTTP endpoint. However, it lacks pagination details beyond the limit parameter, leaving some 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%, baseline 3. The description adds value by explaining parameter effects with examples (type, since, mark_read), default limit, and return fields, going beyond the schema.

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

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

The description clearly states it pulls fired events from subscription feed, specifying return fields. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on alert events, but lacks explicit differentiation.

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

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

The description mentions an alternative HTTP endpoint for scripts/dashboards, suggesting polling is appropriate, but does not contrast with other sibling tools or specify when not to use it.

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

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

Annotations already indicate idempotent, read-only, non-destructive. The description adds behavioral details: fans out to multiple sources (SEC, GDELT→GNews, USPTO), fallback behavior, and soft-fail for USPTO. 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 a single well-organized paragraph, front-loaded with query examples. Each sentence adds value, but it could be slightly more concise. However, the information density is high and efficiently conveyed.

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

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

For a tool with 3 parameters and no output schema, the description adequately explains all aspects: sources, fallback behavior, parameter formats, return structure (changes[] grouped by source, total_changes, citation URIs), and when to use an alternative. Nothing essential is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical context: explains `since` accepts ISO or relative shorthand with examples, `value` can be ticker or CIK, and `type` enum is only 'company'. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It uses specific verbs and resources, and distinguishes from the sibling tool 'entity_profile' by stating when to use the alternative.

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

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

Explicit examples of queries are provided ('What's new with X', 'latest on Y'). It gives clear usage context: 'Use entity_profile instead when you want the static profile...' This directly tells the agent when to choose this tool over a sibling.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds key-value store scoping by identifier, persistence details (authenticated persistent, anonymous 24h), which is valuable 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?

Well-structured paragraph with clear flow: purpose, usage, storage details. Slightly verbose with examples but overall concise.

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

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

For a simple key-value save tool with no output schema, the description covers all needed aspects: usage, persistence, pairing with sibling tools.

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

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

Schema descriptions are minimal ('Memory key', 'Value to store'). The description adds examples of keys and values, enhancing understanding beyond schema.

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

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

The description clearly states the tool saves data for reuse, with specific examples like ticker, address, and preferences. It distinguishes from siblings recall and forget by mentioning pairing.

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: 'when you discover something worth carrying forward' and recommends pairing with recall and forget. 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by explaining cascading lookups, graceful degradation (Lei/FIGI fallback), and that unresolved identifiers are stated explicitly. 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 quite long with multiple paragraphs including detailed sub-explanations for company and drug types. While every sentence adds value, the length may reduce quick scanning efficiency. It is front-loaded with examples and the key directive, which helps, but overall conciseness is only adequate.

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 and high tool complexity (multi-source resolution with cascading), the description covers input types, output elements (identifiers, sources, unresolved), behavior (graceful degradation), and ownership data. It sufficiently equips an AI agent to understand what to expect, making it contextually complete.

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

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

Schema coverage is 100% with short descriptions. The description substantially enriches meaning: explains valid input formats for 'value' (e.g., ticker, CIK, ISIN, name for company; brand/generic for drug), details what each type resolves to (e.g., EDGAR CIK, LEI, FIGI), and gives examples. This goes well beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific verb 'resolve entity' and resource names/IDs. It provides example queries that illustrate the purpose. However, it does not explicitly differentiate this tool from sibling tools like 'entity_profile' or 'compare_entities', which also deal with entities, slightly reducing clarity of unique role.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' This is strong guidance. It also mentions that the tool replaces 2-3 manual lookups, indicating efficiency. However, it does not provide explicit when-not-to-use scenarios or list alternative tools, leaving some gaps.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details (probes each entity, ranks by score, surfaces most/least recognized, returns ranked list with score/confidence/signal density) that are not present in annotations, increasing transparency 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 concise (two sentences) and well-structured: it states the core purpose, describes the mechanism, and gives a practical usage example. 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 complexity (multiple entities, optional parameters, external API key), the description fully explains input (entities array with subject, models, API key, context) and output (ranked list with score, confidence, signal density). No output schema needed as description covers return values.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and that context disambiguates common names, providing useful semantic context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (across multiple entities), distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (different comparison context).

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

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

Explicit context is provided: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' This implies when to use the tool, and the mention of probing with ai_visibility_check suggests that for single-entity checks, one should use that sibling tool instead.

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, open-world, and idempotent. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed will list timeouts, and the remaining data still returns. 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 comprehensive but not overly verbose. It front-loads the core purpose and includes all essential details in a logical flow. Could trim a few words but remains efficient for the amount of information conveyed.

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 fully explains the return structure: summary block with fields listed, per-advisory detail, links, alternative versions, and sources_failed on error. For a tool with 2 params and no nested objects, this is complete and actionable.

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 minor context: package accepts scoped names, version defaults to latest. But it doesn't add meaning beyond what the schema already provides, hence a 3.

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

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

The description clearly states the tool's composite nature: it checks multiple aspects of an npm package (license, advisories, version history, bundle size, ESM/tree-shake support) in one call. It uses specific verbs like 'fans out' and enumerates resources, making the purpose distinct from all sibling tools.

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

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

Explicit usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies limitations (NPM only v1, other ecosystems via deps.dev:version) and gracefully handles partial failures with timing warnings.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety profile is covered. The description adds the substring search behavior but no additional details like pagination or result format. Adequate but minimal extra value.

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 one concise sentence with no fluff. It is front-loaded with the core action. However, the extreme brevity sacrifices valuable detail.

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

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

Given 4 parameters, an output schema, and many sibling tools, the description fails to provide sufficient context. Missing parameter explanations, usage scenarios, and differentiation from other search tools makes it incomplete.

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 0%, and the description does not explain any of the 4 parameters (query, limit, language, platform). This forces the agent to guess their meaning, which is inadequate.

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 'substring search across page titles', which is a specific verb and resource. It distinguishes from sibling tools like 'search_within' which likely searches within page content.

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

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

No guidance on when to use this tool versus alternatives like 'search_within' or 'page'. The agent must infer usage from the description alone, which lacks explicit 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 safe, read-only, idempotent behavior. Description adds valuable context: embedding model (BGE-base-en), windowing (500-char overlapping), character offsets, 200K char cap with truncation flag—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, no redundant words, front-loaded with key action ('Semantic search INSIDE a fetched record'). Every sentence adds value.

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

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

Despite no output schema, the description explains return values (passages, character offsets, similarity scores) and covers behavioral details (windowing, cap) comprehensively.

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 all 3 parameters with descriptions (100% coverage). Description adds context for 'text' (cap, truncation) and 'query' (examples), providing additional meaning beyond the schema.

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

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

The description uses a specific verb-resource pair ('semantic search inside a fetched record') and provides concrete examples (SEC 10-K, article) that distinguish it from siblings like 'search' or 'ask_pipeworx_grounded'.

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

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

Explicitly states when to use (record too large for prompt) and pairs with ask_pipeworx_grounded. Does not explicitly list when not to use, but the context is clear.

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

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

Annotations (readOnlyHint: false, openWorldHint: true, idempotentHint: true, destructiveHint: false) are supplemented with rich behavioral details: account requirement, return value, delivery channel specifics (SMS cap, webhook auto-disable), and 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 thorough but could be more structured (e.g., bullet points for types). However, it front-loads the core purpose and every sentence adds value, with no 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 the tool's complexity (multiple types, delivery channels, constraints), the description covers requirements, expected behavior, and edge cases (e.g., SMS cap, webhook failure). No output schema exists, but the return value is clearly stated.

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 significant meaning beyond the schema, e.g., examples for each type, detailed delivery constraints (phone verification, webhook HMAC signing, auto-disable). This helps the agent correctly construct parameters.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts by focusing on creation and specifying supported types and delivery channels.

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 context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery options. It does not explicitly contrast with alternatives like reading subscriptions, but the purpose is clear enough for an agent to decide when to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it returns category-bucketed examples with exact tool+argument shapes, which provides useful output context without contradicting annotations.

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

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

The description is somewhat lengthy and includes multiple example phrasings in the parenthetical list. While informative, it could be more concise without losing key information, but the front-loaded structure helps quickly convey 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?

Given no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shapes) and its source (live catalog). For a tool with one optional parameter, it covers all essential aspects.

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 a description for 'topic'. The description adds specific example values ('finance', 'pharma', etc.) and clarifies that omitting the parameter yields a cross-category spread, going beyond the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions and is the onboarding entry point for Pipeworx. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by positioning itself as the first tool to use when unsure of capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools, giving clear context for when to use it versus 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 discloses that the row is deactivated (not deleted) and historical events remain available, which goes beyond the annotations (no destructive hint). It also confirms ownership enforcement. No contradiction with annotations.

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

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

Three sentences that are all essential, no redundancy. The action is front-loaded, and every sentence adds value without wasting words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the effect (deactivation, history kept), ownership, and the parameter's source. No gaps.

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

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

Schema coverage is 100% with a clear description of the parameter 'id'. The description does not add additional information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id'. It also adds specificity with ownership enforcement and the deactivation behavior, distinguishing it from siblings 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 explicitly notes that ownership is enforced, telling agents they can only cancel their own subscriptions. This provides clear context but does not explicitly mention alternative tools like 'subscribe' for creating subscriptions.

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

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

The description discloses important behavioral traits not in the annotations, such as conditional routing based on claim type, the meaning of could_not_verify (check did not happen, not evidence), and unsupported (no source found). It also states the tool returns verdicts, actual value, and reasoning, and it carries no contradiction with the readOnly/idempotent annotations.

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

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

The description is longer than a single sentence, but each section earns its place: examples, purpose, use case, routing rules, return values, caller warnings, and efficiency note. It is front-loaded with the core purpose after a brief example list, and stays on-topic without 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?

There is no output schema, so the description's responsibility to explain return values is fully met: it enumerates the verdict enums, mentions grounded/structured values with citations, and details error-handling semantics. The description is complete for a tool with this complexity, covering internal routing and caller-facing caveats.

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 parameter baseline is 3. The description adds only modest contextual value by providing example claim phrasings and explaining tolerance logic, but it does not significantly elaborate on the parameter definitions 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 explicitly states 'natural-language claim verification against authoritative sources,' providing a specific verb and resource. It further distinguishes itself from sibling tools by detailing the two-path routing (SEC EDGAR/XBRL for financial claims, grounded pipeline for others) and by noting it replaces 4–6 sequential calls.

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

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

It says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It does not name a specific alternative sibling but implies that using this single tool supersedes multi-step sequential calls, which serves as usage guidance.

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