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. The description adds valuable behavioral context: routes to 5,462 tools, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. This goes beyond annotations, though it doesn't discuss failure modes or rate limits.

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

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

The description is long but front-loaded with the most important information ('PREFER OVER WEB SEARCH') and organized logically. Every sentence contributes useful guidance, though a few redundant phrasings could be tightened without losing value.

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

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

Given the tool's complexity (a meta-router for thousands of tools) and the absence of an output schema, the description is remarkably complete: it covers when to use, what to expect (citations), alternatives, and examples. It could mention error handling or the shape of the returned structured answer, but for its scope, it's strong.

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

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

Schema description coverage is 100%, with all six parameters documented in the schema (including aliases). The description itself doesn't add parameter-level details, but the schema is sufficient, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: routes factual questions to authoritative structured data sources and returns answers with citations. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific needs, and provides concrete examples of supported queries.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives step-up guidance ('Step up only when needed') with named alternatives. It also provides when-not-to-use context for deep_research and grounded, plus example phrasings that trigger use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the description can focus on added value. It transparently discloses that no candidate is currently active (last retired 2026-07-26), so it currently matches ask_pipeworx exactly, and that it falls back to nothing—it is a full working router, not a stub. This adds useful behavioral context beyond the annotations.

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

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

The description is a single paragraph of four sentences, each earning its place: it establishes identity, current state, usage guidance, and the fallback behavior. Front-loaded with the tool's purpose and alternatives, with zero redundancy.

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

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

Given the tool's simplicity (one effective parameter with aliases, no output schema, and rich annotations covering safety), the description covers all critical aspects: what the tool is, when to use it, current experimental state, and that it functions fully. No significant gaps remain for an agent to misuse it.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for 'question', with the primary 'question' parameter described as accepting natural language. The description does not add beyond the schema, but equals it; the baseline for high coverage is 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 identifies this as a beta variant of ask_pipeworx: an identical universal router with the same 5,462 tools, arguments, and response shape, but with candidate routing improvements enabled when under test. It distinguishes itself from the stable sibling ask_pipeworx by emphasizing its experimental nature, though it does not explicitly name the stable alternative in the same sentence.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This provides clear guidance on when to use this beta variant vs the stable tool, fulfilling the when/when-not requirement.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses critical behavioral traits: it extracts answers using ONLY tool results, returns a structured object with verbatim evidence, and explicitly enumerates refusal reasons (e.g., not_in_source, no_tool_match). It also discloses the extra LLM call cost, which is not captured by annotations. This is rich, transparent context.

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

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

The description is dense but every sentence adds value: purpose, routing behavior, return format, refusal reasons, usage instructions, and trade-off all included. It is front-loaded with the core concept and uses clear structured punctuation (lists, pipe-separated refusal reasons) for readability. No filler or repetition.

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

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

With no output schema, the description thoroughly explains the return object and all failure modes, which is essential for an agent to interpret results. It also covers the performance trade-off and provides enough context to decide when to use this tool versus ask_pipeworx. For a complex tool, the description is remarkably 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%: all six parameters are documented as natural-language questions or aliases. The description does not add additional parameter-level detail (e.g., formatting, length limits, examples), so it meets the baseline for high schema coverage. The description's mention of "question in natural language" is redundant with the schema, thus no extra points.

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

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

The description opens with a specific, concrete purpose: "Hallucination-resistant answer mode for high-stakes reads." It clearly states the process (routing, fetching data, extracting answers using only tool results) and distinguishes from the sibling tool ask_pipeworx by highlighting the grounded, evidence-based extraction and explicit refusal behavior. This is a specific verb+resource that separates it from 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 gives explicit when-to-use guidance: "Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts." It also states when NOT to use it: "prefer ask_pipeworx for casual lookups" and cites the cost trade-off. This is clear, actionable, and distinguishes it from 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 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?

The description adds no behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It does not explain what 'commands' refers to, nor does it disclose any traits like pagination or result format. The output schema exists but is not described.

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

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

While the description is extremely concise at two words, it is under-specified for a tool with two parameters and many siblings. Conciseness should not sacrifice necessary detail; here, the brevity is detrimental.

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 low complexity, the description is severely inadequate. It does not specify what is listed, what the parameters do, or provide any context despite having an output schema. The tool appears simple but the description fails to make 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?

Schema description coverage is 0%, and the description does not explain the parameters 'language' and 'platform'. The examples hint at filtering, but the description fails to add any semantic meaning, leaving the agent to guess their purpose.

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 'List commands.' clearly states the verb 'List' and resource 'commands', avoiding tautology. However, it is extremely brief and does not differentiate from sibling tools like 'discover_tools' or 'platforms', making the purpose somewhat vague.

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 usage guidelines are provided. There is no indication of when to use this tool, when not to, or how it compares to alternatives such as 'discover_tools' or 'platforms'. This leaves the agent without context for selection.

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

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

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context beyond annotations: parallelism across 5,462 tools, facets decomposition, gap recovery, contradictions scan, hop field, citation fetchability guarantee, semantic excerpting, time expectations, and the limitation that unsupported topics return empty gaps. It also discloses account/payment requirements. 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 extremely information-dense and front-loaded with the account warning, but it is a single paragraph with many semicolons and parentheticals, making it hard to parse. Every sentence earns its place, but the lack of structural breaks (bullets or short paragraphs) hurts scannability. For the amount of critical context, the length is justified, but structure is suboptimal.

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

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

For a complex tool with no output schema, the description does a strong job: it explains what the findings packet contains, timing, limitations, and citability. However, it does not explicitly describe the exact JSON shape of the response beyond naming fields (evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions, hop). Given no output schema, a bit more structural detail would make it complete, but the behavioral description largely compensates.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how depth values map to behavior (quick=3 facets, standard=5 + gap recovery + contradictions, thorough=8 paid + iterative hop), which goes beyond the enum names. Question parameter semantics are also enriched with guidance that broad/multi-part questions are fine. Loses one point because the description is so dense that some depth nuance is only in the schema, but the added semantic context justifies a 4.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call. It clearly distinguishes from siblings by contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx') and warning that deep_research is NOT open-web search. The scope (broad/multi-part questions over structured data) is explicit, with examples.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It says 'Best for broad/multi-part questions over structured data' and directly names the alternative: 'For a single lookup use ask_pipeworx ... For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also gives prerequisites (account required, depth:thorough needs paid) and fallback ('If you are not signed in, use ask_pipeworx instead'). This is exemplary.

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 (which are all false), the description discloses meaningful behavior: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, team reads digests daily, and signal directly affects roadmap. This gives the agent a clear picture of consequences and constraints 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 a single dense paragraph but front-loaded with the core purpose. Every sentence provides useful guidance (scope, rate limit, quota, roadmap impact). It could be slightly more scannable with bullet points, but it remains efficiently written 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?

For a feedback tool with no output schema, the description covers all necessary context: what to report, what not to report, how to frame the message, rate limits, quota impact, and even how the feedback is used (daily digests, roadmap). It is fully complete for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by instructing users to describe issues 'in terms of Pipeworx tools/packs' and not to paste the end-user's prompt, which gives important practical guidance for the message and context parameters. However, it doesn't directly re-explain each field since the schema already does that thoroughly.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools like ask_pipeworx and discover_tools by focusing on reporting issues to the Pipeworx team, not retrieving information.

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

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

The description gives explicit when-to-use guidance with concrete examples (bug, feature, data_gap, praise) and an explicit when-not-to-use rule: do not report issues for tools from other MCP servers, as they cannot be fixed by Pipeworx. It also helps disambiguate by noting Pipeworx tool names are those listed by this connection.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no further behavioral context beyond what annotations provide, essentially just restating the tool's purpose.

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 extremely concise—one sentence. It is front-loaded and contains no extraneous text, though it could be slightly more informative.

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

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

Given no parameters, rich annotations, and an existing output schema, the description is sufficiently complete for a list tool. It tells what the tool does without missing essential context.

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

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

The tool has zero parameters and 100% schema description coverage. Baseline is 4. The description does not need to add parameter info beyond the schema, which is already complete.

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 lists supported platforms. It is a specific verb+resource pair and distinguishes itself from siblings since no other sibling tool appears to list platforms.

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 is provided on when to use this tool versus alternatives. The description lacks context on usage scenarios or when to prefer other tools.

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

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

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?

Beyond annotations, the description reveals key behavioral details: compatibility_warning logic, temporal_alignment check, and skipped_cross_type/subtype counters. It also warns that spreads are rare despite the macro-shortcut list. No contradiction with annotations.

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

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

The description is lengthy but well-structured with bold terms and clear sections. Some sentences are dense but necessary for the complex tool. Minor redundancy could be trimmed.

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

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

Despite no output schema, the description thoroughly covers return values (leg prices, spread, safety fields like compatibility_warning and temporal_alignment). It also explains edge cases, making it complete for agent decision-making.

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

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

Schema coverage is 100%, but the description adds value: explains the topic list, that explicit tickers override topic-mapped sides, and describes response fields (leg prices, spread, safety fields). This goes 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage. It specifies two modes and lists pre-mapped topics.

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 guides when to use and not use: explains compatibility_warning conditions (shape mismatch, semantic mismatch) and warns that most pre-mapped topics return warnings and are not tradeable. Also explains the two modes and how to use explicit tickers.

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 cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavior: it cascades through several lookup endpoints, returns citation URIs and specific fields (ticker, CIK, company_name, RxCUI, ingredient, brand), and auto-disambiguates input. This goes beyond the annotations without contradicting them.

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

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

The description is longer than ideal but well-structured: front-loaded with natural-language trigger phrases, then SUPPORTED TYPES breakdown. Each sentence contributes unique information (return fields, citation URIs, internal cascading), though it could be tightened by removing redundancy between examples and the type breakdown.

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

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

No output schema exists, so the description carries the burden of explaining return values, which it does comprehensively (ticker, CIK, RxCUI, citation URIs, etc.). It also explains the internal multi-step process and positions itself against sibling tools that require identifiers, making it complete for an agent to select and invoke correctly.

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

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

Schema covers both parameters fully with descriptions and examples. The description enhances semantics by detailing what each type returns and how value is interpreted (e.g., 'auto-disambiguated', accepts ticker, CIK, or name), adding meaning beyond the schema's generic examples.

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

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

The description clearly identifies the verb 'resolve' and specific resource 'user-spoken name to canonical/official identifier', with concrete examples like tickers, CIKs, and RxCUIs. It distinguishes itself from sibling tools by positioning itself as a prerequisite for other tools that require identifiers as input.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', giving a clear condition and priority. It implies when not to use (if you already have the ID), but does not name alternative tools like entity_profile for that case, so not a full 5.

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

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

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

Annotations show readOnlyHint=true, openWorldHint=true, etc. Description adds detailed behavior: uses SEC EDGAR for financial claims, grounded pipeline for others, returns verdict with citations and reasoning. No contradiction.

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

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

Description is detailed and well-structured with examples and routing logic, but slightly long. Every sentence earns its place, though minor trimming possible.

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

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

Given complexity, no output schema, description covers return values (verdict, actual value, citation, reasoning) and both scenarios. Sufficient for agent to invoke correctly.

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

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

Schema coverage is 100%, but description adds context: explains claim with examples, describes tolerance_pct default and override use. Adds value beyond schema.

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

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

Description clearly states it verifies natural-language claims using authoritative sources, with specific verb 'validate' and resource 'claim'. Distinguishes from siblings by detailing routing for financial vs. other claims.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides separate handling for company-financial and other claims, and implies when not to use.

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