Arcgis Sanbernardino

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe, non-destructive, idempotent reads. The description adds valuable context: it details per-model and combined output structure, notes that Anthropic probing requires a BYO key with direct payment to Anthropic, and clarifies that the default model is free. 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 compact (two sentences) and front-loaded with the primary action and outcome. Every sentence adds value: first sentence defines the tool, second sentence adds model details 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?

Despite no output schema, the description sufficiently details the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). Parameters are fully covered. Use cases are provided. Given the tool's moderate complexity and rich description, it is complete for effective usage.

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

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

Schema description coverage is 100% with all four parameters described. The description adds meaning beyond the schema: it gives concrete examples for 'entity' (e.g., 'Pipeworx'), explains 'models' defaults and supported values, clarifies '_apiKey' as a passthrough, and describes 'context' as disambiguation aid. This significantly aids 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 a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic') and indicates the output ('score visibility (0-100) per model'). It distinguishes from sibling tools by focusing on AI visibility scoring across multiple models, with specific mention of default and paid model options.

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 contexts where the tool is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), offering clear guidance on when to use it. However, it does not explicitly mention when not to use it or name alternative sibling tools for different purposes, which would strengthen the guidelines.

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 explains it routes queries, fills arguments, and returns citations (pipeworx://), which adds value beyond annotations. Annotations already indicate readOnly, openWorld, and idempotent, but description elaborates on the multi-source routing behavior. No contradictions.

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

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

The description is front-loaded with a strong preference statement, then lists supported domains, usage examples, and exit criteria. It is slightly long but each sentence is informative. Could trim the list of domains slightly, but overall well-structured.

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

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

Given the tool's broad scope (many sources) and no output schema, the description comprehensively explains coverage, use cases, alternatives, and limitations. It provides enough context for an agent to decide when to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add detail about the question parameter beyond what the schema provides, but the schema itself gives aliases and examples, which is sufficient. No additional semantic value in description.

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

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

The description clearly states the tool routes questions to the correct source among thousands, returning authoritative structured data with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by specifying its scope and typical use cases.

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

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

Explicit guidance on when to prefer this tool over web search, and when to step up to alternatives (ask_pipeworx_grounded, deep_research). Provides concrete query examples and types of questions that are appropriate.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the beta nature, that results are compared against the stable router to decide merges, and that it falls back to nothing (full working router). The description is consistent 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 that are well-structured and front-loaded with the core purpose. The first sentence establishes identity and equivalence, the second provides usage context. Concise but not at the expense of clarity.

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

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

Given the high parameter count (6) covered by schema, rich annotations, and no output schema, the description adequately covers the beta nature and fallback behavior. It explains the experimental purpose and current inactive state, which is sufficient context for selecting this tool.

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

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

Schema coverage is 100% with all 6 parameters documented as aliases for 'question'. The description does not add meaning beyond the schema for the parameters, 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?

Description clearly identifies it as the beta version of ask_pipeworx with the exact same toolset and behavior. It states it is a 'universal router' with 5,564 tools and identical arguments, differentiating it from the stable sibling ask_pipeworx.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison purpose with the stable router. It also warns that no candidate is currently active, so behavior matches ask_pipeworx, providing clear when-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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral context: the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), the extra LLM call cost, and the fact that answers are extracted only from tool results. It does not contradict annotations. Minor deduction for not detailing what happens on timeout or partial results beyond 'data_truncated'.

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 in a single paragraph, front-loading the core value proposition. Every sentence adds value except perhaps the list of aliases, which could be inferred from the schema. It earns a 4 for being information-dense but could benefit from minor structural breaks (e.g., bullet points for refusal reasons) for easier scanning.

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 (5,564 tools, 1462 sources, multi-step pipeline), the description covers all essential aspects: purpose, usage trade-offs, refusal reasons, and cost implications. There is no output schema, but the description explicitly details the return object structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and error states, making it complete for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description exceeds baseline by explaining that the question is processed through a multi-step pipeline (picking tools, fetching data, extracting answer), which adds context about how the parameter is used. However, it doesn't describe the expected format or length of the question. A 4 is appropriate for the added pipeline context.

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

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

The description clearly identifies this as 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling tool 'ask_pipeworx' by specifying the grounded extraction behavior. The verb 'ask' combined with 'grounded' and the explanation of the refusal mechanism make the purpose precise and distinct.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives clear examples of high-stakes domains (financial, legal, medical, public statements) and advises preferring 'ask_pipeworx for casual lookups' along with a cost trade-off. This provides excellent guidance on alternatives and exclusions.

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

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

The description goes well beyond annotations (readOnlyHint: true, etc.) by detailing market resolution, classification, fan-out, evidence packet, resolver contract, parent event extraction, news fallback handling, safety checks for low-confidence matches, closed markets, wide spreads, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but uses headings (e.g., CLASSIFIERS, FAN-OUT EXAMPLES) to structure content. Each section adds value, but some parts are verbose. It strikes a balance between completeness and conciseness, earning a 3.

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 must explain return values. It thoroughly covers market fields, analysis block, evidence, resolver contract, parent event, news fields, safety checks, and resolution-rule risk. Edge cases like closed markets, low-confidence matches, and wide spreads are addressed, making it complete for a complex tool.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds valuable context: depth parameter explained as quick vs thorough, market parameter examples, include_raw default false and reasoning. This adds moderate value beyond schema, justifying a 4.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It provides specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes from siblings like polymarket_edges by being a comprehensive research 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?

The description explains acceptable inputs (slug, URL, question text), when to use it for betting decisions, and gives fan-out examples by category. It does not explicitly state when not to use it, but the context implies it's for pre-bet research, and alternatives like polymarket_edges are implied.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already present, but description adds: parallel call handling, off-calendar fiscal year logic, sorted results, citation URIs. 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 moderately concise with front-loaded triggers and useful details. Could be more structured (e.g., bulleted lists) but each 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 both entity types, what data is returned (paired data + citation URIs), and sorts results. No output schema exists, but description fully informs agent of expected results.

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

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

Schema coverage 100% with parameter descriptions. Description adds context: tickers/CIKs for company, drug names for values, and clarifies 2-5 count. Examples enhance clarity beyond schema.

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

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

Description begins with clear natural-language triggers ('Compare X and Y', 'which is bigger') and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It differentiates from sequential lookups and details data sources per type.

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 (comparison queries) and when-not-to ('ALWAYS PREFER over sequential single-pack lookups'). Contrasts with sibling tool 'entity_profile' and other single-entity tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description significantly adds context: account requirements, parallel execution internals, gap recovery behavior, hop fields, contradictions array, semantic excerpting, citation stability rules, and expected latency per depth. 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 excessively long with many parenthetical asides and run-on clauses. It front-loads important content (account requirement, alternative) but later details like hop field, citation URI stability, and semantic excerpting are buried. Every sentence is earned in terms of content, but the lack of paragraph breaks or scannable structure makes it hard to digest.

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 parameters, no output schema, 1462 data sources, variable depth behavior), the description covers request behavior, constraints, output structure (findings packet with evidence/confidence/source/citation_uri/gaps/contradictions), latency expectations, and edge cases (empty gaps for non-structured topics). It is remarkably complete despite lacking a formal output schema.

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

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

Schema description coverage is 100% (both parameters documented). The description adds substantial context beyond schema: the 'question' parameter semantics for multi-part queries and decomposition; the 'depth' parameter gains behavioral details (parallel count, gap recovery, contradictions) not present in schema enum descriptions. Slight deduction because the schema already does a good job, but the description still adds meaningful nuance.

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

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

The description explicitly states the verb 'research' with a specific resource: 'Pipeworx's 1462 STRUCTURED data sources'. It clearly distinguishes itself from siblings by naming alternatives (ask_pipeworx) and describing the parallel decomposition approach, making it highly discriminable.

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 (broad/multi-part questions over structured data), when-not-to-use (breaking news, colloquial current-news), and named alternatives (ask_pipeworx for single lookups or news). It also includes account tier constraints and depth-specific behavior.

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, destructiveHint=false, and idempotentHint=true. The description adds valuable context beyond annotations: it returns top-N tools with full schemas and curated examples, and states each result is 'ready to call directly, no second schema lookup needed.' This enhances understanding of the tool's behavior without contradicting annotations.

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

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

The description is a single paragraph of 5 sentences, front-loaded with the main purpose. Every sentence serves a distinct role: overall function, usage context, domain examples, return format, and strategic guidance. There is no wasted text, and it remains concise yet comprehensive.

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

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

Given the tool's simplicity (discovery tool with a single required string parameter and optional limit), the description covers all necessary aspects: what it does, when to use it, what it returns (top-N tools with schemas and examples), and its reusability. Annotations cover safety and idempotency. No output schema is needed because the return format is described in words.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter-specific meaning beyond what the schema already provides, though it clarifies that multiple aliases (q, task, search, description) exist for the same query parameter. The schema descriptions are sufficient, so the description adds marginal value.

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 starts with 'Find tools by describing the data or task,' clearly stating the verb (find/discover) and resource (tools). It lists numerous domains (SEC filings, financials, etc.) and distinguishes from sibling tools by positioning itself as the tool to discover other tools, making the purpose unambiguous.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides specific use cases: 'when you need to browse, search, look up, or discover what tools exist for: ...' This gives clear guidance on when to use the tool and implies it should be used before other tools for exploration.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds detailed behavioral context: fans out across multiple data sources, returns specific fields (cik, filings, fundamentals, patents, news, LEI), and notes that patent data soft-fails until reactivated. 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 detailed with a list of returned fields and example queries. While somewhat long, each sentence adds value. Well-structured with a clear use case and constraints. Slightly verbose but efficient for the information conveyed.

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

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

No output schema, but description comprehensively lists all returned data (CIK, filings with URIs, fundamentals sorted by period, patents with status, news via fallback, LEI). Covers edge cases (patent soft-fail, name unsupported). For a 2-parameter tool with rich output, the description is complete and sufficient.

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

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

Schema covers both parameters with descriptions (type enum 'company', value as ticker or CIK). Description reinforces these details and adds examples, but does not significantly extend meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

Description clearly states it provides a full cross-source profile of US public companies in one parallel call, with specific examples (e.g., 'Tell me about X', 'research Acme'). It distinguishes from siblings like compare_entities or resolve_entity by focusing on holistic single-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 advises to prefer over chaining single-pack lookups, specifies when not to use (names not supported, requiring resolve_entity first), and provides example invocations. This gives clear guidance on when and how to use the tool.

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

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

Annotations already mark destructiveHint=true; description adds context about clearing sensitive data, adding value beyond annotations with no contradiction.

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

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

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

For a simple tool with one required param and no output schema, the description fully covers purpose, usage context, and pairing, leaving 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% and description adds 'by key' which repeats the schema's 'Memory key to delete'; baseline 3 applies with no extra meaning.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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

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

Provides explicit context for when to use (stale context, task done, clear sensitive data) and pairs with remember/recall, but does not explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by outlining the process: fetching the page, extracting title/description/key links, and emitting standard llms.txt format. This confirms the read-only, information-gathering nature beyond the annotations.

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

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

The description is concise, consisting of three sentences that front-load the primary purpose, then describe the process, and finally list use cases. While efficient, it could be more structurally organized with bullet points for readability, but it earns its sentences.

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

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

Given the low complexity (2 parameters, 1 required) and the presence of informative annotations, the description covers the tool's purpose, process, and output format ('single text blob'). Without an output schema, the description adequately explains the return value, making the tool contextually complete.

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

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

Both parameters have detailed descriptions in the schema (url and max_links), achieving 100% coverage. The description does not add new semantic information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL. It specifies the verb 'Generate', the resource 'llms.txt file', and the context for AI crawlers. The specific use cases provided (client's site, own project, competitor audit) add clarity and distinguish it from siblings.

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 useful scenarios for the tool, guiding agents on when to employ it. However, it does not mention when not to use it or suggest alternative tools for related tasks, which would be beneficial for exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about what is returned (fields, geometry, count, capabilities) but does not contradict annotations. A score of 3 is appropriate as annotations cover safety, and description adds some value.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and outputs. 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?

For a simple tool with one parameter and rich annotations, the description adequately covers the return values. Minor missing details like error handling or versioning, but not critical for this tool.

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

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

Schema description coverage is 100% with one parameter 'url' having a clear description and example. The description does not add additional meaning beyond the schema, so baseline 3 is warranted.

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 verb 'Get' and resource 'ArcGIS Feature/Map Service layer's schema', listing exact outputs (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like 'query_layer' which queries data.

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 'by url' but does not explicitly state when to use this tool versus alternatives. It implies usage for schema retrieval, but lacks when-not-to-use or alternative recommendations.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds value by specifying return fields and the effect of the 'include_inactive' parameter (including cancelled subscriptions). No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the action and return fields. No unnecessary words or redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers its behavior, return data, and usage purpose. No gaps identified.

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

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

Schema coverage is 100% with a description for the single boolean parameter. The description restates the parameter's effect but adds little beyond the schema. 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 lists the caller's active subscriptions and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings 'subscribe' and 'unsubscribe' through usage guidance.

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 the agent when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicit alternatives (subscribe, unsubscribe).

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

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

The annotations only indicate readOnlyHint=false and other false hints, but the description adds rich behavioral context: rate-limited to 5 per identifier per day, free and does not count against quota, returns a claim_token when filed without an account, supports later follow-up with that token, and the team reads digests daily. No contradiction with annotations exists.

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

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

The description is longer than average but every sentence earns its place. It is logically structured: purpose, when to use, when not to use, disambiguation, content guidance, workflow, rate limits, and cost. There is no filler or repetition, and the most critical information is front-loaded.

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

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

Despite having no output schema, the description covers what the caller can expect (claim_token on filing, status on follow-up), the constraints (rate limit, scope, quota), and the appropriate content of the message. For a feedback-reporting tool with nuanced scope rules, this description is fully complete.

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

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

Although schema-description coverage is 100%, the description adds meaning beyond the schema: it explains the claim_token round-trip workflow (filing returns a token; pass it back later to read status), instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and clarifies the message field's expected specificity. This goes well beyond the raw parameter descriptions.

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

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

The description opens with a specific verb and resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates concrete feedback categories (bug, feature/data_gap, praise). It clearly distinguishes this tool from sibling research and query tools by framing it as feedback to the Pipeworx team rather than a data retrieval action.

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

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

The description provides explicit 'Use when' triggers (wrong/stale data, missing tool in catalog, praise) and an explicit exclusion ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It also gives a disambiguation rule ('Pipeworx tool names are the ones this connection lists'), making it unmistakable when to invoke this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). No contradictions.

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

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

The description is concise: two sentences plus a bullet list of use cases. Every sentence provides essential information without repetition. Front-loaded with the main purpose.

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

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

For a tool with 1 optional parameter and no output schema, the description covers returns, use cases, caching, data source, and privacy. It is fully self-contained and leaves no major gaps for an agent to misunderstand.

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 the window parameter with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose appropriately beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, specifying the verb 'returns' and the resource 'trending on Pipeworx'. It distinguishes from sibling tools like ask_pipeworx that answer questions, not provide trending data.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking use case alignment) and explains the window options. It implies when to use without explicit exclusions, but the guidance is clear enough for an 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 declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds extensive behavioral context: how the scan works, semantic anchor, Jaccard similarity, placeholder filtering, fill check, and response structure. There is 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 long but well-organized, starting with core purpose, then detailing modes, filters, and response. It uses clear separators and each section adds value. Minor redundancy in explaining modes, but overall concise for the complexity.

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

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

Given the tool's complexity (arbitrage detection with multiple modes, detailed logic), the description is thorough. It explains the algorithm, parameters, response fields, and even mentions related tool for custom sizing. No output schema exists, but the description covers response structure adequately.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning beyond the schema: it explains each mode, provides example inputs, and gives usage recommendations. Agents can understand exactly how to use event and topic parameters.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and explains each. The purpose is specific and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode ('Call with NO args for trending_scan', 'event recommended for a specific market', 'topic for cross-event scanning'). It does not explicitly state when not to use this tool versus alternatives, but the sibling tool list is provided. The guidance is clear and practical.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: caching (1h at KV level), diagnostics (funnel counters, filter skips), edge calculation details (slippage, Kelly caps, move warnings), and response structure. 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, front-loaded with purpose and segments. Each section (models, response, knobs, diagnostics) adds value, but some details (e.g., exact model parameters in MODEL_DRIVEN) could be more concise. Overall, it's dense but organized, earning a 4.

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 (9 parameters, no output schema), the description is remarkably complete. It covers all segments, all knobs, response structure (by_segment, diagnostics), edge cases (empty segments, Fed bets exclusion), and even explains why certain filters exist. Nothing appears missing.

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

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

All 9 parameters are described in the input schema (100% coverage). The description adds significant context beyond schema: e.g., slippage_pp explains typical bid/ask costs, min_kelly explains filtering logic, max_spread_pp and min_liquidity are 'tradeable-edge filters', category_filter explains segment strings. This enriches 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the intended use case: 'Built for "what should I bet on today"' and distinguishes from siblings by detailing unique segments (model_driven, structural_arbitrage, concentrated_longshot) and knobs, making it clear this is a comprehensive edge-finding 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?

The description explains when to use the tool ('agents discover opportunities without paging hundreds of markets') but does not explicitly state when not to use it or provide alternatives. However, the sibling context implies alternatives like polymarket_arbitrage for specific arbitrage scans, but this is not stated explicitly.

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

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

Beyond annotations (readOnly, idempotent), description details snapshot gaps, TTL, computation methods, and response structure, fully disclosing 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?

Description is well-structured with purpose upfront, followed by response fields and limits. Slight verbosity in some details but overall efficient and clear.

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

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

No output schema exists, so description fully explains return fields (tracked, expired, snapshot_dates) and computational limits, making it self-contained for agent understanding.

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

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

Both parameters are fully described in the schema (100% coverage). Description adds minor context but does not significantly extend beyond schema defaults and clamping limits.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, distinguishing it from sibling polymarket_edges by focusing on time-series and trend analysis.

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

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

Description explains when to use the tool (to know edge duration and decay) and hints at alternatives (raw edges from polymarket_edges). However, it does not explicitly state when not to use or provide exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive hints. The description adds value by detailing that the tool walks the order book ladder, returns specific fields (e.g., top_of_book, vwap_fill_price, slippage_pp), and explains the verdict categories. It also warns that partial basket fills can convert an arb into an unhedged directional position. 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 dense and verbose, containing multiple sentences and sections. While it is well-structured with bold section headers and front-loaded purpose, some sentences are complex and could be tightened. It earns its place but could be 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 there is no output schema, the description compensates by listing returned fields (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict). It covers both modes, explains default values, and highlights risk. However, it lacks details on error handling or edge cases like invalid slugs. Overall, it is sufficiently complete for a complex tool.

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

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

Schema description coverage is 100% (all 4 parameters described). The description adds extra meaning: explains that size_usd for single-market is spend vs target proceeds, for basket is settlement notional; explains side defaults per mode; and gives examples. This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool. The verb 'check' and resource 'edge' are specific, and the description provides detailed outcomes.

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 the agent when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risks of partial fills and unhedged positions. While it does not explicitly list when not to use it, the context is clear and sufficient for an AI 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are all positive and safe. The description adds extensive behavioral context: compatibility warnings for mismatched bet shapes, temporal alignment checks, and counters for skipped comparisons. It fully discloses edge cases and limitations, going well beyond what annotations provide.

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

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

The description is comprehensive but somewhat verbose. It front-loads the core purpose and then details modes, response structure, and safety fields. While every sentence adds value, it could be trimmed for conciseness without losing essential 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 tool's complexity (cross-venue comparison with multiple modes and safety checks) and no output schema, the description thoroughly explains return values: leg-by-leg prices, spread array, compatibility warnings, temporal alignment, and skip counters. It covers all necessary contextual details for an agent to understand usage and interpret results.

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

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

Schema coverage is 100% with all three parameters described. The description adds value by explaining the two modes, providing valid topics list, and clarifying that explicit tickers override topic mappings. It also includes examples in the schema, making the semantics clear.

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: cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources ('spread', 'compare prices') and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue differences.

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 two modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics yield compatibility warnings. However, it lacks explicit guidance on when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edges, and does not specify when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds crucial behavioral details: returns attribute rows and geometry, SQL-like syntax, pagination with limit/offset, default values, and a sampling tip. No contradiction with annotations.

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

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

Two concise sentences plus a tip. The first sentence states purpose and key parameters; the second provides a practical usage example. No redundant information; every sentence is valuable.

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

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

The description covers the tool's inputs, behavior, and return type (attribute rows and geometry) despite no output schema. It includes default values, limits, and practical guidance. With annotations covering safety, this is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100% with each parameter described. The description adds value by contextualizing parameters (e.g., 'SQL-like where', 'comma-separated out_fields') and providing a practical sampling tip. It goes slightly beyond the schema.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with specific parameters. It distinguishes from sibling tools like search_datasets (which finds layers) and layer_info (which might get metadata), though not explicitly. The purpose is specific and actionable.

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 using search_datasets first to obtain the URL, and provides a tip for sampling (where='1=1', out_fields='*'). It does not list alternative tools, but the context is clear enough for an agent to understand when to invoke this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping and listing behavior, providing useful context beyond annotations.

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

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

Four sentences efficiently cover function, usage, scoping, and pairing. Could tighten slightly but 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?

For a simple read-only retrieval tool, the description covers essential behavioral aspects considering annotations and schema. No gaps identified.

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 optional parameter 'key' is well-described in schema, and description adds 'omit to list all keys' which is key behavioral detail.

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

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

Clearly states the tool retrieves a saved value or lists all keys. Verb-resource pair is explicit and distinguishes from siblings 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?

Tells when to use (looking up previously stored context) and pairs with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds key behavioral details like the effect of setting mark_read:true (flags events as read) and mentions that polls are fine, implying no rate limiting issues. 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 four sentences, front-loaded with the main purpose, and every sentence adds new information. No redundant or filler content.

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

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

Despite having no output schema, the description explicitly lists the return fields (source, citation_uri, raw event payload) and explains filtering and state-changing behavior (mark_read). This fully compensates for the missing output schema.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing an example for type ('sec_8k'), specifying ISO timestamp for since, and explaining the effect of mark_read. 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 starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It distinguishes this tool from siblings by focusing on retrieving events, not managing subscriptions (like list_subscriptions).

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

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

The description states that polls work fine and notes the same feed is available via a GET endpoint for scripts/dashboards, offering an alternative. However, it does not explicitly exclude when not to use this tool versus siblings.

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

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

Annotations already confirm read-only, idempotent, non-destructive behavior. Description adds valuable operational detail about multi-source fan-out, GDELT→GNews fallback, and USPTO dependency sunset, enhancing transparency beyond annotations.

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

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

Well-structured with front-loaded query examples. Sentences are informative but could be slightly more streamlined; minor redundancy in parameter explanations. Overall efficient and clear.

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 (grouped changes, total count, citation URIs) and covers all sources with behavior details, making it self-sufficient for a complex multi-origin 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?

With 100% schema coverage, baseline is 3. Description enhances meaning by explaining format (ISO vs relative shorthand), providing typical usage ('30d'), and clarifying value can be ticker or CIK, adding practical context not in schema.

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

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

Describes a specific verb-resource pair ('change feed for a company') and explicitly contrasts with sibling tool entity_profile for static data, making selection unambiguous.

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

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

Provides concrete query examples ('What's new with X', 'latest on Y'), explains parameters, and explicitly states when to use entity_profile instead, offering clear guidance on tool 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?

Discloses that data is key-value scoped by identifier, with 24-hour retention for anonymous sessions and persistence for authenticated users. Annotations already indicate idempotentHint=true and non-destructive, and description complements 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?

Four sentences, no redundancy. Core purpose in first sentence, usage guidance in second, behavioral details in third, pairing in fourth. Highly efficient.

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

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

Completely covers all aspects: purpose, when to use, behavioral traits (persistence), and pairing with sibling tools. No output schema needed; simple tool is fully described.

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

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

Schema already covers both parameters with clear descriptions (100% coverage). Description adds context about key-value pairs and example patterns like 'subject_property', slightly enhancing understanding beyond schema.

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

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

Clearly states the action ('save data'), the purpose ('reuse later'), and the context ('across conversation or sessions'). Distinguishes from siblings by mentioning pairing with 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?

Provides explicit guidance on when to use ('when you discover something worth carrying forward'), and mentions alternatives (recall, forget) to guide tool 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, idempotentHint, openWorldHint, and destructiveHint false. The description adds substantial behavioral detail: it cascades through multiple lookup endpoints internally, replaces 2-3 manual lookups, degrades gracefully when GLEIF or OpenFIGI are unavailable (EDGAR identifiers still return), and explicitly lists unresolved identifiers under an `unresolved` field. This goes well beyond what annotations provide and gives the agent rich behavioral transparency.

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

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

The description is verbose (multiple paragraphs) and contains extensive detail about internal resolution logic (e.g., parent/ultimate-parent/children ownership, graceful degradation). While well-structured and front-loaded with the key purpose, it could be trimmed without losing essential information. For an agent quickly scanning tool definitions, the length may reduce readability. A more concise format would improve scannability.

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

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

Despite having no output schema, the description fully explains what the tool returns for both entity types: for company it lists CIK, ticker, company name, LEI, FIGI, parent/ultimate-parent/children ownership, and an explicit `unresolved` list; for drug it returns RxCUI, ingredient, brand, and a citation. The description also covers graceful degradation, input types, and internal cascading behavior. This is complete and self-sufficient for correct invocation.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds meaningful value by detailing acceptable inputs for company (ticker, CIK, ISIN, company name) and drug (brand or generic name) with concrete examples like 'AAPL' and 'ozempic.' It also explains how an ISIN resolves through GLEIF mapping. This enriches the schema beyond the 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?

The description starts with natural language queries ('What's the ticker for...') and explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes the tool's purpose from siblings like entity_profile or compare_entities by using the phrase 'Use FIRST whenever you have a name but need an ID.' The verb 'resolve' is specific and the resource is identity identifiers.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke this tool. It gives concrete input examples (ticker, CIK, ISIN, drug names) and lists supported entity types. While it does not explicitly mention when NOT to use it (e.g., if ID is already known), the strong 'first in pipeline' directive and detailed supported-type descriptions make the usage context quite clear.

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

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

Annotations indicate read-only, idempotent, no destruction. Description adds that it probes each entity, ranks results, and returns score/confidence/signal density. 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?

Three well-structured sentences: purpose, mechanism, use case. No wasted words, front-loaded with key action.

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

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

No output schema, but description explains return fields (score, confidence, signal density per entity). All parameters are covered. Context is sufficient for an agent to understand the tool's 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. Description adds context: first entity is treated as subject, models can be omitted for free default, and context disambiguates common names. Adds value beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score. Differentiates from siblings like ai_visibility_check (single entity) and compare_entities (other comparison 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?

Explicitly says it's useful for competitive AI-marketing audits and implies when to use. Does not explicitly state when not to use, but the use case is clear. Sibling tools provide alternative for single entity checks.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses partial failure behavior, timeout details (5-30s for bundlephobia first measurement), and the sources_failed field. 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 information-dense and front-loaded with the main purpose. However, it contains some redundancy (e.g., ecosystem information repeated) which could be trimmed. 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?

With no output schema, the description fully details the return structure (summary block, advisories, links, alternatives). It covers all relevant aspects: data sources, behavior on failures, and ecosystem scope.

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 no new meaning beyond what the schema provides for parameters (package and version). It restates defaults and acceptance of scoped packages.

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

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

The description clearly states the tool is a composite check for npm packages across deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings by noting ecosystem limitations.

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

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

The description explicitly states when to use ('is X safe / popular / small'), and provides alternatives for other ecosystems (PyPI, Maven, etc. under deps.dev:version directly).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds return value details (name, summary, record_count, url) but no additional behavioral traits beyond what annotations provide.

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

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

The description is a single clear sentence that covers the tool's purpose, what it returns, and how to use the result. Every part is valuable 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?

Given the tool has 3 optional parameters, no output schema, and safe annotations, the description fully informs the agent about the input (keyword), output fields, and next steps (pass url to siblings). No gaps.

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

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

Schema coverage is 100% with each parameter described. The description restates the action of searching by keyword but does not add additional semantic nuance beyond the schema. 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 searches City of San Bernardino GIS open geospatial datasets by keyword. It specifies the resource domain (GIS datasets) and distinguishes from siblings by mentioning that the returned url should be passed to query_layer / 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?

Explicitly tells the agent to pass the returned url to query_layer / layer_info, indicating a clear usage flow. Does not explicitly state when not to use, but the context of returning dataset URLs makes the alternative tools clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral details: embedding model ('BGE-base-en embeddings'), similarity metric ('cosine'), sliding window size ('500-char overlapping windows'), character limit ('200K chars' with truncation flag), and output format ('top-N passages with character offsets and similarity scores'). 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?

Three well-structured sentences: first defines core action, second provides usage guidance and benefits, third covers technical details (embeddings, window, cap, truncation). No redundant words; every sentence earns its place.

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

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

Despite lacking an output schema, the description fully compensates by describing the return format ('top-N passages with character offsets and similarity scores'). It also notes pairing with a sibling tool and defines the input characteristics (max 200K chars, sliding windows). For a tool with 3 parameters, this is highly complete.

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

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

Schema description coverage is 100%, but the description adds valuable context: for 'text' it specifies the max length (~200K chars), for 'query' it provides concrete examples ('supply-chain risk', 'fiscal year 2024 revenue'), and for 'limit' it implies its effect ('top-N passages'). 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?

The description clearly states it performs 'semantic search INSIDE a fetched record', specifying the verb (search) and resource (inside a record). It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by explaining its role: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. It also describes how it pairs with 'ask_pipeworx_grounded', giving clear usage context. While it lacks explicit 'do not use' guidance, the conditional 'when' usage is strong.

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 (write, idempotent, non-destructive), description adds: OAuth requirement, delivery channel behaviors (phone verification, 10/day SMS cap, webhook auto-disable after 10 failures), and that webhook secret is returned once. 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?

Description is dense but well-structured, front-loading purpose and then expanding. Every sentence adds value, though 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 (multiple types, nested params, delivery channels) and no output schema, description thoroughly covers prerequisites, rate limits, examples, and behavioral details. Only minor gap is precise return format, but 'new subscription id' suffices.

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 far exceeds schema by providing type-specific examples, constraints (phone verify, 10/day cap, webhook signing), and nested object structures. Adds significant meaning beyond schema.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies return value 'Returns the new subscription id.' It distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts by describing creation action.

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?

Describes prerequisite 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)' and provides detailed type examples. Lacks explicit comparisons to sibling tools 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 mark read-only and idempotent. Description adds that it returns tool+argument shapes and behavior with/without topic argument. 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?

Front-loaded with example queries, dense but not verbose. Each sentence contributes meaningful 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 one optional parameter and no output schema, the description adequately explains return content and usage. Could clarify output structure more, but sufficient.

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

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

Schema covers the topic parameter with enum list; description adds usage pattern (omit for full spread, pass topic to focus). Both add value.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, distinguishing it from siblings like ask_pipeworx and 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains optional topic parameter. Lacks explicit when-not-to-use 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 supply readOnlyHint=false and destructiveHint=false. The description adds valuable context: ownership enforcement, deactivation instead of deletion, and that historical events persist. This exceeds the baseline expected from annotations alone, though it does not detail idempotency which is covered by annotation.

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

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

Two sentences, no redundant words. The first sentence immediately states the action and required input. The second provides critical behavioral context. Every sentence is essential and information-dense.

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

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

Given the simple tool with one parameter, no output schema, and existing annotations, the description covers all necessary aspects: action, parameter source, usage constraints, and effect on data. It is fully adequate for an agent to invoke correctly.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds 'Ownership is enforced' which relates to the parameter's context but does not substantially enhance the schema's meaning. Baseline for high coverage is 3.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying this is a cancellation action.

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

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

The description explicitly states ownership enforcement, guiding agents not to attempt canceling others' subscriptions. It also clarifies the effect (deactivation, not deletion) and references 'recent_alerts' for historical data, providing clear contextual 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 mark the tool as read-only and idempotent. The description adds essential context by explaining the difference between 'could_not_verify' (check did not happen) and 'unsupported' (no source found), warning that 'could_not_verify' is not evidence. It also discloses the two-pipeline behavior and the fact that it returns a citation, exceeding what annotations provide.

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

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

The description is front-loaded with trigger phrases and organized into clear segments: trigger, when-to-use, pipeline details, return values, and crucial failure-mode warning. Every sentence adds value, and the length is justified by the complexity of the tool. There is no filler.

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

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

With no output schema, the description compensates by enumerating all possible verdicts, mentioning the citation and reasoning, and explaining failure modes in detail. It also indicates the tool consolidates multiple steps, which helps the agent understand the scope. This is complete for a 2-parameter, no-output-schema tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra nuance for tolerance_pct, explaining that it overrides implied tolerance and giving a use case for hallucination detection (1–2). It also provides concrete examples for the claim parameter. This goes beyond the schema's built-in 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 uses a specific verb ('validate') and resource ('factual claim'), and opens with clear trigger phrases for natural-language claim verification. It explicitly distinguishes itself from generic Q&A tools by focusing on fact-checking with a defined verdict set, and mentions the structured vs. grounded pipeline distinction, making sibling differentiation clear.

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

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

The description states exactly when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains two distinct usage paths (company-financial vs. any other claim) and notes that it replaces 4–6 sequential calls. However, it does not explicitly name alternative sibling tools for non-factual queries, so it falls short of a 5.

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