Arcgis Sarpycounty

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

Annotations already indicate a safe, idempotent read operation. The description adds behavioral context: cost implications for Anthropic calls (BYO key, pay directly), default model, and return structure (per-model + combined). 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 concise (3 sentences) and front-loaded with the core purpose. Every sentence adds essential information: purpose, default model, API key condition, return format, and use cases. No wasted words.

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

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

Given the tool has 4 parameters (all documented in schema) and no output schema, the description adequately explains the return format (per-model score, confidence, signals, raw_response + combined view). It also mentions the use cases, making it complete for an agent to understand 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?

With 100% schema description coverage, the baseline is 3. The description adds value by clarifying default behavior for 'models' (only workers-ai if omitted), explaining '_apiKey' necessity, and providing examples for 'entity' and 'context'. 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 uses specific verbs ('probe', 'score visibility') and identifies the resource (LLMs for business/brand/product/topic). It clearly distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes when to use the API key for Anthropic. However, it does not explicitly state when not to use this tool or mention 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: it routes to the right tool, fills arguments, returns structured answer with stable citation URIs, works on every tier, one fast call. No contradiction; full disclosure.

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 key directive 'PREFER OVER WEB SEARCH' and progressively details use cases, examples, and alternatives. Every sentence contributes value without redundancy. Length is appropriate for the tool's power.

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 6 params (all same), 33 siblings, no output schema, the description is remarkably complete. It covers purpose, when to use, what it returns (structured answer with citations), examples, and how it differs from alternatives. Nothing critical is omitted.

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 clear descriptions for all 6 parameters (all aliases for the question). The description does not add meaning beyond the schema's 'natural language' description; it focuses on usage context rather than parameter details. 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 the tool routes questions to one of many tools, returns structured answers with citations, and explicitly says 'PREFER OVER WEB SEARCH' for factual data. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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 criteria (e.g., 'Use whenever the user asks "what is", "look up", "find"...') and when-to-step-up alternatives (grounded for hallucination-resistant answer, deep_research for broad/multi-part). It also clarifies that breaking news is covered. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the beta nature, candidate testing, and current state (no active candidate). It confirms it's a full working router, not a fallback. No contradiction with annotations.

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

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

The description is a single paragraph but concise and to the point. Every sentence adds value (identity, current state, usage instruction, fallback clarification). Slightly more structured formatting could improve readability.

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

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

No output schema, but the description explains the beta context, candidate status, and relationship to the stable tool. It doesn't detail return shape, but given the tool mirrors ask_pipeworx, the agent can infer. Adequate for the complexity level.

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 as aliases for 'question'. The description adds no further meaning or usage guidance beyond what the schema provides. 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 this is the beta version of ask_pipeworx, identical in functionality but with experimental routing improvements. It distinguishes itself from the stable router and provides specific context about candidate testing and current state (no active candidate).

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It implies when not to use (when you don't want experimental) but doesn't give explicit exclusions or mention alternatives like ask_pipeworx_grounded.

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 thoroughly discloses the tool's behavior beyond annotations: it details the exact return format (answer, evidence with verbatim quote, confidence, source, fetched_at, refusal_reason), enumerates all refusal reasons, and explains the processing pipeline (picks tool, fills arguments, fetches data, extracts answer using only tool output). Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces non-hallucinatory behavior 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 information-dense and well-structured, with the core purpose front-loaded and critical details (return format, refusal reasons, use cases) organized logically. While it is relatively long, every sentence adds value and no unnecessary words are present. Could be slightly tighter but remains clear and complete.

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 lack of an output schema, the description fully compensates by detailing the return structure (success and failure cases), all refusal reasons, and the processing logic. It also addresses the complexity of 6 parameters and the sibling relationship with ask_pipeworx. The description leaves no significant behavioral question unanswered.

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 6 parameters all described as aliases for 'question'. The description adds 'Your question in natural language' but this largely repeats the schema's own description. No additional semantic nuance is provided beyond what the schema already captures, so the 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 identifies the tool as a grounded/hallucination-resistant answer mode for high-stakes reads, with a specific verb ('answer') and resource ('Pipeworx data across 5,564 tools and 1462 sources'). It explicitly distinguishes itself from the sibling 'ask_pipeworx' by highlighting the extraction-only behavior and refusal mechanism.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also specifies when not to use it: 'prefer ask_pipeworx for casual lookups,' with a clear trade-off ('Costs one extra LLM call').

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral detail: fan-out logic, classifier examples, response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling, illiquid spread warnings), and resolution-rule risk. No annotation contradiction.

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

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

The description is lengthy but well-structured, starting with the core purpose and then expanding into sections on classifiers, fan-out examples, response shapes, resolver contract, safety, and resolution rules. Every sentence adds value, though some sections could be slightly more concise. Front-loaded with the most critical information.

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

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

Given the complexity of the tool (multiple classifiers, fan-out to various sources, complex response structure), the description covers all relevant aspects: how inputs are resolved, what data is fetched for each bet type, response fields, matching confidence, error handling, and edge cases. No output schema exists, so the description fully compensates by detailing return shapes.

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

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

Schema coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description adds value by explaining the difference between 'quick' and 'thorough' depth, showing example inputs for market, and clarifying the effect of include_raw on response size. This contextual information goes beyond the schema fields.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes itself from siblings like polymarket_arbitrage or polymarket_edges by focusing on holistic research with fan-out to multiple data sources.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides multiple classification examples and fan-out scenarios. While not explicit about when not to use, the context is clear and sufficient for an agent to decide.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses that company data comes from 'SEC EDGAR/XBRL' with accurate fiscal year handling (e.g., AAPL Sep, NVDA Jan) and drug data from FAERS for adverse events, FDA approvals, and trials. It also states results are sorted by primary metric and returns citation URIs.

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 long but front-loaded with common query patterns. Every sentence adds new information (data sources, sorting behavior, use cases). A slight reduction could be possible, but it remains efficient given the complexity of the comparison 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?

No output schema exists, but the description mentions 'Returns paired data + pipeworx:// citation URIs per entity.' It also clarifies sorting and the data sources for each type. While it could add more detail on the output shape, it provides sufficient context given the tool's comparative 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 coverage is 100% and parameter descriptions are adequate. The description adds value by providing examples (e.g., tickers/CIKs for company, drug names like 'ozempic') and explaining what data each type returns. This enriches the parameter meaning beyond the schema's bare descriptions.

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

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

The description starts with clear example queries ('Compare X and Y', 'X vs Y', 'which is bigger'), then explicitly states it does 'side-by-side comparison of 2–5 companies or drugs'. It distinguishes from sequential single-pack lookups by saying 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive. It also implies that for single entity lookups, 'entity_profile' is the sibling alternative, but that's not stated. However, the context signals include sibling tools like 'entity_profile', and the description's strong preference statement 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds verified value beyond these: it explains account/auth requirements (sign-in needed, depth:'thorough' needs paid plan), latency expectations (15-90s), the internal parallel decomposition process, the return format (findings with evidence, confidence, source, gaps[], contradictions[]), and that findings are semantically excerpted (not head-truncated). The only minor gap is it doesn't explicitly state that results are not real-time (though 'structured catalog' implies it). No annotation 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 packed with useful information but is somewhat dense and could be slightly more structured. The first sentence covers the critical prerequisite (account requirement) and the fallback, which is front-loaded well. Some details like 'second-hop iteration' and 'large records are semantically excerpted' could be organized into a clearer bullet or callout, but the current prose is not excessive.

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 (2 params, high annotation coverage, no output schema), the description is remarkably complete. It explains prerequisites, alternatives, internal behavior, return format, edge cases (gaps[], contradictions[], semantic excerpts), pricing tiers, and latency. There is no output schema, but the description compensates by detailing the findings packet structure. Sibling tools are appropriately referenced for comparisons.

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 significant meaning beyond the schema: it explains that 'quick'=single hop, 'standard'=gap-recovery hop+contradictions scan, 'thorough'=paid, adds iterative hop, contradiction scan. It also clarifies that 'question' accepts broad multi-part queries and that decomposition is automatic. However, it does not mention the exact number of facets for each depth level in the description itself (schema covers this partially), preventing a 5.

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

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

The description clearly states a specific verb ('grounded multi-source research') and a specific resource ('Pipeworx's 1462 structured data sources'). It explicitly distinguishes this tool from the sibling 'ask_pipeworx' by contrasting it as one-call parallel research versus a single LLM call, and further distinguishes it from open-web search. This makes the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data'), when-not-to-use guidance ('for a single lookup use ask_pipeworx'), and when-to-avoid-with-alternative-sibling advice ('for breaking or colloquial current-news topics, prefer ask_pipeworx'). It also notes the account requirement and directs to 'ask_pipeworx' as a fallback if not signed in. This is comprehensive usage guidance.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: returns top-N tools with names, descriptions, and full schemas with examples; results are ready to call directly without a second lookup. 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 core purpose and packed with useful details. Every sentence contributes, though it is somewhat lengthy. Could be slightly more concise, but structure is logical.

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?

Without an output schema, the description fully explains what is returned (names, descriptions, full schemas) and the tool's role as an option set explorer. This is complete for the 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% with well-described parameters and aliases. The description adds minimal extra meaning beyond listing example queries and mentioning aliases, which is already in the schema. Baseline 3 is appropriate as schema handles the burden.

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

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

The description uses specific verbs (find, discover, browse, search) and a clear resource (tools). It enumerates many domains (SEC filings, FDA drugs, etc.) and distinguishes this tool from siblings by its role as the discovery gateway, not a data-fetching tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on when to use. It does not explicitly list alternatives or when not to use, but the context implies it is for exploratory lookup rather than direct data retrieval.

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

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

Adds value beyond annotations: explains multi-source fan-out, soft-fail for patents after May 2025, and specific return fields. No contradiction with annotations.

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

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

Front-loaded with examples, each sentence adds info. Slightly long but justifies length with comprehensive details. Could be slightly more 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?

Given complexity and no output schema, description thoroughly covers return fields (filings URIs, fundamentals, patents, news fallback, LEI) and limitations (patent sunset). Complete for holistic profile.

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%. Description adds practical usage details: ticker or zero-padded CIK, and clarifies that names are not supported, directing to resolve_entity.

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 'full cross-source profile of a US public company in ONE parallel call' with specific verb 'profile' and resource 'entity'. It distinguishes from siblings by preferring this over chaining single-pack lookups.

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

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

Explicitly tells when to use ('ALWAYS PREFER') and when not (names not supported, use resolve_entity first). Provides example queries and 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?

Description mentions deletion, aligning with destructiveHint=true in annotations. Adds context about clearing sensitive data, which is beyond the annotation. No contradictions with annotations.

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

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

Two sentences, no filler, front-loaded with action and use cases. Every sentence adds value.

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

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

Given the simple delete operation with one parameter, destructive and idempotent hints, and no output schema, the description is complete with usage guidance and pairing advice.

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 clear description for the 'key' parameter. The description adds little beyond 'Memory key to delete,' 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 explicitly states 'Delete a previously stored memory by key,' clearly identifying the action and resource. It also references sibling tools 'remember' and 'recall,' distinguishing this tool from them.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data). Suggests pairing with related tools, but does not explicitly state when not to use, warranting a 4 rather than 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by explaining the process: fetches the page, extracts title/description/key links, and emits standard markdown format. No contradictions; behavior is well-disclosed.

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

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

The description is two sentences, front-loaded with the core purpose and followed by use cases. It is efficient but could be slightly more concise; however, it earns its place without unnecessary verbosity.

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 output as a single text blob in standard llms.txt markdown format. Parameters are well-covered, and the tool's purpose and usage are fully described for a simple generation 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%, so the baseline is 3. The description reiterates purpose of parameters (extracting key links, controlling max links) but does not add significant new meaning beyond what the schema already provides. It mentions default and max values, but those are in the schema description as well.

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

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

The description clearly identifies the tool as generating a production-ready llms.txt file for any URL, with specific verbs ('generate', 'fetch', 'extract', 'emits') and resource (llms.txt file). It distinguishes from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check' by focusing on file generation rather than scanning or visibility checking.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It implies when to use this tool vs alternatives but does not explicitly state when not to use it or name alternative tools. However, the context from sibling tools helps guide selection.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds context about the returned data but does not disclose additional behavioral traits beyond what annotations cover.

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

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

The description is a single, front-loaded sentence with no wasted words, efficiently conveying the tool's 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 explains the return values (fields, geometry, count, capabilities) adequately. Annotations cover safety. Some missing details on error behavior, but overall complete.

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

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

Schema coverage is 100% and the description mentions 'by url', but it does not add significant meaning beyond what the schema description already provides for the url parameter.

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

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

The description clearly states the verb 'Get' and the resource 'an ArcGIS Feature/Map Service layer's schema', listing the specific information returned (fields, geometry type, record count, capabilities). This distinguishes it from siblings like query_layer or search_datasets.

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

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

The description implies usage for retrieving schema information but does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by specifying return fields (id, type, params, timestamps, fire_count), which is consistent and useful.

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 and return fields, then 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?

Tool is simple with one optional parameter. Description covers purpose, return fields, and usage context. No output schema needed given the clear listing of return fields.

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

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

Schema coverage is 100% with one parameter (include_inactive) described. Description does not add additional semantics beyond the schema, hence baseline 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?

Description explicitly states 'List the caller's active subscriptions' and lists return fields. Clearly differentiates 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 when-to-use guidance: 'review what you're monitoring before adding more or to find an id to cancel', covering both use cases and contrasting with 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 reveals the tool is free, rate-limited to 5 per identifier per day, doesn't count against tool-call quota, and that filing without an account returns a claim_token for later status checks. It also warns against pasting end-user prompts, a behavioral constraint not in annotations. Annotations are sparse, so the description carries the burden well.

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

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

The description is long but well-structured, front-loading purpose and usage, then moving to exclusions, token handling, and constraints. Every sentence provides distinct value (purpose, triggers, scope, message guidance, token behavior, roadmap impact, rate limits). Slightly verbose but not wasteful.

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

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

The tool has only 4 optional parameters, no output schema, and minimal annotations; the description covers all relevant operational aspects: when to use, what to include, how to follow up via claim_token, limitations, and context. It's complete for the 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?

The schema already documents all four parameters at 100% coverage. The description adds semantic guidance such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which enriches the message parameter, and explains the claim_token usage beyond the schema's description. This extra context justifies a score above the baseline.

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

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

The description uses a specific verb ('Tell the Pipeworx team') and explicitly names the resource (feedback about tools). It distinguishes from sibling tools by scoping to the Pipeworx connection and clarifying it's for bug reports, feature requests, and praise, while excluding tools from other MCP servers.

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

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

It explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: if the tool is from a different MCP server, file it there instead, and offers guidance on how to identify Pipeworx tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that data is derived from CF analytics-engine, no PII, and cached 5min-1h depending on window. This provides useful behavioral context beyond annotations.

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

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

The description is concise, front-loaded with the core purpose, followed by use cases and technical details. Every sentence adds value with no redundancy.

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

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

While the description covers purpose, use cases, and data source, it lacks details on the output format (e.g., structure of 'top tools' and 'top packs'). Without an output schema, the agent may need to infer the return shape from the description, which is not fully specified.

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

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

The schema covers the 'window' parameter with enum and description. The description adds further nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing agent understanding.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window. It uses specific verbs and resources, and the sibling context shows it is distinct from other tools like 'ask_pipeworx' or 'discover_tools'.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, seeing alignment). No when-not-to-use or alternative tools are mentioned, but the sibling list implicitly offers alternatives for other tasks.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: the fill check (realizable_edge_pp ≤ 0 means no trade), placeholder filter, Jaccard similarity threshold, and response structure. This adds value beyond annotations without contradiction.

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

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

The description is informative but quite verbose, with multiple paragraphs and detailed technical explanations. While structured well, it could be more concise for faster AI parsing. Every sentence adds value, but some details might be streamlined.

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 modes, fill check, edge cases), the description covers all necessary aspects: input modes, response fields (opportunities, partition_check, fill_check), and constraints (placeholder filter, similarity threshold). No output schema exists, so the description compensates effectively.

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

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

Schema coverage is 100%, but the description enriches both parameters: for event it explains date-axis/threshold-axis ordering and partition_check; for topic it adds Jaccard similarity and cross-event merging. This adds meaning beyond the schema descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains each, differentiating it from sibling tools like polymarket_edges.

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

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

The description explicitly says when to use each argument: no args for trending scan, event for specific market, topic for cross-event scan. It also explains why cross-event mode catches patterns single-event misses. It lacks explicit 'when not to use' but provides clear context.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive, which the description aligns with. The description adds valuable behavioral details: it explains the five model families, three response segments, caching at 1h, diagnostics to explain empty segments, and the 24h-move warning. No contradictions with annotations.

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

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

The description is long but well-structured and front-loaded with the core purpose. Each sentence adds value, explaining model families, response fields, tradeable-edge knobs, and caching. Given the complexity (5 model families, 9 parameters), the length is justified. It could be slightly more concise, but it remains clear and organized.

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

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

Given the complexity of the tool (multiple segments, diagnostics, tradeable-edge knobs, nested response fields) and no output schema, the description is extremely complete. It explains what each segment contains, how edge_pp_net and Kelly fractions work, why certain segments might be empty, and what diagnostics reveal. This allows agents to fully understand the tool without additional information.

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 every parameter already has a description in the input schema. The tool description adds context about the model families and the overall usage of knobs but does not provide new semantic information for individual parameters beyond what the schema already offers. The baseline of 3 is appropriate as the description reinforces but does not significantly extend parameter understanding.

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

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

The description clearly states the verb ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and resource, and distinguishes from sibling tools by focusing on disagreement discovery. It is built for 'what should I bet on today' and explicitly says agents discover opportunities without paging hundreds of markets, which sets it apart.

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

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

The description provides clear context for when to use (discovering opportunities based on model-driven signals and structural arbitrage) and includes tradeable-edge knobs for filtering. However, it does not explicitly mention when not to use this tool or point to alternative sibling tools like polymarket_arbitrage or polymarket_edge_tracker. The provided guidance is sufficient but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context beyond annotations: explains data sources (daily snapshots), output structure (tracked, expired, snapshot_dates), caveats (decay from daily closes, not intraday), and limitations (60-day TTL, gaps from no scans). 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 information-dense but well-structured: opens with a clear purpose, then details output fields and limitations. It is longer than ideal but every sentence adds value. Could integrate the RESPONSE section more smoothly, but overall efficient.

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

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

Given no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and key fields within each. It also covers limitations (60-day TTL, snapshot gaps). For a tool with 2 optional parameters, the description leaves no significant gaps in understanding what the tool does and what it returns.

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

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

Schema coverage is 100% with both parameters already described. The description repeats defaults and clamp values (days: default 14, clamp 2-30; window: default '1wk') but adds little new meaning beyond the schema. For example, it clarifies that 'days' is lookback and 'window' refers to snapshot family, but the schema already indicates that.

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, answering a specific question: 'how long has this edge existed and is it shrinking?'. It uses specific verb+resource ('edge persistence and decay telemetry') and distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical trends rather than current edges.

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

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

The description implies a use case ('a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when to use this tool versus alternatives like polymarket_edges. There is no mention of when not to use it or direct comparison to siblings, leaving some ambiguity for the agent.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds: REQUIRES one of 'market' or 'event', explains return fields for each mode, and warns about forced directional risk. No contradiction; the description enriches behavioral understanding beyond annotations.

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

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

The description is well-structured with uppercase cues for modes and required parameters, but it is relatively long. Every sentence adds value, though some repetition could be trimmed. Still, it remains clear and organized.

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, so the description fully covers return values: lists fields for both single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket modes (theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk). It also explains the verdict and risk of unhedged positions, making the tool's behavior completely understood.

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

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

Schema coverage is 100%, but description adds significant meaning: explains dual modes, default values, interpretations of 'size_usd' for single-market vs basket mode, and the 'side' parameter's auto-detection in basket mode. This goes well beyond the schema's brief property 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 checks 'realizable-vs-theoretical edge' against live CLOB order-book depth, distinguishing single-market and basket modes. It uses specific verbs ('check', 'returns') and resource ('edge against order-book depth'), and differentiates from sibling tools like 'polymarket_arbitrage' and 'polymarket_edges'.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about risks of partial fills converting arb into unhedged positions, providing clear context for usage.

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. Description adds rich behavioral detail: compatibility_warning scenarios, temporal_alignment field, skipped_cross_type/subtype counters. 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?

Well-structured with clear sections (modes, response, safety fields). Some repetition (e.g., 'Real cross-venue spreads are rarer...' could be trimmed), but overall efficient and front-loaded.

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

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

With no output schema, the description thoroughly explains response format (leg-by-leg prices, matched spreads, top_spreads_pp) and covers edge cases (compatibility warnings, temporal misalignment). Complete for a read-only comparison tool.

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

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

Schema coverage is 100% with examples, but description adds value by explaining the difference between topic shortcuts and explicit tickers, including the full list of topics and override behavior.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison and explicit safety fields.

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

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

Explicitly describes when to use topic mode vs explicit pairing, warns that most pre-mapped topics return compatibility_warning, and explains that only equivalent bet shapes produce meaningful spreads.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns 'attribute rows (and geometry)', which provides extra context beyond annotations but does not cover auth, rate limits, or other behavioral traits.

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

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

The description is two sentences: the first states purpose and lists parameters, the second offers a usage tip. No wasted words, front-loaded with essential information. Exemplary conciseness.

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

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

Given the rich schema (100% coverage) and annotations (safety profile), the description adds return type details and workflow context (url from search_datasets). It misses pagination limit specifics, but schema fills that gap. Overall, well-balanced.

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

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

Schema description coverage is 100%, with each parameter described. The description summarizes parameters (e.g., 'SQL-like where, comma-separated out_fields') but adds no additional semantic meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool queries ArcGIS Feature/Map Service layers by URL and lists parameters. It mentions the source (from search_datasets) but does not explicitly differentiate from sibling tools like layer_info, which might retrieve metadata. Hence, it's clear but not fully distinguishing.

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?

Includes a practical tip on sampling with 'where="1=1" + out_fields="*"', implying when to use it. However, no explicit guidance on when not to use it or alternatives, leaving room for ambiguity in complex workflows.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and 'without re-deriving it from scratch', which goes beyond annotations without contradiction.

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

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

The description is concise at three sentences, with the primary action front-loaded ('Retrieve...'). Every sentence adds value, and there is no wasted wording.

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 single parameter, no output schema, and rich annotations, the description is complete. It covers the tool's purpose, variations, scope, and relationships with siblings, leaving no critical gaps.

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

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

Schema coverage is 100% with description for the 'key' parameter. The description adds meaning by explaining the optionality and effect of omitting key ('Retrieve a value... or list all saved keys (omit the key argument)'), enhancing the schema's lone 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 'Retrieve a value previously saved via remember, or list all saved keys', specifying the verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools like remember and forget.

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

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

The description explains when to use the tool: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also tells when to omit key and suggests pairing with remember/forget, though it lacks explicit 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 indicate safe read-only, idempotent behavior. Description adds behavioral nuance: explains that setting mark_read:true flags events read to hide them on subsequent calls, and describes return fields. No contradictions.

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

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

The description is concise at 4 sentences, front-loaded with the main purpose, then details parameters, then provides a usage note. Every sentence adds value; no wordiness.

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 covers return fields (source, citation_uri, raw payload) and polling behavior. With 5 optional parameters all described, the tool is fully specified for correct invocation.

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

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

Schema covers all 5 parameters with descriptions. The description enriches by giving a concrete example for type ('sec_8k'), clarifying that since expects an ISO timestamp, and explaining the effect of mark_read (so next call shows only newer ones).

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 the subscription feed and returns recent alerts with source, citation_uri, and raw event payload. It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on fired events specifically.

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 polling as suitable and notes the same feed is available via GET endpoint for scripts/dashboards. While it provides context for usage, it lacks explicit when-not-to-use guidance or direct comparisons to 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 indicate safe, idempotent read operation. The description adds specifics: fans out to multiple sources, soft-fails on USPTO, and returns structured changes with citations, exceeding annotation requirements.

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 well-structured paragraph front-loaded with usage examples, efficient use of language covering all key aspects 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?

Covers multiple data sources, return format (changes[], total_changes, URIs), and soft-fail behavior. Minor gap: could mention error handling or rate limits beyond GDELT→GNews fallback, but sufficient for agent use.

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

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

Schema coverage is 100% with descriptions, and the description adds valuable context: since examples ('7d', '30d', '3m', '1y'), value as ticker or CIK, and type limited to 'company'.

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

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

The description clearly states it provides a change feed for a company from SEC EDGAR, GDELT/GNews, and USPTO, and explicitly distinguishes from entity_profile for static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X', 'latest on Y') and when-not-to-use (use entity_profile instead for static profile), plus fallback behavior for GDELT→GNews.

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 (idempotentHint=true, destructiveHint=false), the description adds behavioral details: scoping by identifier, persistent vs 24-hour retention, and storage as key-value pair. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, then usage, then behavior, then companions. No redundancy, 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?

Covers purpose, when, how, and companion tools. Lacks mention of return value or behavior on duplicate keys, but given idempotentHint and simplicity, it is nearly complete.

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

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

Schema coverage is 100% with good descriptions for key and value. The description adds context and examples but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides specific examples (resolved ticker, target address, user preference). It distinguishes from siblings by mentioning companion tools recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Also directs to pair with recall and forget for retrieval and deletion, providing clear 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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds important behavioral traits: internal cascading through multiple endpoints, graceful degradation (returns EDGAR even if GLEIF/OpenFIGI unavailable), and explicit listing of unresolved identifiers under 'unresolved'. 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 front-loaded with examples and a core directive, then details the supported types and enrichment behavior. While slightly long, every sentence adds informational value—no filler. Efficient for the complexity covered.

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 fully explains return values: CIK, ticker, company_name, LEI, FIGI for company; RxCUI, ingredient, brand for drug; plus unresolved identifier handling. This is complete given the tool's multi-source complexity and one-to-many resolution behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining accepted input formats in context (e.g., ISIN resolves to legal entity via GLEIF, drug accepts brand or generic), and details the resolution chain for each parameter type. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples like 'What's the ticker for…' and explicit differentiation from siblings (e.g., 'compare_entities', 'entity_profile'). It identifies the core action—name-to-ID mapping—and the resource (identifiers across company/drug types).

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

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

The description gives explicit usage cues: 'Use FIRST whenever you have a name but need an ID' and lists supported query patterns. It does not explicitly state when NOT to use it (e.g., if an ID is already known), but the context is clear enough for correct selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized, including output details (score, confidence, signal density). No contradictions.

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

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

Description is 4-5 sentences, front-loaded with main purpose, and every sentence adds value. No redundancy. Efficiently communicates what the tool does and its output.

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

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

No output schema, but the description explains the return format (ranked list with score, confidence, signal density). It also clarifies internal use of ai_visibility_check, which is sufficient given the tool's simplicity.

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

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

Input schema has 100% coverage with descriptions, so baseline is 3. The description adds extra meaning: first entity is treated as 'subject' for narrative, rest as competitors. This enhances 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, specifying it probes each entity with ai_visibility_check and returns a ranked list. Differentiates from single-entity check by emphasizing multi-entity comparison, and the example question clarifies the use case.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and provides an example question. However, it does not explicitly state when not to use this tool or mention alternative tools (e.g., ai_visibility_check for single entities).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement on a new version can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

Description is front-loaded with core purpose, then details. Slightly verbose (multiple clauses) but each part adds value. Could be tightened by removing a few redundancies (e.g., 'in ONE call' already implied). Overall well-structured for an AI agent.

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

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

Despite no output schema, description fully specifies return structure: summary block (fields listed), per-advisory detail, links, alternative versions, and partial failure info. Covers error scenarios gracefully. Complete for decision-making 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?

Input schema covers 100% parameters with descriptions. Description adds nuance: 'Scoped packages (e.g. "@types/node") are accepted' and clarifies version defaulting behavior ('Defaults to the latest published version when omitted'). This provides extra guidance 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 it's a composite check for npm packages combining deps.dev and bundlephobia, with specific context ('should I add this npm package to my project'). It distinguishes scope from siblings by noting NPM-only in v1 and directing other ecosystems elsewhere.

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

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

Explicitly states use cases: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', offering clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the description does not need to reiterate safety. It adds value by detailing the return fields (name, summary, record_count, owner/org, url) and the purpose of the url (to pass to query_layer/layer_info). 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 two sentences long, immediate front-loading the purpose and then specifying the return format and follow-up use. Every sentence is informative and concise 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?

Despite no output schema, the description clearly enumerates return fields (name, summary, record_count, owner/org, url) and explains how to use the url. This is fully sufficient for an agent to invoke and consume results. The connection to sibling tools (query_layer/layer_info) completes the workflow context.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning for parameters, but it clarifies the role of org_id as optional to override default organization. This is a small but useful addition.

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 specific verbs and resources: 'Search Sarpy County GIS open geospatial datasets...by keyword.' It lists examples of datasets (parcels, addresses, zoning) and explicitly states what each result contains (name, summary, record_count, owner/org, url). This clearly distinguishes it from sibling tools like query_layer or layer_info.

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 names the next step: 'pass that url to query_layer / layer_info.' This provides clear usage context. However, it does not explicitly state when not to use this tool or compare it to alternatives beyond referencing downstream tools. It implies usage for dataset discovery, which is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. This provides rich behavioral context beyond annotations.

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

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

The description is concise: first sentence states purpose, second gives usage guidance, last sentence provides technical caps. No wasted words, well-structured, and front-loaded with key information.

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

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

Despite no output schema, the description explains return values (passages with offsets and similarity scores). It covers usage context, behavioral details, parameter semantics, and constraints. For a 3-param tool, it is fully complete and leaves no gaps.

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

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

Schema coverage is 100%, but description adds value: examples of natural-language queries ('supply-chain risk'), clarifies max chars for 'text', and explains default for 'limit'. This helps the agent use parameters effectively beyond schema definitions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies inputs (text, query) and outputs (top-N passages with character offsets and similarity scores). It distinguishes from sibling tool 'ask_pipeworx_grounded' by explaining the pairing strategy.

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

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

The description explicitly tells when to use: when a record is too big for the prompt, to save context, and to get only relevant passages. It also mentions pairing with ask_pipeworx_grounded. It does not explicitly say when not to use, but the guidance is clear enough.

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

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

Annotations already indicate no destructive behavior and idempotency, but the description adds crucial behavioral details: OAuth requirement, subscription id return, webhook HMAC signing, auto-disable after 10 failures, and SMS 10/day cap. No contradictions with annotations.

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

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

The description is well-structured and concise. It front-loads the core purpose, then systematically covers types and delivery channels. Every sentence provides unique information without redundancy.

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

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

Given the tool's complexity (multiple subscriptions types, delivery channels, and security details), the description fully covers prerequisites, type-specific parameters, delivery options, and limitations. No output schema exists, but the description notes the returned subscription id.

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, but the description adds significant value beyond the schema by detailing type-specific params examples (e.g., items for sec_8k, topic for polymarket_edge) and delivery constraints (phone verification, webhook signing secret).

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions returning the subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies when to use (proactive monitoring), requires a Pipeworx OAuth account, and gives examples of types and delivery channels. It does not explicitly mention alternatives or when not to use, but provides sufficient 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 readOnly, openWorld, and idempotent hints. The description adds valuable behavioral context: it's a discovery tool that returns example questions with exact tool+argument shapes from the live catalog. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads common queries but could benefit from more structured formatting (e.g., bullets) for readability. Still, every sentence adds value.

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

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

Given no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes). Parameter semantics and usage are well-covered, making the description complete for this simple tool.

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

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

Schema coverage is 100% with one optional parameter. The description adds significant meaning beyond the schema by explaining the effect of omitting vs. providing a topic, and listing example topic values.

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 specific verbs like 'onboarding entry point', 'what can I ask', and 'getting started', clearly identifying the tool's role in helping new users discover Pipeworx capabilities. It distinguishes from sibling tools by focusing on exploration rather than specific actions.

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

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

The description explicitly advises using this tool first when unsure of Pipeworx's capabilities and to learn meta-tool usage. It covers when to call with no arguments vs. a topic, though it lacks explicit 'when not to use' guidance 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 indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds that the row is deactivated, not deleted, and historical events remain available via recent_alerts. No contradiction.

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

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

Two concise sentences, front-loaded with main action, no redundant information.

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

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

Complete for a simple one-parameter tool with good annotations. Covers purpose, constraints, and post-action effects.

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?

Single parameter 'id' has schema description. Description adds context about ownership but does not significantly enhance schema coverage (100%). 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?

Clearly states 'Cancel a subscription by id' with specific verb 'cancel' and resource 'subscription'. Differentiates 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?

Explicitly states ownership enforcement ('only cancel your own subscriptions'), providing clear context on when to use. No explicit alternatives mentioned, but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds substantial beyond-annotation context: the dual processing paths (company-financial vs any other), the full verdict vocabulary, and the critical semantic distinction between could_not_verify (pipeline failure, not evidence) and unsupported (no source exists). It also specifies that claims are answered with verbatim evidence and a pipeworx:// citation, which is valuable behavioral disclosure.

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 fairly dense but well-structured. Every sentence carries useful information: trigger phrases, routing logic, verdict types, edge-case semantics, and efficiency. There is minor redundancy in restating the purpose, but overall it is appropriately sized for the tool's complexity.

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

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

For a complex verification tool with no output schema, the description is comprehensive. It covers verdict values, evidence/citation behavior, error semantics for could_not_verify and unsupported, and the two execution paths. It gives callers the full picture needed to interpret results and handle edge cases 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%, with both 'claim' and 'tolerance_pct' already thoroughly documented (including default behavior and usage examples). The description itself adds no new parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as claim verification against authoritative sources, with concrete trigger phrases and a specific verb ('validate'/'verify'). It distinguishes itself from sibling research/search tools by focusing on fact-checking a user's statement rather than open-ended research or entity lookup.

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

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

Explicitly states when to use it: 'whenever the agent needs to check whether something a user said is factually correct.' It also outlines two distinct routing paths (SEC EDGAR fast path vs grounded pipeline) and notes it replaces 4–6 sequential calls, implying the alternative. It does not explicitly name sibling tools to exclude, but the context is clear enough for an agent to select it appropriately.

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