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 indicate readOnlyHint=true, and the description adds behavioral details about routing to 4,819 tools and returning structured answers with stable citation URIs, providing 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?

Well-structured with front-loaded key takeaway. Some redundancy in listing sources, but each sentence contributes useful 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 tool complexity and full annotations, the description covers purpose, usage, behavior, and examples. Explains output format (structured answer with citation URIs) adequately.

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

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

Schema covers all parameters fully. The description adds natural language guidance and examples for phrasing questions, providing added 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?

The description clearly states the tool answers factual questions using structured data from verified sources. It differentiates from siblings by specifying when to use alternatives like ask_pipeworx_grounded or deep_research.

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

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

Explicitly says to prefer over web search for factual questions, provides examples, and gives guidance on when to step up to other tools. Also declares it the default entry point.

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?

Extends annotations (readOnlyHint, etc.) with detailed behavioral specifics: refusal reasons list, return fields, single-sourcing from tool result, and extra LLM call cost. 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?

Front-loaded with core purpose, each sentence adds value. Slightly long but justified by the comprehensive information needed.

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 necessary aspects: purpose, trade-offs, refusal reasons, return format, usage context. No output schema, but description fully explains return structure.

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

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

Schema covers 100% of parameters with descriptions. The description adds minimal beyond stating that question is in natural language and aliases exist. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: hallucination-resistant answer extraction for high-stakes reads. It uses specific verbs ('extracts', 'fetches', 'returns') and clearly distinguishes from sibling 'ask_pipeworx' by emphasizing groundedness and explicit refusal.

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

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

Provides explicit guidance on when to use ('when answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). Includes cost trade-off and alternatives context.

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

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

The description 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, openWorldHint, idempotentHint, and destructiveHint. The description adds 'returns paginated mixed media objects with URLs and metadata', which provides behavioral context about pagination and content beyond what annotations cover. No contradiction.

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

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

The description is a single front-loaded sentence with no unnecessary words. It conveys purpose, resource, and return type efficiently.

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

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

With an output schema present, the description need not detail return structure. It mentions pagination and content type, which is sufficient for a simple fetch tool. It lacks mention of pagination details but these are likely in the output schema.

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

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

Schema coverage is 0%, so the description must compensate. It mentions 'by string id' and examples exist in the schema, but it does not specify the format or type of the collection id (e.g., string name vs numeric ID). This is adequate but not fully detailed.

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 'Fetch all photos and videos inside a specific Pexels collection', specifying the verb 'Fetch' and the resource 'photos and videos in a collection'. It distinguishes from siblings like 'photo' or 'photo_search' by explicitly mentioning 'collection' and mixed media.

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

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

The description implies usage with 'by string id', and sibling names like 'featured_collections' and individual media tools help differentiate contexts. However, it does not explicitly state when not to use this tool or provide direct comparisons to alternatives.

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

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

Annotations already indicate 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 mark read-only, idempotent, open-world. Description adds account requirement, typical latency (15-60s), output format (findings packet with gaps[]), and that it never invents data. 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?

Long description (multiple paragraphs) with important information front-loaded (account requirement, alternatives). However, could be trimmed slightly without losing clarity.

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

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

Given no output schema and 2 parameters, the description covers account, siblings, use cases, limitations, time estimate, output structure, and behavioral traits. Fully informs agent decision.

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

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

Schema covers both parameters (100% coverage) with descriptions. Description reinforces that question should be natural language and broad/multi-part, and explains depth enum values (quick=3, etc.). Adds modest extra 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 the tool performs multi-source research across structured data sources, decomposes questions into facets, and runs parallel tools. It distinguishes itself from siblings like ask_pipeworx and provides specific use-case examples like 'compare X and Y's regulatory + financial exposure'.

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

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

Explicit guidance: when to use (broad/multi-part structured questions), when not (single lookup → ask_pipeworx, breaking news → ask_pipeworx). Also notes account requirement and paid plan for thorough depth.

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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by specifying the exact return fields (id, title, description, media counts), compensating for lack of behavioral details 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?

Single sentence is concise and front-loaded with verb and resource, followed by return fields. 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 no parameters, full annotations, and presence of an output schema, the description adequately covers the tool's functionality and return structure. No missing context for a simple listing tool.

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

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

Input schema has no parameters and schema coverage is 100%. Description correctly handles this by focusing on what the tool returns, adding clear meaning without needing parameter info.

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

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

Description clearly states it lists Pexels' featured curated collections and specifies returned fields (id, title, description, media counts). It distinguishes from sibling tools like 'collection_media' and 'photo_curated' which serve different 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?

Description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or context. Usage is implied but not formally explained.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specific details about returned fields (e.g., all sized image URLs, photographer info) beyond what annotations provide, without any contradiction.

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

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

The description is a single sentence that is slightly long but front-loaded with the core purpose. It could be split for readability, but no information is wasted.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers all necessary context: what is returned, key fields, and the photo ID requirement. No further details are needed.

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

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

The only parameter (id) is described as 'numeric id' in the description, compensating for 0% schema coverage. The example further clarifies. While brief, it is sufficient for the simple single-parameter tool.

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 ('Fetch') and resource ('full metadata for a single Pexels photo'), listing key return fields (sized image URLs, photographer, dimensions, alt text). It clearly distinguishes from siblings like 'photo_search' and 'photo_curated' which serve different 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?

The description implies use when needing detailed info for a specific photo ID, but does not explicitly contrast with siblings or state when not to use. It is clear but lacks comparative guidance.

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

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

Annotations already convey readOnly, idempotent, openWorld, and non-destructive hints. The description adds value by detailing the return structure (multiple image sizes, photographer info) and pagination, which are beyond the annotation scope. 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, front-loaded sentence. It uses an imperative verb ('Fetch') and immediately states the core function. Every word is meaningful 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?

For a parameterless tool with annotations and an output schema, the description sufficiently covers purpose and return details. It mentions pagination but does not explain how to paginate (e.g., page parameter), which is a minor gap.

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

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

There are zero parameters, and schema description coverage is 100% (empty schema). The description does not need to explain parameters. It appropriately omits param info, earning a baseline 4.

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

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

The description clearly specifies the action ('Fetch'), the data source ('Pexels' curated editorial photo feed'), and the output details ('paginated photo objects with image URLs in multiple sizes and photographer info'). It is distinct from siblings like 'photo_search' which implies search, and 'photo' which is singular.

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 the basic purpose but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'photo_search' for non-editorial photos, 'photo' for a single photo). Usage context is implied but not stated.

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, and idempotent behavior. Description adds value by specifying output details (paginated results, image sizes, photographer name, attribution link) 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?

Single sentence, front-loaded with key information, 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 one-parameter search tool, the description covers required input, output structure, and return format. Slightly incomplete on pagination details, but output schema likely handles that.

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 0% schema coverage, the description only states 'by keyword (required)' and provides examples, but does not explain query optimization or format expectations. Minimal added meaning.

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

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

Description clearly states the verb 'Search', resource 'Pexels photos', and required input 'keyword', distinguishing it from siblings like 'photo' (single photo) and '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?

The description implies usage for keyword-based photo search but offers no explicit guidance on when to prefer this over sibling tools like 'photo_curated' or 'photo'.

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 declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details beyond these, such as the fill check logic, semantic anchor with Jaccard similarity, and partition filter with placeholder handling. No contradiction with annotations.

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

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

The description is well-structured with sections and front-loaded with the primary purpose. While it is lengthy, every sentence adds value. It could be slightly more concise, but the structure aids readability.

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

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

Given the tool's complexity and lack of output schema, the description covers usage, parameters, behavioral checks, response format, and references to sibling tools. It is nearly complete; the only minor gap is the response format for trending scan mode, which is implied but not explicit.

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

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

Schema coverage is 100% with both parameters described. The main description adds significant meaning: it explains the difference between event and topic modes, provides example values, and describes the behavior of each mode. This goes well beyond the baseline 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk by explicitly mentioning it for custom sizing.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It explains the benefits of cross-event mode and includes a fill check section warning when not to trade. It also directs users to polymarket_fill_risk for custom sizing.

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 indicate read-only, idempotent, and non-destructive behavior. Description adds value by detailing the exact content returned (file URLs, resolutions, duration, etc.), which goes 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?

Single sentence, front-loaded, concise, with no extraneous information. Every word contributes to understanding.

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

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

With an output schema present and simple tool complexity, the description is nearly complete. Lacks mention of error conditions or prerequisites, but these are implied by the tool's nature.

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

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

Schema coverage is 0%, so description must compensate. Description mentions 'by numeric id' but provides no additional detail about the id parameter (e.g., range, format, or source). Minimal value added over the schema's property definition.

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

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

Description clearly states it fetches full metadata for a single Pexels video by numeric id, specifying included fields (file URLs, resolutions, duration, width, height, videographer attribution). It distinguishes from sibling tools like video_search 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?

Description implies usage when needing detailed metadata for a specific video by id. While it doesn't explicitly state when not to use or mention alternatives, the context of sibling tools (video_search, etc.) provides clear differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying pagination and the nature of returned objects (file URLs, resolutions, etc.), which is beyond what annotations provide. No contradictions.

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

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

Single sentence that is front-loaded with the action ('Fetch Pexels' popular video feed'), efficiently conveys purpose and return details without extraneous words.

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

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

Given no parameters and existence of an output schema, the description adequately explains the return content. It lacks explicit pagination instructions, but with output schema likely covering that, completeness is high for a simple feed 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?

No parameters exist (0 params, 100% schema coverage). Baseline score of 4 applies because description need not add parameter info, and it does not misrepresent any.

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 fetches the popular video feed from Pexels, lists return content (video objects, file URLs, resolution, duration, videographer info), and distinguishes from siblings like video_search which is likely a search 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?

Description does not explicitly state when to use this tool vs alternatives. It is implied that it is for fetching popular videos rather than searching, but no direct guidance or exclusions are provided.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by mentioning pagination, multiple resolution URLs, duration, and videographer info, which go beyond the annotations. No contradiction.

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

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

The description is a single efficient sentence (15 words) with no fluff. It front-loads the core action and key details.

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

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

For a simple tool with one parameter and an output schema, the description covers purpose, required input, and key output characteristics (paginated, multiple resolutions, etc.). It is fully sufficient.

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

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

Schema coverage is 0% for the single parameter 'query'. The description calls it a 'keyword', adding meaning not in the schema. However, it lacks elaboration on format or valid inputs, so it is adequate but not rich.

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 'Search Pexels videos by keyword (required)', specifying the verb, resource, and requirement. It also distinguishes from siblings like 'video' and 'video_popular' by implying this is for keyword-based 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?

The description implies usage when a keyword is available, but it does not explicitly state when to use or avoid this tool vs alternatives like 'video' or 'video_popular'. Some guidance can be inferred from context.

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