Octopus Energy

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds key behavioral details: default free model, BYO key for Anthropic (direct billing), return structure (per-model fields + combined view), and cost implications. 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 (4 sentences) with critical information front-loaded. Every sentence adds value: main action, default behavior, return format, use cases.

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

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

Given 4 parameters (1 required), no output schema, and no nested objects, the description is complete: it explains all parameters, default behavior, optional features, and the return structure (per-model {score, confidence, signals, raw_response} + combined view).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between the 'models' and '_apiKey' parameters (e.g., only needed for Anthropic) and clarifies the default model behavior.

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

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

The description clearly states the tool's action ('Probe one or more LLMs'), the resource (LLMs for visibility of business/brand), and the output (score 0-100 per model). It differentiates from sibling tools like 'ask_pipeworx' by focusing on visibility scoring rather than direct Q&A.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to use the optional API key. However, it does not explicitly state when not to use the tool or compare with alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context about internal routing, argument filling, citation URIs, and tier availability. However, it doesn't disclose potential limits or behavior when sources are unavailable, so not a perfect 5.

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: a strong directive at the top, followed by purpose, usage triggers, examples, step-up options, and news handling. There is some repetition (e.g., authoritative data mentioned twice), but each section serves a distinct role. Appropriate for the tool's complexity.

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

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

For a routing tool with no output schema, the description fully covers what it does, what it returns (structured answer with citations), when to use it, and when to choose alternatives. It provides numerous examples and source categories, making it self-contained for an agent.

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

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

Schema description coverage is 100% with detailed aliases and examples. The tool description adds no specific parameter guidance beyond reinforcing that questions should be factual, but the schema is fully self-sufficient. 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's function: routing factual questions to 5,529 tools across 1,455 verified sources and returning structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by positioning as the default entry point and explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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

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

Explicitly instructs to prefer over web search, provides trigger phrases like "what is", "look up", "find", and gives concrete examples. It also names specific alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus clarifies news handling.

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 read-only, idempotent, and open-world hints, and the description adds rich behavioral context beyond these: live candidate routing tests, current inactive state, fallback behavior, and the fact that results are compared with the stable router. This fully discloses the tool's experimental behavior.

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

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

The description is four sentences of dense, relevant information. Every sentence adds value, but it could be slightly more concise; it is well-structured and front-loaded with the key 'beta' identification.

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

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

Given that this is a complex router with no output schema, the description fully explains current status, usage, relationship to the stable tool, and fallback behavior. It provides sufficient context for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters, including aliases. The description does not add parameter-level detail, but since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with identical universal routing, distinguishing it from its stable counterpart and the grounded variant. It specifies the resource (universal router) and the experimental edge nature, making the purpose specific and unambiguous.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, giving clear usage context. However, it does not explicitly state when not to use it (e.g., for production stability), relying on the beta label and mention of the stable router to infer the alternative.

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

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

The description goes far beyond annotations, detailing the refusal reasons, return format, evidence generation, and the extra LLM call cost. Annotations (readOnlyHint, idempotentHint) are confirmed and supplemented; 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?

Despite being dense, every sentence contributes critical information: purpose, mechanism, output format, failure modes, use cases, and trade-off. Front-loaded with the core value proposition, and nothing is redundant.

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 fully covers the tool's complexity: routing to thousands of tools, extraction-only behavior, refusal handling, and return fields. With no output schema provided, the description compensates by explaining the return shape and error codes, making it complete for an agent.

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

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

Schema coverage is 100% for all 6 parameters (aliases for question), so the schema already documents everything. The description adds no additional parameter-level detail beyond mentioning 'fills arguments' generically; 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's purpose: a hallucination-resistant answer mode for high-stakes reads, with a specific mechanism (same routing as ask_pipeworx, extracts answer only from tool result). It distinguishes itself from siblings like ask_pipeworx by adding evidence/refusal behavior, and lists concrete 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?

Explicitly states when to use (answers that will be quoted, cited, or acted on, where no facts can be invented) and when not to (casual lookups, prefer ask_pipeworx). Names the alternative tool and explains the cost trade-off, giving clear decision guidance.

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

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

Annotations indicate readOnly, non-destructive, and idempotent. The description goes far beyond by detailing fan-out behavior, response shapes, resolver contract, safety checks (low-confidence, closed markets), parent event extraction, and resolution rule risk. This is highly transparent.

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 very long and includes extensive examples and edge-case explanations that could be more structured. While it front-loads the main purpose, the verbosity detracts from conciseness. It could be broken into clearer sections.

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

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

Given the complexity and lack of output schema, the description covers all critical aspects: inputs, fan-out behavior, response shapes, resolver contract, parent event handling, news fields, and risk warnings. It is thorough and provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds meaningful detail: explains the market parameter accepts multiple formats, depth controls evidence sources, and include_raw summarizes vs full payloads. This adds value beyond the schema.

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

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

The description clearly states that it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, so it's not a perfect 5.

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 usage examples ('should I bet on X', etc.) and explains when results might be low confidence or blocked. However, it does not specify when to use alternative tools or what prerequisites are needed. The guidance is present but not comprehensive.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals that it pulls LATEST 10-K data, sorts results by primary metric, and returns paired data with citation URIs. It also details internal processing differences between company and drug types.

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 densely informative with key guidance front-loaded (query examples, preference directive). Every sentence adds value, though slightly verbose. Structure is clear: example usage, then explanation, then technical details.

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

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

No output schema, but description sufficiently explains return behavior: sorted results, paired data per entity, citation URIs. Covers both entity types and special cases (off-calendar fiscal years). Adequately complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains what each 'type' value entails (company pulls financial data, drug pulls adverse event counts) and specifies input formats (tickers/CIKs for companies, drug names for drugs) and constraints (2-5 items). This enriches the schema defaults.

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

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

Description explicitly states it performs side-by-side comparison of 2-5 companies or drugs, with clear query examples like 'Compare X and Y' and 'which is bigger'. It distinguishes from sequential single-entity lookups and sibling tools. The verb 'compare' and resource entities are concrete.

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?

Clear directive to prefer this tool over sequential single-pack lookups when comparing entities. Explains the data sources for each type (SEC EDGAR for companies, FAERS for drugs) and notes correct handling of off-calendar fiscal years, guiding appropriate invocation.

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

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

Beyond the read-only/idempotent annotations, the description adds critical behavioral details: account/paid-plan requirements, the findings packet structure with gaps[] for unanswered facets, a 'never invented' honesty guarantee, depth-dependent hop/recovery/contradiction behavior, resolvable citation_uris, semantic excerpting, and latency expectations. This fully discloses the tool's safety and output characteristics.

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?

Though lengthy, the description is front-loaded with the most crucial constraint (account required) and organized by topic (function, usage, depth semantics, output details, performance). Every sentence carries unique operational information relevant to selecting and invoking the tool, with no wasted text.

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

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

With no output schema, the description fully covers return values: verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also explains prerequisites, cost, and performance, making it self-sufficient for an agent despite the tool's complexity.

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

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

The description expands on both schema parameters: depth is explained with exact facet counts and behavioral differences (quick=3 single-hop, standard=5 with gap recovery and contradiction scan, thorough=8 paid with lead chasing), and question is clarified as allowing broad/multi-part input since decomposition is the point. This significantly enriches the sparse schema descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across 1,455 structured data sources in a single call, decomposing questions and routing to tools in parallel. It explicitly distinguishes itself from open-web search and names its best use case, setting it apart from sibling tools like 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?

Explicit guidance is given: 'Best for broad/multi-part questions over structured data' and alternatives are named — 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. This provides clear when-to-use and when-not-to-use direction.

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 that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) – each result is ready to call directly, no second schema lookup needed.' This provides useful behavioral context beyond annotations.

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

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

The description is a single paragraph that front-loads the purpose and includes a list of example domains. While informative, the list is somewhat lengthy for a parameter description. However, it remains efficient and every sentence adds value, slightly marred by redundancy in domain enumeration.

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 discovery purpose and the presence of many sibling tools, the description covers what it does, when to use, and what it returns. It lacks mention of behavior when no tools match or error handling, but overall is fairly complete for a search 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 good alias descriptions. The description adds that 'query' should be a 'Natural language description of what you want to do' but does not elaborate on the 'limit' parameter or how results are ranked. The schema already handles parameter meaning, so description adds modest 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 uses a specific verb 'Find' and resource 'tools', and lists numerous example domains (SEC filings, FDA drugs, etc.) to ground the purpose. It clearly distinguishes itself from sibling tools as a discovery/search tool, making the purpose unmistakable.

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

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

The description explicitly states when to use ('browse, search, look up, or discover what tools exist') and advises 'Call this FIRST when you have many tools available'. This provides clear context, but it does not name specific alternative tools for comparison, leaving a minor gap in guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: patent soft-fail until May 2025, fallback chains, fan-out behavior. No contradiction with annotations.

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

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

Description is lengthy but each sentence adds value. Front-loaded with example queries. Slightly long but justified by complexity. Could be more structured with bullets but acceptable.

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 fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. For a complex tool with 2 params, it provides complete guidance.

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

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

Schema covers 100% of parameters. Description adds useful context beyond schema: type only 'company', value must be ticker or CIK, names not supported, and the format example. Does not redundantly restate schema.

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

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

Description clearly states it provides a full cross-source profile of US public companies. Lists example queries and data sources, distinguishing it from sibling tools like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER' over chaining individual lookups for holistic views. Gives clear when-not condition (only names not supported, use resolve_entity first) and acceptable inputs (ticker or CIK).

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

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

Description matches annotations (destructiveHint=true) but adds only rationale ('clear sensitive data') beyond what annotations already declare.

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

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

Two sentences, front-loaded with purpose, no unnecessary words.

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

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

Simple tool with one parameter, description covers purpose and usage adequately. No output schema needed.

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 provides full description for the single parameter ('key'). Description adds no additional 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?

Clear verb 'delete' and specific resource 'memory by key'. Distinguishes from sibling tools like 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?

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with remember and recall. Lacks explicit 'when not to use' but provides sufficient guidance.

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

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

Annotations already declare readOnly, idempotent, open world, non-destructive. Description adds concrete behavior: fetches page, extracts title/description/key links, emits standard markdown format. 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 sentences, front-loaded with purpose, no wasted words. Structure is clear and efficient.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully explains input, process, and output format. Covers all necessary context for an agent.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds no additional meaning beyond what's in the schema (e.g., examples are already implied). Baseline 3 is appropriate.

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

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

Clearly states the verb 'generate', the resource 'llms.txt file for any URL', and the goal of indexing for AI crawlers. Distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence which are about auditing rather than generating.

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 specific use cases: getting a client's site indexed, drafting for own project, auditing competitor. Could be improved by explicitly stating when not to use, but the examples are sufficient.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds the output format ({count, results:[{group_id}]}) but does not disclose additional behaviors beyond what annotations imply.

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

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

The description is two sentences, front-loads the primary action, and contains no redundant information. Every sentence adds value.

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

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

Given the simple one-parameter input and complete annotations, the description adequately covers the purpose, output structure, and real-world significance. It lacks error handling or edge cases but is sufficient for a straightforward mapping 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?

The input schema fully describes the postcode parameter (type, example, spaces optional). The description adds context about the output group_id range but does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool maps a UK postcode to a GSP group, explaining the group_id suffix and its relevance to tariff codes and regional breakdowns. This is specific and distinguishes the tool's core function.

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

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

No guidance is provided on when to use this tool versus alternatives like tariff_unit_rates or product_details. There is no mention of prerequisites or 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?

The description confirms a read-only, idempotent operation as indicated by annotations, and adds value by detailing the return fields and scope (UK energy products). 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 with no wasted words. The key action and return structure are front-loaded, making it easy to grasp.

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 provides a detailed return structure list and mentions the relationship with product_details. It is fully adequate for understanding tool output.

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 detailed descriptions for each parameter. The description adds minimal value by calling them 'optional filters', but the schema already explains their semantics, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists Octopus Energy UK energy products, specifies the return structure, and mentions that the 'code' field feeds into the product_details sibling tool, distinguishing it from that 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 implies usage context by stating it lists products and that 'code feeds product_details', suggesting when to use this vs. product_details. However, it does not explicitly state when not to use it or contrast with other siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by enumerating specific returned fields and scope (caller's active subscriptions), beyond what annotations cover.

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

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

Two sentences: first declares purpose and return fields, second gives usage context. No wasted words, 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?

Description fully covers the tool's behavior for a simple list operation with one optional parameter. No output schema needed, as fields are listed.

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

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

Schema coverage is 100% with a well-described optional boolean parameter (include_inactive). Description does not need to add more; 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?

Clear verb 'list' and resource 'subscriptions'. Specifies returned fields (id, type, params, etc.), distinguishing from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides practical guidance for selecting 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 are all false, offering no safety profile, so the description carries the burden. It discloses rate limiting (5/identifier/day), the account-free claim_token flow, how to check resolution status, and that feedback feeds a daily digest. 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?

Although about 150 words, every sentence is purposeful. The first sentence states the core purpose, then guidelines, exclusions, mechanics, and rate limits are introduced in logical order. No filler or redundancy.

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

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

The tool has no output schema and four optional parameters, but the description covers both use cases, return values (claim_token or status), operational limits, and right/wrong usage. It is complete for a feedback and reply-checking 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 covers all parameters at 100%, giving baseline 3. The description adds value by advising 'don't paste the end-user's prompt' for the message field and clarifying claim_token round-trip behavior beyond the schema. It doesn't fully compensate, as most meaning lives in the schema, but the extra guidance raises it to 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb and resource. It enumerates use cases (bug, feature/data_gap, praise) and explicitly contrasts with sibling tools by restricting to Pipeworx-served tools only, clearly differentiating from 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?

Provides explicit when-to-use guidance (bug, missing tool, praise), when-not-to-use (other MCP servers), and identifies Pipeworx tools by the connection's listing. It also explains two operational modes: filing feedback and checking a claim_token, with clear instructions on how to do each.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), description adds data source ('derived from CF analytics-engine, no PII'), caching behavior ('Cached 5min-1h depending on window'), and the aggregated nature (pack, tool, count). Fully transparent.

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?

Five sentences, each earning its place: first sentence defines core output, next three list use cases, last sentence covers technical details. Front-loaded and 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 fully states what is returned (top tools, packs, volume). For a simple tool with one optional parameter and clear output, this is complete. Context of use cases and caching adds completeness.

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?

Only one parameter 'window' with schema coverage 100%. Description adds value beyond schema by explaining the effect of window choice ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). Baseline 3 plus extra context gives 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?

Description clearly states verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window.' Distinguishes from siblings like ask_pipeworx and discover_tools by focusing on aggregate 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, seeing alignment). Window selection guidance is given. No explicit when-not-to-use or alternatives, 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 read-only and idempotent. Description adds detailed behavioral context: monotonicity checks, partition sum validation, semantic anchor for cross-event, placeholder filtering, and fill check against CLOB 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 well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded. While it is lengthy, every sentence adds value; slightly less concise than ideal but justified by tool 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?

Despite no output schema, the description fully explains output fields (opportunities[], partition_check, fill_check), edge cases (null signal, placeholder filtering), and references sibling tool for custom sizing. All necessary context for agent selection and invocation is present.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning—explaining event mode's child market analysis and topic mode's cross-event search with Jaccard similarity and partition filtering, going well beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific verbs and resource. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

Explicit guidance is provided: no args for trending scan, event for specific market, topic for cross-event scan. Includes recommendations and alternatives (e.g., polymarket_fill_risk for custom sizing), meeting all criteria for usage 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: caching at KV level, three response segments, edge calculation details, slippage, and diagnostic output. No contradictions.

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

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

The description is a dense block of text with extensive technical detail. While front-loaded with purpose, it is verbose and could be more structured. 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?

Despite having no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and covers all 9 parameters comprehensively. It is complete for an edge scanning tool with good annotations.

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

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

Parameter schema coverage is 100% and descriptions are detailed. The tool description adds context about how parameters affect segments and tradeable-edge knobs, providing additional meaning beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and action (scan and return opportunities), distinguishing it from siblings like polymarket_arbitrage.

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

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

Explicitly states it's built for 'what should I bet on today' and notes that Fed bets are excluded from ranking. Provides context for when to use, but does not explicitly mention when not to use or list specific alternatives.

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

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

The description adds significant behavioral context beyond annotations: explains response structure (tracked, expired, snapshot_dates), data limits (60-day TTL, snapshot gaps), and sign conventions (negative means SELL YES). 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 well-structured and front-loaded: purpose, args, response structure, limits. Each sentence provides necessary information without excess.

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

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

Despite no output schema, the description thoroughly documents the response format and constraints, making it complete for tool 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%, so baseline is 3. The description restates parameter purposes with minor clarifications (e.g., max 30 for days) but adds limited new meaning beyond the schema.

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

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

The description explicitly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It clearly distinguishes from sibling polymarket_edges by focusing on historical analysis.

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

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

The description implies when to use (for historical edge analysis) but does not explicitly exclude use cases or name alternatives. The context is clear enough for agents to differentiate.

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 (readOnlyHint, idempotentHint, etc.) already indicate safety, but the description adds rich behavioral context: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict (clean|degraded|cannot_fill). It also explains the risks of thin legs and forced directional risk, 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 well-structured and front-loaded with the core purpose. It uses bold for emphasis. While it is lengthy, every sentence adds value and explains complex behavior. It could be slightly more concise but is not redundant.

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

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

Given the tool has 4 parameters, no output schema, and no nested objects, the description provides a comprehensive understanding. It covers both modes, all parameters, return values, and potential pitfalls (partial fills, thin legs). It is fully adequate for an agent to correctly 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 description coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the dual interpretation of size_usd (max spend on buys vs target proceeds on sells for single-market; settlement notional for basket), the default auto side for basket mode, and the exact return fields. This provides a complete understanding of parameter behavior.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes: single-market and basket. It uses specific verbs like 'check' and explains the resource (CLOB order-book depth), differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs the agent to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why theoretical overround is not always capturable on thin books and warns that partial basket fills convert an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

The description goes far beyond the annotations (which already declare read-only, idempotent, and non-destructive). It explains the computation of spreads, response structure, compatibility warnings, temporal alignment, and skipped cross types, fully disclosing behavior and caveats.

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

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

The description is well-structured and front-loaded with the core purpose. However, it is somewhat lengthy with some repetition (e.g., 'pre-mapped' appears multiple times). It could be slightly more concise while retaining all necessary details.

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

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

Given the tool's complexity (two modes, safety fields, no output schema), the description is remarkably complete. It covers all inputs, outputs, and edge cases, including practical warnings about compatibility and rarity of tradeable spreads, enabling an AI agent to use it correctly.

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

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

With 100% schema coverage, the schema already documents parameters. The description adds value by listing the exact topic shortcuts, explaining the override mechanism, and providing an example of usage, enhancing 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 that the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It details two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides extensive context on when to use the tool, including safety fields and warnings about compatibility issues. However, it lacks explicit comparison to sibling tools or guidance on when not to use it in favor of 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 this as read-only, idempotent, non-destructive. The description adds that it returns tariffs by region/payment method, standing charges, unit rates, and lists tariff set categories. No contradictions.

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

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

Three sentences, front-loaded with purpose. No redundant information. Could be slightly tighter but efficient overall.

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

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

Without an output schema, the description comprehensively explains return values: tariff breakdown by region and payment method, including codes, standing charges, unit rates, and tariff set categories. It also advises on using the tariff code further.

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

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

Schema coverage is 100% with a clear description of the only parameter (productCode from list_products). The description does not add extra semantic meaning beyond providing an example in the schema examples.

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

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

The description clearly states the tool retrieves 'full detail for one product code' including tariffs by region and payment method. It distinguishes from sibling tools like list_products (which lists product codes) and tariff_unit_rates (which uses a tariff code for rates), providing specific context.

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

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

The description implies use when a specific product code is known and comprehensive tariff info is needed. It tells how to further use the tariff code with tariff_unit_rates. It does not explicitly list when not to use, but sibling differentiation is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by explaining scoping to identifier and the ability to list all keys when key omitted, complementing 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?

Four sentences, front-loaded with the main purpose, no extraneous words. Every sentence provides necessary 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 simplicity (1 optional param, no output schema), description fully covers what the tool does, when to use it, and scoping details. 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% (1 param with description). The description adds useful context: 'omit the key argument' and the purpose of listing keys, enhancing the schema's 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?

Clearly states the action: retrieve a value saved via remember, or list all keys. Verb+resource is specific, and it distinguishes from sibling tools forget and remember.

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 explains when to use (look up stored context) and when to omit argument to list keys. Also mentions pairing with remember and forget, providing clear usage context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint are consistent. The description adds context about polling behavior, the effect of mark_read on subsequent calls, and the availability of an alternative endpoint. 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 a single paragraph of 4 sentences, front-loaded with the main purpose. It is concise without verbosity, though a slightly more structured format (e.g., bullet points for filters) could improve readability.

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

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

Despite no output schema, the description explains the return values (source, citation_uri, raw payload). It covers filtering, mark_read effect, polling suitability, and alternative access. For a tool with 5 non-required parameters, this is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by explaining the effect of mark_read (flagging events read so next call shows newer ones) and mentioning type and since filters beyond the schema's basic descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, specifying what each event carries (source, citation_uri, raw payload). It does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'subscribe', but the verb 'Pull' and resource 'fired events' provide a specific purpose.

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 filter by type and/or since, and how to use mark_read to control which events appear on next call. It also notes that polling works fine and provides an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare it with 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds operational context: sources used (SEC EDGAR, GDELT/GNews, USPTO), USPTO sunset date and soft-fail behavior, return structure (grouped changes, total_changes, citation URIs). Good but not perfect because annotations already cover safety.

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

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

Single paragraph with all essential info front-loaded. Includes example queries, tool function, source details, parameter hints, and sibling differentiation. No superfluous 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?

Despite no output schema, describes return structure. Covers error handling (soft-fail for USPTO), fallback mechanism, and parameter specifics. Comprehensive for a read-only aggregation tool with 3 params and many siblings.

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

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

Schema description coverage is 100% (all three parameters described). Description adds more: 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, 'type' only supports 'company'. Provides context 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 tool provides a 'change feed for a company' with specific examples like 'What's new with X' and 'latest on Y'. It explicitly distinguishes from sibling 'entity_profile' by stating when to use that instead.

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 usage examples, explains fallback logic (GDELT→GNews), and gives parameter guidance like 'Use "30d" or "1m" for typical monitoring'. Directly tells when to use alternative tool 'entity_profile'.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context about scoping by agent identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. No contradictions; slight deduction for not explicitly confirming idempotency behavior.

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

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

Concise and well-structured: purpose first, then examples, then technical details. Four sentences with no fluff, each sentence adds unique value.

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

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

For a simple key-value store with no output schema, the description covers lifetime, scoping, and tool pairing comprehensively. Complete for an agent to understand 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 coverage is 100% with basic descriptions. The description adds examples of key formats (e.g., 'subject_property', 'target_ticker') and clarifies that value is any text, going beyond schema to aid parameter selection.

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

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

The description clearly states it saves data for later reuse, with specific verb 'Save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by explicitly naming them, leaving no ambiguity about the tool's role.

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

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

Provides explicit when-to-use guidance ('when you discover something worth carrying forward') with concrete examples (resolved ticker, target address, etc.). It also mentions pairing with recall and forget, giving clear context and alternatives.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details what happens when an identifier cannot be resolved (stated under `unresolved` rather than omitted), how sources are labelled, and that LEI/FIGI enrichment degrades gracefully with EDGAR identifiers still returning. It also notes the internal multi-endpoint cascade, giving substantial behavioral insight.

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

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

The description is long but well-structured, starting with trigger examples and the core purpose, then breaking down supported types and behavior. Each sentence adds informational value, though the density could be slightly overwhelming; the front-loaded core purpose helps.

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 effectively documents expected return content for both entity types, including the `unresolved` field and graceful degradation. It covers input formats, source attribution, and edge cases, making it highly complete for a complex lookup 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?

The schema already covers both parameters with examples, and the description enriches this by specifying exactly which identifiers are returned for each type (e.g., CIK, ticker, company_name, LEI, FIGI for company; RxCUI, ingredient, brand for drug). This goes beyond the schema's basic type/value definitions.

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

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

The description opens with concrete user queries and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This is a specific verb+resource that clearly differentiates from sibling tools like entity_profile or compare_entities by focusing on identifier resolution.

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

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

It provides explicit trigger phrases and the directive 'Use FIRST whenever you have a name but need an ID.' It also clarifies what input formats are accepted per type and explains that using this tool replaces 2-3 manual lookups. However, it does not name alternative tools or explicitly state when not to use it, so while context is clear, it stops short of full alternative guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density—useful behavioral context beyond annotations. No contradiction present.

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 concise sentences front-load the purpose, then explain the mechanism and use case. Every sentence adds distinct value with no redundancy.

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

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

The description explains the tool's process and output format adequately. It leverages annotations for safety and schema for parameter details. Could be improved by mentioning error or edge cases, but overall solid for a tool with no output schema.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the narrative role of the first entity and reinforcing the correlation between apiKey and the 'anthropic' model option, complementing 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking results. It distinguishes itself from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison) by being specific to AI presence.

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 it's useful for competitive AI-marketing audits and provides a concrete example question. It notes that the first entry is treated as the subject, guiding usage. However, it doesn't explicitly state when not to use this tool versus alternatives like ai_visibility_check.

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 context not captured by annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeout sources. This is useful but could mention more about default behavior on total failure.

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

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

The description is front-loaded with the core purpose and contains valuable detail, but it is somewhat lengthy. Every sentence adds value, though minor trimming could improve readability while retaining all 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?

Without an output schema, the description fully explains the return structure: summary block with specific fields, per-advisory detail, links, and alternative versions. It covers failure modes, external dependencies, and scope. The tool is complex, and the description addresses all relevant aspects.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra semantics: 'Scoped packages (e.g. "@types/node") are accepted' for 'package', and 'Defaults to the latest published version when omitted' for 'version'. This exceeds what the schema provides.

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

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

The description clearly states the tool is a composite check for adding npm packages, specifying the two data sources (deps.dev and bundlephobia). It distinguishes itself from sibling tools by focusing on npm package analysis, which is unique among the listed 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 provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies scope limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to-use and alternative paths.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as safe. The description adds technical details beyond annotations: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, with a 200K char cap (truncated and flagged). This provides valuable behavioral context without contradiction.

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

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

The description is concise with no redundant sentences. Key purpose and usage are front-loaded in the first sentence. Every sentence adds unique information (use case, example, technical details, pairing suggestion). No fluff.

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

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

Despite no output schema, the description fully explains what is returned (passages with character offsets and similarity scores). It covers constraints (200K char cap, truncation flag), embedding model, and windowing strategy. For a search tool with three simple parameters, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by clarifying the max character limit for text (~200K) and providing example queries. It also ties the limit parameter to the number of passages returned, adding context beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', gives concrete examples (SEC 10-K, article, long tool result), and specifies output type (passages with offsets and similarity scores). It distinguishes from siblings by positioning it as an alternative to stuffing the full text into a prompt.

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 when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. It also mentions pairing with ask_pipeworx_grounded for a two-step workflow. It lacks explicit when-not-to-use statements, but the guidance is clear and actionable.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds significant behavioral context: it states the tool requires OAuth, lists supported types with example parameters, details delivery channels (feed, email, SMS) with constraints like phone verification and a 10/day SMS cap. The description also notes the return of a subscription id. There is a potential contradiction: idempotentHint=true may not align with creating a new subscription each call, but the description does not explicitly contradict it.

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

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

The description is moderately long but well structured: purpose and return value first, then requirements, then types with examples, then delivery options. It is front-loaded and each section adds value. Could be slightly more concise, but overall efficient.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple enum values, delivery options), the description covers all necessary aspects: purpose, requirements, type-specific parameters, delivery channels, constraints, and return value. There is no output schema, but the return value is mentioned. The description is complete for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds substantial meaning beyond the schema by providing concrete examples for each type (e.g., items codes for sec_8k, topic for polymarket_edge) and clarifying delivery constraints (e.g., phone must match verified phone, 10/day cap). This extra detail improves the parameter semantics above the baseline.

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

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

The description uses a specific verb 'Create' and clearly identifies the resource as 'a proactive monitoring subscription to a live-data event stream'. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation and explicitly stating the return value, the new subscription id.

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

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

The description provides clear context for when to use the tool (to create a subscription) and includes prerequisites (Pipeworx OAuth account, no anonymous). It does not explicitly state when not to use it or compare with alternatives, but the sibling list and the detailed type/ delivery options help the agent infer appropriate use cases.

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 valuable context about behavior: returns categorized example questions, supports optional filtering by topic, and is called without arguments for full spread. 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 example queries and is well-structured, but could be slightly more concise. It effectively communicates key information without extraneous words.

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

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

Given the absence of an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes). For a simple tool with one optional parameter, the description is complete and self-contained.

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

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

Schema coverage is 100%, and the description adds meaning by listing possible topic values ('finance, pharma, etc.') and explaining the effect of omitting the parameter ('cross-category spread'). This clarifies the parameter's role beyond the schema.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and names the resource ('example questions with tool+argument shapes'). It distinguishes itself from sibling tools by being the onboarding entry point for new users, making its purpose clear and unique.

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 to use this tool 'FIRST when you do not yet know what Pipeworx can do' and describes when to use the optional `topic` parameter. While it doesn't explicitly state when NOT to use it, the context and alternatives 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 declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, which the description complements by stating the tool returns data (no mutations). It adds beyond annotations: specifies newest-first ordering, default to most recent rates, and output structure with fields. 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?

Very concise: two sentences with no fluff. First sentence states purpose and example; second sentence covers alternative usage and parameter behavior. Every phrase adds value.

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

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

Given 6 parameters, 2 required, no output schema, the description fully explains the output format, default behavior, and all parameter usage. It compensates for the missing output schema by explicitly listing fields. Covers all necessary context 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%, so description adds extra usage context: explains that for Agile it's half-hourly pricing, that kind can be 'standing_charges', and that period_from/period_to bound a window. This goes beyond the schema's 'ISO-8601 start/end' 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 returns time-series of electricity unit rates for a specific tariff, with explicit mention of Agile's half-hourly pricing. It distinguishes from standing charges by setting kind='standing_charges', and the output format is fully detailed. No other sibling tool serves the same purpose.

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 how to switch between unit rates and standing charges using the 'kind' parameter, and how to constrain the time window with period_from/period_to. It does not explicitly state when not to use it, but the sibling tools are diverse and unrelated, so guidance is sufficient.

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

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

Annotations already indicate mutation (readOnlyHint=false), non-destructiveness (destructiveHint=false), and idempotency. The description adds valuable context: the row is deactivated (not deleted) and historical events remain available via recent_alerts. 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 two sentences with zero waste. The first sentence states the primary action, and the second covers ownership and behavioral details. 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?

For a tool with one parameter, full schema coverage, and good annotations, the description completely covers purpose, parameter source, ownership constraint, soft delete behavior, and link to related tool (recent_alerts). No gaps.

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

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

With 100% schema coverage, the schema already describes the 'id' parameter. The description adds extra context by noting the id is 'returned by subscribe', which helps the agent understand how to obtain it. This slightly exceeds the baseline of 3.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by emphasizing ownership enforcement and soft deletion.

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

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

The description explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear guidance on when to use the tool. It does not mention alternatives or when not to use, but the constraint 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 the annotations (readOnly, idempotent), the description discloses the two routing paths, the exact verdict enum, the citation requirement, and a critical caller caveat: could_not_verify means the check did not happen and must not be treated as evidence. This is substantial behavioral context that directly affects how the agent should interpret results.

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 dense, well-structured paragraph that opens with examples, states the use condition, explains the pipelines, lists return values, and flags the could_not_verify semantics. Every sentence serves a purpose, though it could be tightened with bullet points.

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 no-output-schema tool, the description fully explains return values (verdicts, grounded actual value, citation, reasoning), error cases, and the two execution paths. It also covers parameter semantics and caller caveats, leaving no critical ambiguity for an agent deciding when to invoke it.

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

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

The schema already describes both claim and tolerance_pct, but the description adds real-world claim examples and strategic guidance for tolerance_pct ('set 1–2 for hallucination detection'), explaining how it overrides wording-implied tolerance. This adds meaning beyond the schema's range/default.

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 concrete user phrasings ('Is it true that…', 'fact check'), states a specific verb+object (natural-language claim verification against authoritative sources), and clearly differentiates from generic ask tools by focusing on true/false verification. It also outlines two distinct execution paths (SEC/XBRL fast path vs grounded pipeline), making the tool's function unmistakable.

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

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

It explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also partitions claim types (company-financial vs other) and notes it replaces 4–6 sequential calls, implying it should be preferred over multi-step lookups. However, it does not name specific sibling tools as alternatives or exclusions, so it slightly misses the top tier.

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