Nist Beacon

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description respects. The description adds behavioral context: the cost implication of using Anthropic (BYO key), the per-model response structure, and the default model. This adds value 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 two sentences, front-loaded with the core function. Every sentence adds value: first sentence covers purpose, default model, and scoring; second sentence covers optional parameter, response structure, and use cases. No redundancy.

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

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

Given no output schema, the description adequately explains the return format (per-model results and combined view). It covers all parameters, default behavior, and use cases. Could optionally mention rate limits or error handling, but not necessary for 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: explains that 'models' defaults to workers-ai if omitted, that _apiKey is only needed for Anthropic, and that 'context' helps disambiguate. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: to probe LLMs about a business/brand/product/topic and score visibility (0-100) per model. It specifies the default model and distinguishes from siblings by focusing on AI visibility scoring, which is unique among the listed sibling tools like 'scan_competitor_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 provides clear usage scenarios: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the _apiKey parameter for Anthropic. However, it does not explicitly contrast with siblings or specify when not to use this tool.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. Description adds valuable context: routes to 3,756 tools, returns structured answer with citation URIs. No contradictions, and the added details enhance transparency beyond annotations.

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

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

The description is fairly long but well-structured: starts with key guidance, then lists domains, explains routing, and gives examples. The length is justified by the tool's complexity, and it remains scannable.

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 (routing to many sources) and lack of output schema, the description adequately explains what it does, when to use it, and what it returns (structured answers with citation URIs). Examples further enhance 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?

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds examples of valid questions, but does not significantly add semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, with a list of domains and examples. It distinguishes from web search but does not differentiate from the sibling tool 'ask_pipeworx_grounded', so slightly loses a point for sibling differentiation.

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

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

Explicit guidance to prefer over web search for specific domains and query types, with examples. It does not explicitly state when not to use or mention alternatives like 'ask_pipeworx_grounded', 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 already indicate readOnlyHint=true and idempotentHint=true. The description adds value by disclosing the extra LLM call cost, the structured return format including refusal reasons, and the constraint that answers come only from tool result. 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?

Single paragraph front-loaded with purpose, then mechanism, return structure, use cases, cost, and alternative. Every sentence is informative with 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 provides full return structure and refusal reasons. Parameter semantics are fully covered. Sibling differentiation is clear. The high-stakes context is well conveyed.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. Description adds minimal value by restating 'Your question in natural language' and listing aliases, but the schema already covers this. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (extracts answer) and resource (tool result). It distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call cost and preference for casual lookups.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' for high-stakes domains, and advises 'prefer ask_pipeworx for casual lookups'. Clear when-to-use and when-not-to-use with alternative named.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds extensive context: low-confidence resolutions short-circuit, closed markets return specific status, wide-spread markets carry tradeability notes, resolution-rule risk with cancellation parsing. It also explains safety mechanisms and the resolver contract, providing rich behavioral disclosure 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 long and dense, covering many technical details. It is structured with section headers (e.g., RESPONSE SHAPES, RESOLVER CONTRACT) for readability, but the verbosity could be trimmed. Front-loading of purpose and usage is good, but overall it lacks conciseness.

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

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

Given the tool's complexity (3 parameters, no output schema, rich behavior), the description covers all essential aspects: purpose, input variants, classifier examples, fan-out details, response shapes, resolver mechanics, parent events, news fallback, safety, and resolution risk. It compensates fully for the lack of output schema and 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 description coverage is 100%; each parameter has a description. The description adds global context (e.g., fan-out examples) but does not significantly enhance parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). The tool is distinguished from siblings like polymarket_edges or polymarket_arbitrage by focusing on data gathering and research.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not list negative cases or alternatives, the usage context is clear and implies when to invoke this tool over edge-specific 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, idempotentHint, and destructiveHint false, but the description adds no behavioral context (e.g., data freshness, required permissions). 'Chain metadata' does not disclose any behavioral traits beyond what annotations imply, missing an opportunity to clarify 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 extremely concise (2 words) but at the cost of usability. It is not appropriately sized for the tool's complexity; it under-specifies and does not earn its place by providing valuable information. Structure is minimal.

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 an output schema, the description is too minimal to be considered complete. It lacks parameter documentation, usage context, and behavioral details. The tool requires a single required parameter and returns metadata, but the description gives no guidance on use, making it inadequate.

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 has a single required parameter 'chain_id' with no description in the schema. The description fails to explain what 'chain_id' represents or how to obtain it. With 0% schema description coverage, the description should compensate but does not, leaving the parameter semantics completely undocumented.

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 'Chain metadata' is vague and merely restates the tool name. It does not specify what metadata is provided or any action (e.g., retrieve, fetch). The lack of a verb and resource specificity makes it difficult for an agent to understand the tool's exact 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 usage guidelines are provided. The description does not indicate when to use this tool over siblings like 'pulse_at' or 'latest_in_chain', nor does it mention prerequisites or exclusions. The agent receives no help in selecting this tool.

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

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

The description goes well beyond annotations by detailing exact data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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 dense with useful information but not overly long. It is front-loaded with the core purpose and uses a clear structure with examples. Could be slightly more concise, but every sentence serves a purpose.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the absence of an output schema, the description covers all essential aspects for correct invocation and interpretation of results.

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

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

Schema coverage is 100% with good parameter descriptions, and the description adds further context such as examples of values (tickers/CIKs for company, drug names) and the nuanced handling of fiscal years. Adds meaningful 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 the tool performs side-by-side comparison of 2-5 companies or drugs in a single call, with specific verb phrases like 'compare X and Y' and 'which is bigger'. It distinguishes itself from sibling tools by explicitly preferring this over sequential single-pack lookups.

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

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

The description provides clear when-to-use guidance with examples of natural language queries and a strong preference over sequential lookups. It lacks explicit when-not-to-use statements but is sufficient for an agent to decide.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral details: account requirement, paid plan for thorough depth, 15-60s latency, explicit gaps[] for unanswerable facets, pre-verified facts, and structured output with evidence fields. No contradictions.

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

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

Description is dense but not verbose; front-loaded with key value proposition. Every sentence adds distinct information (process, sources, output, alternatives, requirements, timing). No redundancy or filler.

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

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

Given no output schema, description fully explains return values (structured findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]). Covers what, how, when to use, prerequisites, pricing, and latency. Complete for a complex research 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 both parameters with descriptions (100% coverage). Description adds constraint that 'thorough' requires a paid plan and clarifies that 'question' can be broad/multi-part. This adds value beyond schema, but baseline 3 is appropriate since schema already does heavy lifting.

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 core function: grounded multi-source research by decomposing questions into sub-questions and routing them in parallel to many tools/sources, retrieving grounded answers with evidence. It distinguishes from sibling ask_pipeworx by specifying scope (broad/multi-part vs single lookup).

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

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

Explicitly says 'Use for broad or multi-part questions' and contrasts with ask_pipeworx for single lookups. Also mentions requirements (Pipeworx account, paid plan for 'thorough') and typical latency (15-60s), guiding appropriate use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly, which provides useful behavioral context beyond the annotations.

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

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

The description is front-loaded with the purpose, followed by usage guidance and return details. It includes a list of example data domains, which adds length but is helpful for context. Overall, it is well-structured and each sentence contributes.

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 and no output schema, the description adequately explains purpose, usage, and return format. It mentions full schemas with examples, so an agent can understand the output without an explicit schema. A minor gap is the lack of detail on pagination or result structure, but the description is sufficient.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description mentions that query accepts natural language and lists aliases, but this adds minimal value beyond the schema. Baseline 3 is appropriate.

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

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

The description starts with a specific verb+resource: 'Find tools by describing the data or task.' This clearly distinguishes it from sibling tools, which perform data retrieval or analysis, not discovery.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides a broad list of example tasks, giving clear context for usage.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable behavioral context: patents soft-fail due to USPTO API sunset, returns specific fields, parallel call optimization. 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 thorough but well-structured, starting with examples and purpose, then detailing capabilities. Every sentence provides useful information, though slightly long. Front-loaded with key 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?

Despite no output schema, description fully enumerates return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and mentions handling of soft-fails and fallbacks. 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 schema only provides basics (enum for type, string for value). Description adds meaning: value is ticker or zero-padded CIK, names not supported; type will be expanded in future. Adds significant value beyond schema.

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

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

Description clearly states it provides a full cross-source profile of a US public company in one parallel call. Lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and distinguishes from chaining single-pack lookups. Also differentiates from sibling resolve_entity for name 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?

Explicitly states when to use (e.g., 'Tell me about X' queries) and provides use case examples. Tells when not to use: if only a name is provided, use resolve_entity first. Also says always prefer over chaining single-pack lookups.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, indicating a destructive write operation. The description adds context by specifying it deletes by key and mentions clearing sensitive data. 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 extremely concise: two sentences that deliver purpose and usage guidance with no filler. Front-loaded with the core action.

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

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

Given the simplicity of the tool (single parameter, no output schema), the description is nearly complete. It covers purpose, usage, and sibling pairing. Could mention return value or side effects, but adequately supports tool selection.

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 schema already describes the 'key' parameter as 'Memory key to delete'. The description adds no further detail about the parameter format or usage 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 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but does not explicitly state when not to use or list alternatives beyond the memory trio.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds process details (fetching, extracting title/description/key links) and output location (site-root/llms.txt). This goes beyond the annotations to explain behavior without contradiction.

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

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

The description is two sentences plus a bulleted list of use cases. Every sentence adds value: first sentence defines purpose, second explains process and output, third lists use cases. No fluff 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?

Given low complexity (2 params, no output schema) and good annotations, the description covers core functionality and use cases. It lacks error handling or edge cases (e.g., unreachable URLs), but for this tool it is reasonably 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 both parameters. The description does not add additional meaning beyond the schema; it only recontextualizes the purpose. Baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Generate') and resource ('llms.txt file for any URL') and explains the process (fetches page, extracts title/description/key links) and output format. It distinguishes from siblings like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation for AI crawlers, not just scanning 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 lists three use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. This provides clear when-to-use guidance. It does not explicitly state when not to use or mention alternatives, but the sibling tools are different enough that the use cases suffice.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond this, which is acceptable given the annotations, but no additional transparency is provided.

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

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

The description is extremely concise (2 words) but lacks structure and additional detail that could aid understanding. It is not overly verbose, but brevity comes at the cost of clarity.

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

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

Given the presence of rich annotations and an output schema, the description is adequate but incomplete. It does not explain what a 'pulse' is or what the output contains, relying on the output schema for details.

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?

There are zero parameters, so schema coverage is 100%. The description does not need to add parameter semantics since none exist. Baseline score of 4 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 'Most recent pulse.' is vague but identifies it as the latest entry of something called 'pulse'. It distinguishes from siblings like 'pulse_at' by implying recency, but does not clarify what a pulse is.

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

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

No usage guidance is provided. There is no mention of when to use this tool versus alternatives like 'pulse_at' or other pulse-related tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no further behavioral context (e.g., what 'pulse' means, side effects, or return structure). It does not contradict 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 very short but it is under-specified, not concise. It does not earn its place as it provides minimal information. A single sentence that adds no value is not 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?

Despite having an output schema and annotations, the description fails to clarify core concepts (e.g., what is a 'pulse'), how the tool relates to siblings, or the expected input. It is incomplete for an AI agent to use correctly without additional context.

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

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

Schema description coverage is 0%. The single parameter 'chain_id' is unexplained in the description. The description fails to add any semantic meaning to the parameter beyond its name and type.

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 'Latest pulse in chain' is a tautology of the name and title. It does not define what a 'pulse' is, nor does it distinguish this tool from siblings like 'last_pulse' or 'pulse_at'. The verb and resource are implied but not explicit.

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

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

No guidance on when to use this tool versus alternatives. No context about prerequisites or exclusions. The description lacks any usage 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, destructiveHint. Description adds value by specifying the returned fields and the 'active' filter behavior, and hints at the optional include_inactive parameter.

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 conveys purpose and return fields, second provides usage guidance. 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?

Simple tool with one optional parameter and no output schema. Description fully covers purpose, return fields, and usage context. 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 has 100% coverage with description for include_inactive. Description does not elaborate on the parameter beyond what schema provides, so baseline score of 3 applies.

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

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

Description clearly states it lists active subscriptions and specifies returned fields (id, type, params, etc.). Differentiates from sibling tools subscribe and unsubscribe by being read-only.

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

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

Explicitly advises using before adding more subscriptions or to find an id for cancellation. Provides clear context for when to use, though does not explicitly exclude 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 provide no behavioral hints (all false). The description compensates by disclosing key behaviors: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. This is 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 concise, with each sentence adding new information. It is front-loaded with the core purpose, followed by usage guidance and constraints. No redundant or extraneous content.

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

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

Given that there are 3 parameters (2 required), a fully documented schema, and no output schema, the description is complete. It covers the tool's purpose, when to use it, how to format input, and key constraints (rate limit, quota). No gaps are apparent.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds value by explaining the enum types in context and providing usage examples, but largely aligns with the schema. It offers some extra context (e.g., '1-2 sentences typical') that enhances understanding.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools (none of which are feedback-related) and uses specific verbs and resources.

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 the tool (for bugs, features, data gaps, praise) and provides clear guidance on how to structure feedback (e.g., describe in terms of Pipeworx tools/packs, don't paste user prompts). It also includes limitations (rate-limited, free).

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

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

Adds significant context beyond annotations: self-aggregating signal, derived from CF analytics-engine, no PII, caching behavior (5min-1h). Annotations already cover read-only and idempotent, but description complements well.

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

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

Front-loaded with core purpose and return type. Use cases and additional context are well-organized. Slightly verbose but each sentence adds value.

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

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

No output schema, but description covers return shape (top tools, top packs, total call volume). Sufficient for a simple read-only tool with clear use cases.

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

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

Schema has 100% coverage with enum and description. Description adds semantic nuance about shorter vs longer windows (hot vs steady-state). Baseline 3, plus extra value 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?

The description clearly states it returns top tools, top packs, and total call volume over a window, with specific use cases. It distinguishes itself from sibling tools by focusing on trending/aggregate 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?

Provides three explicit use cases (discovering hot data, confirming canonical tool, checking alignment). Lacks explicit when-not-to-use or alternatives, but the context 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?

The description discloses detailed behavioral traits beyond annotations: internal logic (monotonicity checks, partition sum), response structure (opportunities[], partition_check, fill_check), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB, and conditions when not to trade. Annotations already indicate read-only, idempotent, non-destructive; description adds rich 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 well-structured with front-loaded requirement and clear sections, but it is slightly verbose given the technical details. Every sentence adds value, but some repetition (e.g., explaining fill check in two places). Could be trimmed slightly without losing clarity.

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

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

Given the complexity (two modes, multiple checks, fill validation, response details), the description covers all necessary aspects: when to use, how it works, edge cases, output structure, and trade guidance. No output schema exists, so the description fully explains the return. It even warns against trading when the edge is not realizable.

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

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

Both parameters have schema descriptions (100% coverage) and the description adds significant meaning: for event, it says 'use this if you know the specific Polymarket event' with examples; for topic, it says 'use this if you want to scan related events across the platform' with examples. It also explains how each mode processes the parameter.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two modes (event and topic), each with distinct use, and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk. The verb 'find' and resource 'arbitrage opportunities' are specific.

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 guides when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It states the requirement ('REQUIRES one of event OR topic') and warns that calling with no args fails. It also references polymarket_fill_risk for custom sizing, providing an 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?

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: caching policy (1h KV-level), three model families, edge calculation (net of slippage, with Kelly fractions), diagnostics structure, and Fed bets handling. No contradiction with annotations.

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

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

Well-structured with clear sections and front-loaded purpose, but somewhat verbose with detailed explanations of model families. Could be tightened without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and edge calculations, making it complete for an agent to understand what to expect and how to use the tool effectively.

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

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

All nine parameters are described in the schema (100% coverage). The description adds meaningful context beyond the schema, such as explaining why min_kelly does not filter partition arbs and the rationale behind slippage_pp 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?

Clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, positioned for 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on edge detection without paging hundreds of markets.

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 positions tool for discovering betting opportunities and provides context on tradeable-edge knobs and why segments might be empty. Does not explicitly state when not to use or compare with alternatives, but the detail implicitly guides usage.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive), the description adds critical behavioral details: history bounded by 60-day snapshot TTL, decay computed from daily closes (not intraday), snapshots may have gaps, and response structure with tracked, expired, and snapshot_dates arrays. 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 dense but well-structured: starts with purpose, gives an illustrative analogy, then details parameters and response fields, and ends with limitations. Although somewhat lengthy, every sentence adds essential context for correct usage.

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

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

Given the lack of an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields. It also covers limitations (snapshot TTL, gaps, decay computation). The tool is complex, and the description provides complete guidance for an AI agent to understand and use it effectively.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying 'window' as 'snapshot family' and explaining the 'days' parameter's clamping behavior. This enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It explicitly answers the key question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than just current edges.

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

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

The description provides clear context on when to use the tool, such as comparing a fresh edge against a 3-week-old one. However, it does not explicitly state when not to use it or name specific alternative tools, though the distinction from polymarket_edges is implied. Lacks explicit exclusion criteria.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description fully aligns, adding rich behavioral context: it checks live order-book depth, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction.

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

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

The description is well-structured with clear sections for single-market and basket, front-loaded with the core purpose, and each sentence adds information. It is verbose but justified given the complexity; 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 thoroughly explains return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers prerequisites, risks, and the rationale for using the tool, making it fully self-contained.

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

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

Schema description coverage is 100%, but the description adds value by explaining how parameters like size_usd are interpreted differently in single-market vs basket mode, and the default auto behavior for side in basket. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explicitly stating when to use this tool before acting on their signals.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why with concrete risks (partial basket fills, uncapturable overround). While it doesn't explicitly state when not to use, the context 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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals critical behavioral traits: it explains why spreads can be invalid (mismatched bet shapes, temporal gaps), describes safety fields (compatibility_warning, temporal_alignment) and counters (skipped_cross_type). No contradiction with annotations; it adds substantial transparency.

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

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

The description is moderately long but well-organized with clear sections for modes, response, and safety fields. It is front-loaded with the core purpose. While every sentence adds value, minor tightening could be possible without losing substance.

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

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

Given the lack of an output schema, the description thoroughly covers return values (leg prices, spreads, compatibility_warning, temporal_alignment, skip counters) and edge cases. It explains how to interpret warnings and why pre-mapped topics may not yield tradeable spreads. This provides complete context for an agent to understand the tool's behavior and 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%, so baseline is 3. The description adds value by explaining the relationship between topic and explicit parameters, listing valid topic shortcuts, and clarifying overriding behavior. It could have provided more format examples for explicit tickers, but overall adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by specifying it is specifically about cross-venue comparison, and details two modes (topic shortcuts and explicit tickers). It uses specific verbs and resources.

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

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

The description explains when to use each mode (pre-mapped topics vs. explicit tickers) and provides warnings about invalidity (compatibility_warning, temporal_alignment). It implicitly contrasts with sibling tools by noting that real spreads are rare, but does not explicitly name alternatives like polymarket_arbitrage. Still, it offers solid guidance on 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context (e.g., return format, side effects, or auth requirements), but it does not contradict the annotations.

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

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

The description is extremely concise with no wasted words. However, it may be too terse to be clear. It is well front-loaded but lacks structure and completeness.

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

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

Given the tool's simplicity (one parameter, no nested objects) and presence of an output schema, the description still fails to provide enough context for an agent to understand what the tool does or when to use it. The concept of 'pulse' remains unexplained.

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 parameter 'time_ms' is only described as 'epoch ms' in the description, which clarifies the unit. However, schema coverage is 0%, and the description does not explain the parameter's role or expected format beyond that. Some value is added, but it is minimal.

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 'Pulse at UTC time (epoch ms)' is vague; it does not specify what a 'pulse' is or what the tool does beyond referencing a time parameter. It fails to communicate the resource or action clearly, and the name alone is not self-explanatory.

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 'last_pulse' or other sibling tools. There is no mention of context, 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?

Annotations already indicate safe, read-only, idempotent behavior. The description adds no additional behavioral context (e.g., what happens if pulse not found, or response structure). It repeats the name without value.

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

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

The description is extremely short but sacrifices clarity. It is a single vague phrase that does not earn its place; it could be omitted without loss. Lack of structure or elaboration makes it insufficient.

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 an output schema present, return values are not needed in description. However, the tool is part of a larger system (siblings like chain_info, pulse_at) and the domain concept 'pulse' is left undefined. The description fails to provide minimal context for an agent to understand what the tool does.

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 0%, and the description does not explain the parameters 'chain_id' and 'pulse_id' beyond their names and types. While the example in schema helps, the description fails to add meaning or define the domain concept.

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 'Pulse by chain + pulse index' vaguely states the tool gets a pulse by specifying chain and pulse index. It does not clearly define what a pulse is or distinguish from siblings like 'pulse_at' or 'last_pulse'. The schema clarifies parameters but description alone is vague.

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

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

No guidance on when to use this tool vs alternatives (e.g., 'pulse_at', 'last_pulse', 'latest_in_chain'). The description provides no context for selection, leaving the agent to infer from names and schema.

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 and idempotent. Description adds scoping info (anonymous IP, BYO key hash, account ID) and behavior of omitting key, which is 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?

Three sentences with no fluff. First sentence defines core behavior, second gives purpose/examples, third scope/pairing. 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?

No output schema, but description hints at return type: a value or list of keys. With annotations covering safety, this is sufficient for a simple retrieval 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 100%, so baseline 3. Description clarifies that omitting key lists all keys, adding nuance beyond the schema. This justifies a 4.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It gives specific examples like ticker, address, research notes, and distinguishes from siblings remember and forget.

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

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

Explicitly says to use for looking up context stored earlier without re-deriving. Pairs with remember and forget. Lacks explicit when-not statements, 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?

Description discloses a write operation (mark_read:true mutates read status), contradicting the annotation readOnlyHint=true. This is a critical inconsistency that misleads the agent about state modification.

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

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

Four sentences, front-loaded with purpose, then returned fields, then filtering and side effects, then alternative access. 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?

With no output schema, description adequately describes return fields (source, citation_uri, raw payload). Covers all parameters and provides poll guidance and alternative URL. Complete for the tool's optional-param nature.

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

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

Adds value beyond schema descriptions by providing examples (type: 'sec_8k') and clarifying the effect of mark_read. Schema coverage is 100%, baseline 3, but description enhances understanding.

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

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

Clearly states the tool pulls fired events from subscription feed, specifying the resource and action. Distinguishes from siblings like list_subscriptions and subscribe.

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 guidance on filtering by type and since, explains mark_read behavior, and mentions alternative access via URL. Lacks explicit when-to-use vs siblings, 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 indicate read-only, idempotent, open-world. The description adds valuable behavioral details: it fans out to multiple sources in parallel, provides citation URIs, and notes the USPTO patent search may fail silently due to API sunset. No contradictions with annotations.

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

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

The description is front-loaded with common queries, then states the core purpose, then details the fan-out behavior and returns. It is slightly verbose with multiple query examples, but each sentence contributes meaning. Well-structured for an agent to parse quickly.

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 explicitly states the return structure: grouped changes, total count, and citation URIs. It covers all 3 parameters with examples, explains fallback behavior, and mentions an upcoming soft-failure. This is thorough for a tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for `since` (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), recommending '30d' or '1m' for monitoring, and explaining that `value` can be ticker or CIK. These practical hints go 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 is very specific: it provides the change feed for a company over a defined time window, covering filings, news, and patents. It differentiates from sibling tool `entity_profile` which is for static profiles. Examples of natural language queries make the purpose immediately clear.

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

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

The description explicitly tells when to use this tool versus `entity_profile` for static profiles. It also explains the fallback behavior (GDELT preferred, GNews on rate limit) and the fact that USPTO may soft-fail. It does not provide a comprehensive list of when not to use, but the alternative guidance 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?

Adds behavioral details beyond annotations: key-value scoped by identifier, persistent for authenticated users, 24-hour memory for anonymous. 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?

Concise 4-sentence description, front-loaded with purpose, no filler or repetition.

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

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

Completely addresses the tool's role, parameters, persistence behavior, and relationship to sibling tools for a simple key-value store.

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% (both parameters well-described). Description adds example usage but no additional semantic 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?

The description clearly states the tool saves data for later reuse, with specific examples (ticker, address, preference). It distinguishes itself from siblings recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and directly mentions siblings recall and forget. Lacks explicit when-not-to-use but context is clear.

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

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

Description adds value beyond annotations by explaining that the tool cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups, and detailing the return format for each entity type (including citation URIs). Annotations already provide read/hint/readOnlyHint, so no contradiction.

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

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

Description is moderately concise, front-loaded with examples and key intent. Each sentence adds value, but the list of supported types could be slightly trimmed without losing clarity. Still, it remains focused 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 lack of an output schema, the description adequately explains what is returned for each entity type (ticker, CIK, RxCUI, etc.) and includes citation URIs. It covers the essential behavioral details, though a bit more structure (e.g., that it returns an object) would enhance 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?

Description provides rich context for both parameters: explains the enum values for 'type' with examples, and gives specific input formats for 'value' (ticker, CIK, name for company; brand/generic for drug). Also mentions auto-disambiguation for company, adding meaning beyond the schema's brief descriptions.

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

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

Description uses specific verbs ('resolve', 'look up') and clearly states the resource ('user-spoken NAME to canonical/official identifier'). It distinguishes from sibling tools by explaining that other tools require IDs as input, and provides concrete examples of user queries.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. Does not include explicit when-not-to-use statements, but the context of other tools requiring IDs implies alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it uses ai_visibility_check internally, ranks results by score, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences long, front-loaded with the core action. It contains some redundancy (example and usage context) but remains 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?

No output schema exists, so the description partially compensates by mentioning the ranked list with score, confidence, signal density. However, it omits error handling, failure behavior, limits on entity count, and how the internal AI visibility check is invoked.

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

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

Schema description coverage is 100% and already explains all parameters. The description reinforces the first entity being the 'subject' but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs: 'Compare', 'Probes', 'ranks', 'surfaces'. It clearly identifies the resource (AI visibility across entities) and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on competitive AI-marketing audits.

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

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

The description implies usage for competitive AI-marketing audits and provides an example question. However, it does not explicitly state when NOT to use this tool or mention alternatives like ai_visibility_check for single entity checks.

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

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

Describes graceful degradation of partial failures, mentions potential 5-30s delay on bundlephobia's first measurement, and lists sources_failed. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description adds useful behavioral details.

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?

Information-dense single paragraph with front-loaded purpose. Could be slightly more structured (e.g., bulleted output details), but every sentence serves a purpose and no information 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?

Comprehensively explains return structure with specific fields (summary block, advisories, links, alternatives) and handles edge cases like partial failures. No output schema exists, so description fully covers expectations.

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 describes parameters; description adds value by noting scoped packages are accepted and version defaults to latest. With 100% schema coverage, description still enhances parameter understanding.

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

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

Clearly states it's a composite check for adding npm packages, fanning out across deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific, and the description distinguishes it from siblings by detailing its composite nature.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only scope and directs to deps.dev:version for other ecosystems, providing clear context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context beyond these: specifies that it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation, and returns passages with offsets and similarity scores. This gives the agent a clear understanding of the tool's behavior without contradicting annotations.

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

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

The description is a single paragraph with no wasted words. Each sentence adds distinct value: purpose, use case, pairing, technical details, limitations. It is front-loaded with the key action ('Semantic search INSIDE a fetched record') and then elaborates efficiently.

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

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

Given the high coverage of annotations and schema, the description is complete. It explains the embedding model, windowing, cap, truncation, return format (passages with offsets and scores), and pairing with a sibling tool. No output schema exists, but the description adequately covers return behavior. The tool's complexity is moderate, and the description leaves no major 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%, so the schema already describes each parameter. The description adds value by providing example queries for the 'query' parameter (e.g., 'supply-chain risk') and clarifying the purpose of 'limit' (default 5). It also reinforces the text parameter's 200K char limit. This extra context helps the agent construct effective queries.

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 does semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It distinguishes from sibling tools like ask_pipeworx_grounded by outlining their pairing: fetch with gateway, then search within. The verb 'search' and resource 'record' are 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?

The description explicitly states when to use the tool: 'when the record is too big to cram into the prompt.' It also explains how it pairs with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages.' Additionally, it mentions the 200K char cap and truncation behavior, guiding the agent on limits.

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 a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral context like the 10/day SMS cap, webhook signing secret returned once, and auto-disable after 10 consecutive webhook failures. It does not address idempotency, which the annotation hints at, but that omission is minor given the idempotentHint=true is 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?

The description is a single paragraph that front-loads the core purpose and return value. It contains a lot of detail, which is necessary given the complexity, but could be better structured with bullet points or separate sections for each subscription type. Still, it remains largely concise without redundancy.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple subscription types, optional delivery channels) and no output schema, the description is remarkably complete. It covers all supported types, parameter shapes, delivery options with constraints, authentication requirements, and behavioral notes like the 10/day SMS cap and webhook auto-disable.

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 each parameter: it explains each type enum value with concrete examples (e.g., sec_8k items codes, polymarket_edge topic), details the params object for every type, and elaborates on delivery channels with constraints like phone verification, email validation, and webhook HMAC signing. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and listing supported types with specific examples.

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

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

The description provides explicit guidance on when to use (creating subscriptions) and when not (anonymous or BYO accounts cannot persist). It details supported types, channels, and prerequisites like OAuth and phone verification. However, it does not directly compare to sibling tools like recent_alerts or list_subscriptions for post-subscription usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it draws from a live catalog and returns example questions with tool+argument shape, providing context beyond the annotations.

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

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

The description is front-loaded with common queries and is well-structured. It could be slightly more concise, but every sentence adds value and it avoids redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, input, output shape, and usage guidance. No gaps remain.

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%. The description adds meaning by listing example topics and stating 'omit for a cross-category spread', which is helpful for the agent.

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 is an onboarding entry point that returns category-bucketed example questions. It specifies the verb 'suggest' and resource 'questions/topics', and distinguishes from siblings like ask_pipeworx by noting it teaches how to call meta-tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to pass 'topic' vs omit. This gives clear when-to-use and when-not-to-use 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?

The description adds significant behavioral context beyond annotations: ownership enforcement, row deactivation (not deletion), and impact on historical events. Annotations already indicate non-destructive and idempotent, and the description aligns and enriches these.

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

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

The description is concise (two sentences) and front-loaded with the main action. Every sentence adds value without redundancy.

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

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

For a tool with one parameter, no output schema, and supportive annotations, the description covers ownership, effect on data, and historical availability. It is sufficiently complete 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?

The description adds the key constraint that only the owner's subscriptions can be canceled, which is not explicit in the schema. With 100% schema coverage, this extra context justifies a 4.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and the deactivation behavior.

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 context on when to use the tool (to cancel a subscription) and highlights ownership enforcement and deactivation behavior, which guides usage. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Annotations indicate safe read operations; description adds return format details (verdict types, citation, delta) and processing scope (SEC EDGAR+XBRL). No contradictions.

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

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

Description is moderately long but every sentence adds value, front-loaded with purpose and examples. Minor redundancy in listing alternative phrasings, but overall efficient.

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

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

Given no output schema, description fully explains return values, scope, and replacement of multiple calls. Single-parameter tool with comprehensive coverage.

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

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

Schema has 100% coverage with parameter description; description enriches with examples, natural-language emphasis, and domain specification, adding beyond schema.

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

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

The description explicitly states the tool verifies natural-language claims, with specific examples and domain (company-financial). It distinguishes from siblings by focusing on claim verification and noting it replaces multiple sequential calls.

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

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

Clear guidance to use whenever checking factual correctness, with domain scope specified. Lacks explicit exclusions or alternative tools, but the context is sufficient for typical use.

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