Pexels

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 specifics: default model is free, Anthropic requires a BYO key, and returns per-model data plus a combined view. No contradictions with annotations.

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

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

The description is compact at 4 sentences, front-loaded with the main purpose, and includes all essential information without redundancy. Every sentence contributes meaningfully.

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 {score, confidence, signals, raw_response} + combined view) and covers the tool's purpose, default model, optional key, and use cases. It is complete for an AI agent to understand and invoke the tool.

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

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

Schema coverage is 100%, so each parameter already has a description. The description adds value by providing examples (e.g., 'Pipeworx', 'OpenInvoice') and clarifying the role of each parameter (e.g., '_apiKey' only needed for Anthropic). This goes beyond the schema descriptions.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility 0-100 per model, specifying the default model and optional Anthropic integration. It distinguishes itself from siblings by focusing on AI visibility scoring for marketing audits, pre-launch checks, and competitive monitoring.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use it or compare directly with siblings. The context is clear, but exclusions are absent.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds valuable behavioral context: it routes to 3,751 tools across 886 sources, returns structured answers with stable pipeworx:// citation URIs. This goes beyond annotations without contradicting them.

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

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

The description is longer than average but well-organized. It front-loads the most critical instruction ('PREFER OVER WEB SEARCH'), uses bullet-style enumeration of data sources, and provides clear examples. Every sentence adds value; only minor trimming could be done without loss.

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

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

Given no output schema, the description fully explains what the tool does, how it works (routes to many tools), what kind of answers to expect (structured with citations), and gives numerous examples. It covers the tool's breadth and depth comprehensively for an AI agent.

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

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

Schema coverage is 100% (all aliases for question). The description adds context by explaining the question parameter accepts natural language, providing examples, and noting the aliases. This helps the agent form better queries, exceeding the baseline of 3 for high coverage.

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

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

The description explicitly states the tool answers factual questions using authoritative structured data, and distinguishes itself from web search by saying 'PREFER OVER WEB SEARCH'. It lists specific data domains (SEC filings, FDA drugs, etc.) and provides concrete examples, making the purpose crystal 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 gives explicit guidance: use this tool over web search for factual questions about real-world entities, events, numbers. It includes example queries and a list of trigger phrases like 'what is', 'look up', 'find'. The when-not-to-use is implicit but clear (not for subjective or non-factual queries).

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. The description adds significant behavioral context: it routes to other tools, fills arguments, fetches data, extracts answer using ONLY tool result, and details refusal reasons such as 'not_in_source', 'no_tool_match', etc. No contradiction with annotations.

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

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

The description is a single paragraph, front-loaded with the core purpose, then efficiently covers mechanism, return format, refusal reasons, and usage guidance. Every sentence contributes 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?

Despite no output schema, the description fully specifies the return object shape including fields like answer, evidence, confidence, source, etc. It covers refusal scenarios, cost implication, and usage context. No critical information is missing.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for 'question'. The description adds only 'Your question in natural language' which closely mirrors the schema description. No additional meaning is provided beyond the schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', specifying that it extracts answers only from tool results and returns explicit refusals when data doesn't directly answer. It distinguishes itself from sibling 'ask_pipeworx' by focusing on grounded answering.

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

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

Explicitly guides when to use: 'use whenever an answer will be quoted, cited, or acted on', and when not to: 'prefer ask_pipeworx for casual lookups' due to extra cost. Also mentions the trade-off of one extra LLM call.

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

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

The description extensively discloses behaviors beyond annotations: fan-out patterns, response shapes, resolver contract, parent event extraction, news fallback fields, safety checks (status codes), and resolution rule risk. Annotations (readOnlyHint, idempotentHint) are consistent with the described behavior, and no contradictions exist.

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

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

The description is verbose and contains a wall of text, though it does use capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) to structure information. While every sentence adds value, the length could be reduced for clarity, and the structure could be improved with better formatting.

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 (classifiers, fan-out, response shapes, safety mechanisms) and the absence of an output schema, the description provides comprehensive coverage. It explains edge cases (low-confidence matches, closed markets, wide spreads) and resolution rule risk, leaving few 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 description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific context beyond what the schema provides; it focuses on overall behavior rather than elaborating on individual parameters like `depth` or `include_raw`.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and explicitly lists use cases ('should I bet on X', etc.), distinguishing it from sibling tools like `polymarket_arbitrage` or `polymarket_edges`.

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

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

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also details when the tool short-circuits (low-confidence matches, closed markets) and warns about resolution rule risks. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds no behavioral context beyond what annotations provide, but does not contradict them. With annotations covering safety and side effects, a 3 is appropriate.

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?

Extremely short but lacks essential information. Conciseness is wasted when it omits crucial details like input/output format, resource scope, or usage constraints. The description should be longer to be helpful.

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

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

Given the complexity of media-related sibling tools and the existence of an output schema, the description still fails to clarify whether this tool returns a list, single item, or aggregate. It does not distinguish from photo, video, or search tools. Completeness is low despite output schema covering return values.

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

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

Schema coverage is 0% with no parameter descriptions. The description 'Media in a collection' hints that the 'id' parameter is a collection identifier, but this is ambiguous. The schema examples ('travel-photography', 'wildlife') suggest collection IDs, but the description fails to confirm or explain the parameter's purpose.

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

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

Description 'Media in a collection.' is a tautology of the tool name and title. It does not specify what media type (photo/video), nor how it differs from siblings like photo_search or video_popular, which likely handle similar content. No verb or clear resource scope.

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 context, prerequisites, or alternatives mentioned. Given 33 sibling tools including photo, video, and search variants, the description offers zero guidance on when to use this tool versus others.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions.

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

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

The description is a single paragraph, front-loaded with query examples. Every sentence adds value, but the length is slightly more than minimal. Could be trimmed slightly without losing information.

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

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

Given the complexity of two entity types, multiple metrics, and special handling (off-calendar fiscal years, citation URIs), the description covers essential aspects. No output schema exists, but return format is hinted. Minor gaps like error handling or time period for data prevent a 5.

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

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

Input schema has 100% coverage and describes both parameters. The description further adds meaning: explains the 'type' enum with data sources and provides examples for 'values' (tickers/CIKs for companies, drug names). This goes beyond the schema's basic descriptions.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call. It provides specific query examples and distinguishes itself from sequential lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' when comparing entities, giving a clear usage directive. It lacks explicit 'when not to use', but the positive guidance is strong enough for a 4.

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, and non-destructive hints. The description adds rich behavioral details: parallel routing, structured findings with verbatim evidence, confidence, source, citations, gaps array (no invention), and explicit time estimate. 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-organized: starts with core value proposition, explains mechanism, describes output, and ends with usage notes. Every sentence serves a purpose; 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?

For a complex tool with no output schema, the description covers usage scenarios, behavior, prerequisites, and limitations. Could mention rate limits or pagination, but not essential. Slight additional detail on the 'gaps' array format would improve 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?

Input schema has 100% description coverage for both parameters. The description adds context: decomposition is the point, and depth enum values (quick, standard, thorough) are explained with facet counts. Could be slightly improved by directly linking the depth value to the number of facets in the parameter description.

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

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

The description clearly states the tool performs multi-source research by decomposing questions and routing to sub-tools. It distinguishes from sibling 'ask_pipeworx' by noting the single-lookup alternative, making the purpose unambiguous.

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

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

Explicitly tells when to use (broad or multi-part questions) and when not to (single lookups use ask_pipeworx). Also mentions account requirements, paid plan for 'thorough' depth, and expected timing (15-60s).

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 behavioral context: returns top-N relevant tools with full input schemas and curated examples, ready to call directly. No contradictions observed.

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

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

The description is a single paragraph but is front-loaded with the core purpose in the first sentence. It efficiently lists domains and key behavior (returns top-N with schemas) without superfluous text. Slightly verbose with the list of domains but overall well-structured.

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

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

Without an output schema, the description adequately explains return values: tool names, descriptions, and full input schemas with curated examples. It covers the key aspects for a discovery tool. Could mention pagination or result ordering but is sufficient for an agent.

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

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

Schema coverage is 100% with all parameters documented. The description mentions natural language query and aliases (q, task, search, description) but adds minimal extra nuance beyond the schema. Examples in the schema examples array are helpful but not part of the description text.

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 tools by describing the data or task.' It specifies the verb (find, browse, search) and the resource (tools), and lists concrete domains (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by being a meta-tool for discovery, not a domain-specific tool.

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

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

The description explicitly states when to use the tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on prioritization and context, differentiating it from direct answer retrieval.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false appropriately. The description adds valuable context: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF', notes that 'patents...soft-fails until reactivated', and describes the return structure. This goes beyond the annotations to inform about the tool's parallel fan-out and potential partial failures.

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

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

The description is lengthy but front-loaded with concrete examples and well-organized into sections. Each sentence adds value, detailing data sources, return fields, and constraints. While not perfectly concise, it earns its length by being highly informative.

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

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

Given the tool's complexity (multiple data sources, partial failures, no output schema), the description provides a thorough overview of return values: CIK, company_name, recent_filings (up to 5 with URIs), fundamentals (latest 10-K items), patents (with soft-fail note), news, and LEI. This adequately informs the agent of what to expect, though it could mention the response format explicitly.

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 extra meaning: for 'type', it says 'Only "company" supported today; person/place coming soon.' For 'value', it clarifies ticker or zero-padded CIK and explicitly states 'Names not supported — use resolve_entity first.' This provides actionable guidance beyond the schema's enum and type description.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides example queries and lists the data sources and returned fields. It distinguishes itself from chaining multiple single-pack lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies required inputs (ticker or CIK) and names not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to guidance.

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

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

Annotations clearly mark the tool as readOnly, openWorld, idempotent, and nondestructive. However, the description adds no behavioral details beyond these annotations, such as what data is returned or whether pagination applies. It leaves the agent to infer 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 short, but it fails to be concise in a helpful way. It is under-specified, consisting only of the title itself. Every sentence should earn its place; this one does not.

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 no parameters, the description should at least state the action (e.g., 'List featured collections'). The current description omits the verb, leaving the tool's purpose ambiguous for a zero-parameter read-only 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?

There are no parameters, so schema coverage is effectively 100%. The baseline for zero-parameter tools is 4, as there is nothing additional to describe. The description adds no parameter meaning but does not need to.

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 'Featured collections.' merely restates the title without specifying any verb or resource. It fails to indicate whether the tool lists, retrieves, or manages featured collections, making it a tautology.

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 context is provided. There is no guidance on when to use this tool versus sibling tools like 'collection_media' or 'entity_profile', nor any mention of prerequisites or alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate them. It adds value by explaining why deletion is appropriate, though it doesn't elaborate on irreversibility or logging beyond the annotations.

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

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

The description is concise at two sentences, with no superfluous information. Every sentence provides actionable guidance.

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 delete tool with one parameter, no output schema, and comprehensive annotations, the description fully covers the tool's purpose, usage context, and behavioral aspects. It is complete for its complexity.

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

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

The schema defines the parameter 'key' with a clear description 'Memory key to delete', and the description reinforces this with 'by key'. Since schema coverage is 100%, the description adds minimal additional meaning beyond the schema.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by indicating it is for deletion, contrasting with storage and retrieval.

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

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

The description explicitly specifies when to use the tool: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with 'remember' and 'recall', providing clear context and alternatives.

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

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

The description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.), confirming a read-only, non-destructive operation.

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 followed by a list of use cases, all front-loaded with the primary purpose. Every sentence is necessary and valuable, 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?

For a simple tool with 2 parameters and no output schema, the description fully covers behavior, input, output (single text blob), and intended use. It is self-contained and adequate for an agent to correctly select and invoke the tool.

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

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

The schema covers both parameters with descriptions (100% coverage). The description does not add new information about the parameters beyond confirming the output format, so baseline 3 is appropriate.

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

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

The description specifies the tool generates a 'production-ready llms.txt file for any URL' with explicit mention of target AI crawlers. It clearly distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on producing a standard file for indexing.

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

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

The description lists three concrete use cases (client site indexing, personal project drafting, competitor auditing), providing clear context for when to use the tool. However, it does not explicitly state when not to use it or compare directly with sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context by specifying the return fields and the optional include_inactive parameter, making behavior more transparent 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?

Two well-constructed sentences: the first explains purpose and output, the second provides usage guidance. No unnecessary words. Information is front-loaded and efficiently presented.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains what is returned, when to use it, and the parameter effect. Annotations cover safety and idempotency.

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

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

The schema has 100% coverage for the single parameter (include_inactive) with a clear description. The tool description adds value by referencing 'active' subscriptions, reinforcing the parameter's effect and providing 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 action ('List') and the resource ('the caller's active subscriptions'). It mentions the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe which perform different actions.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This guides the agent on appropriate usage and implies that subscribe/unsubscribe are alternatives for other actions.

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, which are helpful. However, the description adds no behavioral context beyond 'Single photo.' There is no discussion of potential errors, return format, or any constraints not covered by 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 words), but it is underspecified. Conciseness should not sacrifice clarity; here the description omits critical information, making it insufficient for effective tool selection.

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

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

Given the tool has one parameter and an output schema, the description is incomplete. It does not mention what the output contains, any prerequisites, or how to interpret results. The rich annotations compensate partially, but the description still lacks crucial context.

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

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

The input schema has a single required parameter 'id' with no description, and schema description coverage is 0%. The description 'Single photo.' fails to explain what the id parameter represents or how to use it. No compensation for the lack of schema documentation.

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 'Single photo.' is extremely brief and vague. It implies fetching a photo but does not specify the verb (e.g., retrieve) or the resource fully. It fails to distinguish from sibling tools like photo_search or photo_curated, which clearly differentiate their purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention context such as having a specific photo ID, nor does it exclude cases where search or curated views are more appropriate.

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

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

Despite rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) that already convey safety and idempotency, the description adds no behavioral context such as 'returns a fixed set of editor-chosen photos' or 'results may vary over time'. It fails to describe what makes these photos curated.

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 under-specified. 'Curated photos.' does not earn its place because it lacks meaningful information. True conciseness would be efficient without sacrificing 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 many sibling tools and the existence of an output schema, the description is completely inadequate. It does not explain the selection criteria for 'curated' photos, whether the set is static or dynamic, or how it differs from other photo-related tools.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed from the description. Baseline 4 is appropriate as the description adds no param info but doesn't need to.

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 'Curated photos.' is a tautology that merely restates the tool name. It does not specify what 'curated' means (e.g., editorially selected, personalized, trending) or what action the tool performs (e.g., list, retrieve, view). This provides no differentiation from sibling tools like 'photo' or 'photo_search'.

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 given on when to use this tool versus alternatives. The description does not mention contexts, prerequisites, or exclusions, leaving the agent without decision-support information.

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, which convey safety and non-mutability. However, the description adds no behavioral context beyond annotations, missing opportunities to explain query behavior, result scope, or performance characteristics.

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

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

The description is extremely brief but this reflects under-specification rather than conciseness. It lacks structure and fails to front-load essential information, making it unhelpful for agent decision-making.

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 a single parameter and numerous sibling tools, the description is grossly incomplete. It does not differentiate photo_search from similar tools like 'photo' or 'video_search', nor does it set expectations for result set size or behavior.

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

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

Schema description coverage is 0%, yet the description does not explain the single 'query' parameter. No guidance on format, syntax, or expected values is provided, leaving agents to rely solely on schema examples.

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

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

Description is a tautology ('Photo search') that merely echoes the tool name, providing no additional clarity about the action or resource. It fails to specify what searching entails or how it differs from sibling tools like 'photo' or 'photo_curated'.

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. The description offers no context for selection, leaving the agent without direction amid numerous sibling 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?

Description adds critical behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests. Annotations already show readOnlyHint=false and destructiveHint=false, and description aligns 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?

Concise 4-sentence description with clear front-loading: purpose first, then use cases, then behavioral notes. No redundant or filler content; every sentence earns its place.

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

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

Given 3 parameters (including nested object), no output schema, and high sibling diversity, description covers all essential aspects: purpose, when to use, parameter guidance, and behavioral constraints (rate limit, quota, review process). Complete for effective tool selection and invocation.

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

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

Schema coverage is 100%, but description adds value by explaining each enum value ('bug = something broke...') and advising on message specificity (1-2 sentences, 2000 chars max). This goes beyond schema descriptions.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies specific verb+resource and distinguishes from sibling tools (e.g., ask_pipeworx, discover_tools) which handle queries or discovery.

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

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

Explicitly provides when-to-use scenarios: bug, feature/data_gap, praise. Also gives guidance on what to include (tool/pack context) and what not to (end-user prompts). No alternatives needed as feedback is unique.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it is self-aggregating, derived from CF analytics engine, no PII, cached 5min-1h depending on window, and returns just (pack, tool, count) data.

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 and well-structured: a succinct main sentence followed by bullet-pointed use cases. Every sentence adds value without 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?

Despite having no output schema, the description explains what is returned (top tools, top packs, total call volume) and covers data source, caching, and aggregation method. For a simple one-parameter tool, this is fully complete.

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

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

Schema coverage is 100% with the 'window' parameter fully described via enum and description. The description adds extra meaning by explaining that shorter windows surface hot trends and longer windows show steady-state demand, enhancing the schema's built-in explanation.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over recent windows, with specific use cases (discovering hot data, confirming canonical choice, checking alignment). It distinguishes itself among many sibling tools as a trending/aggregation tool.

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

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

The description provides three bullet-pointed use cases that clarify when to use this tool. While it doesn't explicitly state when not to use it, the context is clear and the usage 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?

Annotations already declare read-only and non-destructive. Description adds rich behavioral details: explains internal logic (Jaccard similarity, partition filter, fill check against live CLOB depth), warns about realizable_edge_pp <= 0 meaning overround only at last-trade, and notes placeholders filtering. 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 long but well-structured with clear sections. Front-loads the requirement. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Given the tool's complexity (two modes, multiple checks, fill validation) and no output schema, the description covers almost everything: how to use each mode, what checks are performed, response fields, and even references a sibling tool. No significant gaps.

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

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

Schema coverage is 100% and description adds substantial meaning beyond schema. For event parameter, explains child market walking and partition_check; for topic, explains cross-event scanning and semantic anchor. Goes far beyond the short schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event vs topic) with specific examples, and its purpose is distinct from siblings like polymarket_edges.

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

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

Explicitly tells when to use event (specific market) vs topic (cross-event scanning), warns that no args fails, explains cross-event catches patterns single-event misses, and references polymarket_fill_risk for custom sizing. Provides clear context for agent decision.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral detail: caching policy, model families, edge calculations, diagnostics, and Fed treatment, far exceeding annotation coverage.

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 purpose and effective for a complex tool, but it is lengthy with extensive technical details. Structure and logical flow are good, but some redundancy exists.

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

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

Given no output schema, the description thoroughly explains the response structure (by_segment segments, fed_candidates, diagnostics) and per-opportunity fields. It also covers parameter interactions and caching, making it complete for agent decision-making.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and providing usage context (e.g., 'Set to 5000 to drop thin-book opportunities'), which enhances understanding beyond schema.

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

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

The description explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also clearly identifies the use case 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 ('agents discover opportunities without paging hundreds of markets') but does not explicitly exclude alternative tools or state when not to use it.

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

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

Annotations already declare read-only, idempotent, safe. Description adds: reads from daily snapshots, 60-day TTL, daily closes vs intraday, and response structure. 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?

Purpose is front-loaded. Description is dense but well-organized with sections for response and limits. Could be slightly more concise, but 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 fully explains return fields (tracked, expired, snapshot_dates) with details on fields like trend, decay_pp_per_day, lifespan_days. Also covers limitations (TTL, snapshotting start). Complete for a complex temporal analysis 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 default and clamp for 'days', but description adds possible values '24hr | 1wk | 1mo' for 'window' and explains it as 'snapshot family'. Both parameters gain additional meaning beyond schema.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Answers specific questions about edge age and trend. Distinguishes from sibling tool 'polymarket_edges' by emphasizing temporal analysis.

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

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

Implies usage for assessing edge persistence vs raw edges, contrasting fresh vs old edges. No explicit when-not-to or alternatives, but context from sibling tools and description strongly guide 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 readOnly, idempotent, etc., so the bar is lower. The description adds behavioral context beyond annotations: it explains that the tool walks the order book ladder, returns verdicts (clean|degraded|cannot_fill) and highlights risks like thin_legs and forced_directional_risk in basket mode. 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 relatively long (multiple sentences) but well-structured with section headings for SINGLE-MARKET and BASKET, making it scannable. Each sentence adds necessary information; no fluff. It is front-loaded with the main purpose, and the detailed return fields are justified by the tool's complexity.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description is fairly complete. It explains what each mode returns, includes important edge cases (thin legs, forced directional risk), and references sibling tools for context. Minor omission: it doesn't mention error states or prerequisites beyond parameters, but overall 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 description coverage is 100%, so baseline is 3. The description adds significant value by explaining the relationship between parameters (e.g., requires either 'market' or 'event', defaults for 'side' and 'size_usd', and how 'size_usd' interpretation differs between modes). This helps the agent understand parameter interplay 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 as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', using specific verbs ('checks', 'returns') and resources ('market', 'event'). It distinguishes between single-market and basket modes, and explicitly lists return fields, making the tool's function unambiguous relative to its siblings.

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

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

The description explicitly tells when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround may not be capturable) and warns against partial basket fills converting arbs into directional positions, providing clear usage context.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details compatibility warnings, temporal alignment, and skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is front-loaded with the core idea, but contains many detailed safety field explanations that make it lengthy. Structure is logical, but conciseness could be improved.

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 response fields (spreads, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds meaning by explaining the topic shortcuts, how explicit tickers override topics, and the behavior of parameters in the response context.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two explicit modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing specifically on cross-venue comparison.

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

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

The description explains when to use the tool (to compare prices across venues) and provides warnings about compatibility issues. It implicitly differentiates from alternatives but does not explicitly list when not to use it or suggest sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds scoping (by identifier) and dual behavior (with/without key). 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?

Two sentences with front-loaded main action. First sentence states core function, second adds context and usage. No wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, description adequately explains behavior, scoping, and lifecycle pairing.

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 key parameter with description. Description adds behavior nuance: 'omit to list all keys' and retrieval context. Adds value beyond schema.

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

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

Description clearly states action: retrieve value or list keys. Distinguishes from siblings (remember, forget) by specifying retrieval context and pairing. Provides concrete 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?

Explicitly says when to use: look up stored context without re-deriving. Lists scenarios (ticker, address, notes). Mentions pairing with remember/forget for lifecycle.

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=true and destructiveHint=false, but the description reveals that mark_read:true flags events as read, implying a side effect. The description adds valuable context about return fields and the external endpoint, going beyond annotations.

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

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

The description is well-structured with key actions up front. It is slightly lengthy but each sentence provides useful information without redundancy.

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

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

Given no output schema, the description adequately specifies return fields. It covers filtering, pagination (limit), and an alternative access method. Nearly complete for a read-focused tool.

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

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

Schema coverage is 100%, but the description adds meaning by explaining filter examples ('sec_8k'), ISO timestamp usage, and the effect of mark_read. This enhances understanding beyond the schema definitions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific return fields (source, citation_uri, raw payload) and mentions filtering by type and since, distinguishing it from sibling tools that handle other domains like AI visibility, betting, or entity profiles.

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

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

The description provides clear usage guidance: filtering options (type, since), mark_read behavior, and notes that polls work fine. It also points to an external URL for scripts/dashboards. While it doesn't explicitly state when not to use or compare to siblings, the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it fans out to multiple sources, explains the GDELT→GNews fallback, soft-fails on USPTO due to API sunset, and describes the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). This goes well beyond what annotations provide.

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

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

The description is thorough but well-structured, starting with example queries, then explaining the multi-source fan-out, parameter details, return structure, and finally the alternative tool. Every sentence adds value, and the most critical information (purpose and parameters) is front-loaded.

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

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

Given the absence of an output schema, the description compensates by detailing the return value (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). All three required parameters are fully explained, including examples and typical usage. The description covers behavior, inputs, outputs, and alternatives comprehensively.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying that 'since' accepts ISO dates or relative shorthand (with examples like '7d', '30d', '3m', '1y'), suggests a typical value ('30d' or '1m'), and explains that 'value' can be a ticker or zero-padded CIK. While not required, this additional context improves usability.

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

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

The description clearly identifies the tool as a change feed for a company, aggregating from SEC, GDELT/GNews, and USPTO. It opens with example queries that an agent might use, and explicitly contrasts with the sibling tool 'entity_profile', which provides a static profile. This makes the purpose unambiguous and distinct.

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

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

The description provides explicit guidance on when to use this tool (e.g., 'What's new with X', 'latest on Y') and when to use the alternative 'entity_profile' for static profiles. It also explains the fallback from GDELT to GNews when rate-limited, which helps an agent decide whether to persist. This is exemplary usage guidance.

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

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

Adds context beyond annotations: key-value scoping by identifier, persistence (24 hours for anonymous, permanent for authenticated). No contradiction with idempotentHint or destructiveHint.

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 under 100 words, front-loaded with purpose, then usage, then storage details. Every sentence earns its place with no redundancy.

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

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

Completes the tool's context: explains storage mechanism, scope, persistence, and how to use with recall/forget. No output schema needed for this 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% with good descriptions. Description adds concrete examples (e.g., subject_property, target_ticker) and clarifies value is 'any text', but does not add new constraints 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 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. It distinguishes from sibling tools recall and forget by mentioning pairing with them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides when-not-to-use context via sibling tools recall/forget. Also notes session persistence differences for authenticated vs anonymous.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals that each call cascades through several lookup endpoints internally, replaces 2-3 manual lookups, and specifies exact return fields (ticker, CIK, RxCUI, etc.). This adds significant value beyond the structured annotations and provides full 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 front-loaded with example queries and includes a clear 'Use FIRST' directive. It is slightly verbose with detailed return field descriptions, but every sentence adds value. Could be trimmed slightly, but overall efficient.

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

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

Given the tool has only two parameters and no output schema, the description fully compensates by listing return fields and internal behavior. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the allowed values for 'type' with concrete examples of return data, and elaborates on 'value' with specific input formats (ticker, CIK, brand, generic names). This enriches the schema without redundancy.

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 ('resolve', 'look up') and resources ('canonical/official identifier'), provides clear examples ('What's the ticker for…'), and details supported types with return fields. It clearly distinguishes the tool's purpose from sibling tools by specifying it provides identifiers required by other tools.

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

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

The description explicitly states when to use ('Use FIRST whenever you have a name but need an ID'), providing clear context. It does not mention specific alternatives or exclusions, but the context is sufficient for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. It also explains the optional _apiKey usage. This is good context beyond annotations.

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

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

Two sentences plus a usage statement, front-loaded with the core action. No filler. 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?

Despite lacking an output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers input parameter roles and the underlying mechanism (calling ai_visibility_check). Given the tool's complexity, this is sufficiently complete.

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

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

Schema description coverage is 100%, but the description adds crucial meaning: first entity is 'subject' for narrative, rest are competitors; models default to workers-ai; context disambiguates common names. This greatly enhances parameter understanding beyond the schema alone.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from siblings like ai_visibility_check (single entity probe). It also mentions ranking and surfacing most/least recognized, making purpose unmistakable.

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

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

The description states it's 'useful for competitive AI-marketing audits' and gives an example question, implying when to use. Though it doesn't explicitly say to avoid for single-entity checks, the sibling ai_visibility_check provides that inference. Slightly more explicit exclusion would improve clarity.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description supplements with behavioral details: external API calls (deps.dev, bundlephobia), timing information (bundlephobia's first measurement can take 5-30s), graceful partial failure ('sources_failed will list it if it times out, the rest still returns'). No contradiction with annotations.

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

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

The description is a single paragraph with a logical flow: purpose, what it checks, when to use, ecosystem scope, and failure behavior. Every sentence is essential and adds to understanding. No redundant or extraneous information.

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

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

Given the complexity (multiple external services, timing issues, partial failures) and the lack of an output schema, the description thoroughly explains the return value structure (summary block, advisory detail, links, alternative versions) and edge cases. It covers all critical aspects needed for correct invocation and interpretation.

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 descriptions for both 'package' and 'version'. The description adds context: scoped packages are accepted for 'package', and 'version' defaults to latest when omitted. This adds value beyond the schema, raising the score above the baseline of 3.

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

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

The description clearly states the tool's purpose: a composite check for evaluating an npm package. It uses strong verbs like 'scan' and explicitly lists the services (deps.dev, bundlephobia) and the aspects checked (license, advisories, bundle size, etc.). It distinguishes itself from sibling tools by being the only npm package analysis tool.

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

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

The description gives explicit usage context: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies the ecosystem limitation ('NPM ecosystem only in v1') and directs to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already indicate readOnly and non-destructive. The description adds unique behavioral details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. No contradiction with annotations.

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

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

The description is moderately concise, with each sentence adding value. Slightly longer than minimal but well-structured with key info front-loaded.

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

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

Given no output schema, the description adequately covers return values (passages with offsets and scores), technical details, and constraints. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains return format (character offsets, similarity scores), capping behavior, and default limit. Provides richer context for parameter usage.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings like ask_pipeworx and ask_pipeworx_grounded by describing pairing and alternative usage.

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

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

The description explicitly says when to use (when record is too big for prompt) and suggests pairing with ask_pipeworx_grounded. It lacks explicit when-not-to-use but provides clear context.

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

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

Annotations include readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds creation of a persistent subscription, account requirement, and rate limits, consistent with annotations. 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 detailed but well-organized with appropriate front-loading of core purpose. All information is relevant, though slightly verbose in examples; still 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?

Covers all aspects: purpose, parameters, required auth, delivery channels, limitations, and return value. No output schema, but description adequately explains what is returned. Complete for a subscription creation 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% and description adds detailed examples and explanations for each parameter, including enum values with use cases, type-specific param structures, and delivery channel behavior with security/rate-limit details. 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' with specific verb and resource, and differentiates from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Explicitly states account requirements ('Requires a Pipeworx OAuth account'), delivery channel limitations (phone verification, 10/day cap for SMS), and provides type-specific usage details. Does not explicitly state when to avoid but provides adequate context.

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

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

Description adds behavioral context beyond annotations: returns category-bucketed example questions with exact tool+argument shapes, call with no args for full spread or topic to focus. Annotations already cover safety and idempotency.

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

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

Description is front-loaded with query-like phrases but is somewhat long. However, every sentence adds value, 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?

Complete for an onboarding tool: explains return format, usage scenarios, and parameter behavior. No output schema needed as return is described in words.

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

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

Schema coverage is 100% (one parameter fully described). Description enriches with explicit value list (finance, pharma, etc.) and behavior when omitted, adding meaning beyond the schema.

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

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

The description explicitly states the tool returns example questions for Pipeworx, organized by category, and positions it as the onboarding entry point. It distinguishes from siblings by mentioning meta-tools and discovery use.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains optional topic parameter for focusing and omitting for full spread.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), the description adds valuable context: the row is deactivated not deleted, preserving historical events via recent_alerts, and ownership enforcement.

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

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

Two sentences, front-loaded with the main action, no wasted words.

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

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

Given the single parameter, no output schema, and sufficient annotations, the description fully covers the tool's behavior and constraints.

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%. The description repeats the schema's description of the 'id' parameter as a UUID from subscribe, adding no new meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'cancel' and resource 'subscription', and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and ownership enforcement.

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

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

It specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use, though it does not explicitly state when not to use or list alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details return values (verdict types, structured form, value with citation, delta) and the underlying data sources (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

Description is dense but well-structured: starts with trigger phrases, defines use case, specifies domain, and lists return types. It is informative without being verbose, though could be slightly more concise.

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

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

With one required parameter and no output schema, the description compensates fully by explaining return value structure, limitations (US company-financial claims), and the tool's efficiency over multiple calls. It provides sufficient context for correct usage.

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

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

Schema description coverage is 100% for the single 'claim' parameter, but the description adds value by providing multiple examples and clarifying the expected natural-language format, which goes beyond the schema's minimal description.

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

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

Description uses specific verbs like 'validates natural-language claims against authoritative sources' and provides clear examples of trigger phrases. It distinguishes the tool from siblings by stating it replaces multiple sequential calls, making its purpose unambiguous.

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

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

The description explicitly states when to use ('whenever the agent needs to check factual correctness') and specifies the domain (company-financial claims for US public companies). It lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which provide safety and behavioral traits. However, the description adds no additional behavioral context (e.g., what the output contains, any side effects, or rate limits). It is adequate but uninformative.

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 (three words) but at the cost of clarity. It is under-specified and fails to convey the tool's function effectively. Conciseness should not sacrifice essential information.

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

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

Given the tool's simplicity (single parameter, output schema present), the description is incomplete. It does not explain what the tool does, how to use it, or what to expect. A more complete description would include the action (e.g., 'Retrieves a single video by its ID').

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

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

The input schema has 0% description coverage, so the description must compensate. The only parameter 'id' is self-explanatory, but the description does not clarify its format, constraints, or purpose beyond the schema. A minimal explanation would improve usability.

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 'Single video.' is very vague. It does not specify the action (e.g., retrieve, get) or how it distinguishes from sibling tools like video_search and video_popular. The resource is implied but the purpose is unclear.

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. There is no mention of context, prerequisites, or exclusion criteria, leaving the agent to infer 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, but the description adds no behavioral context beyond the title. It fails to explain what 'popular' means or any traits like sorting, freshness, or scope.

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

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

While extremely concise, the description is under-specified. It consists of two words that add no value over the tool name. Conciseness should not sacrifice informative 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 the presence of an output schema, the description should clarify what 'popular' entails. It does not, leaving ambiguity about the tool's behavior. Incomplete for an agent to understand when to use it.

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

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

With zero parameters and 100% schema coverage, the description is not required to explain parameters. However, it does not add meaningful context about what the output represents beyond a vague label.

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 'Popular videos.' is essentially a tautology of the tool name 'video_popular'. It does not specify what 'popular' means (e.g., trending, most viewed, curated), nor does it distinguish from sibling tools like 'video' or 'video_search'.

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 such as 'video_search' or 'video'. There is no mention of context, prerequisites, or exclusions.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior, so the safety profile is clear. However, the description adds nothing beyond the annotations, missing an opportunity to disclose any additional behavioral traits (e.g., search source, result limits).

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

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

The description is extremely short (two words), which is under-specification rather than conciseness. It lacks essential information and is not front-loaded with value.

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

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

Despite having a simple schema (one parameter) and an output schema, the description fails to cover the search behavior, return format, or any constraints. It is entirely inadequate for the tool's complexity.

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

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

The input schema has 0% description coverage, and the description does not explain the 'query' parameter. It provides no additional meaning beyond the parameter name, which is insufficient for an AI agent to understand usage.

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 'Video search.' is a tautology that merely restates the tool name without specifying what kind of search, scope, or sources are involved. It fails to distinguish the tool from siblings like 'video' or 'video_popular'.

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 (e.g., video_popular, photo_search). The description gives no context for appropriate usage.

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