Pypi Stats

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, no destruction. Description adds beyond this: probes multiple models, returns per-model {score, confidence, signals, raw_response} + combined view, default is free, Anthropic requires API key passed through. No contradictions.

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

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

Three sentences pack verb+resource+scope, usage, return format, and parameter hints. Front-loaded and efficient 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?

Given 4 params, no output schema, and no enums, the description covers tool purpose, parameters, return structure, use cases, and cost implications. 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 has 100% description coverage for all 4 parameters. Description adds practical context: default model is Workers AI Llama-3.3-70b (free), Anthropic requires api key, context helps disambiguate. 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 it 'probes one or more LLMs for what they know' and 'score visibility (0-100) per model.' Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on AI model awareness rather than general web presence.

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

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

Explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Provides guidance on default model vs. Anthropic (BYO key). Could be improved by noting when NOT to use (e.g., for fact-checking) but overall 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, open-world, idempotent, and non-destructive behavior. Description adds context about returning structured answers with stable citation URIs and routing to many sources, but does not cover potential rate limits or detailed operational quirks.

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 a clear front-loading of key advice, followed by examples and sibling differentiation. While a bit lengthy, every part contributes to understanding the tool's usage and context.

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 effectively covers purpose, usage, and differentiation. It mentions return value (structured answer with citation URIs), but lacks explicit return format details.

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

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

Schema coverage is 100%, so the description is not required to add parameter details. The description focuses on overall purpose rather than parameter semantics, which is acceptable given high schema coverage.

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

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

The description clearly states that the tool routes questions to a vast set of tools across verified sources to answer factual questions with citations. It provides specific examples and distinguishes from sibling tools like ask_pipeworx_grounded and 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 states when to use this tool over alternatives: 'PREFER OVER WEB SEARCH' for authoritative structured data, and provides examples of when to step up to other tools. Includes query patterns like 'what is', 'look up', etc.

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 goes beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing the return structure including fields like answer, evidence, confidence, source, fetched_at, and refusal_reason. It also explains the possible refusal reasons. 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 thorough and well-structured, but could be slightly more concise. However, it is front-loaded with the key purpose and usage, and every sentence adds meaningful information.

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

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

Despite no output schema, the description fully explains the return format and error conditions. It covers complex routing across 4,774 tools and 1,242 sources, making it 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% with descriptions for 'question' and alias parameters. The description adds value by explaining that the parameter accepts natural language and lists multiple alias forms (query, q, prompt, text, input), which is not explicitly in the schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads.' It explains the process of routing, argument filling, data fetching, and extracting answers only from tool results. It distinguishes itself from the sibling tool 'ask_pipeworx' by specifying it is for factual, high-stakes queries, while 'ask_pipeworx' is for casual lookups.

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

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

Explicit guidance on when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also advises to prefer 'ask_pipeworx' for casual lookups and mentions the extra cost of one LLM call.

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

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

The description extensively details behavioral traits beyond annotations: resolver contract, parent event extractor, news fields with fallback handling, safety checks for low-confidence matches, closed markets, wide spreads, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and includes extensive examples and edge cases. While it is well-structured with clear sections, it is not concise and could be significantly shortened without losing essential information.

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

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

Given the tool's complexity, the description is highly complete. It covers resolution confidence, parent events, news failure modes, safety short-circuits, and response shapes. Without an output schema, the description adequately explains return values and nuances.

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 examples and clarifications for each parameter (e.g., market input types, depth levels, include_raw usage). This adds value beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and provides a comprehensive list of classifiers. It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on single bet research.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides guidance on inspecting market_match_confidence and other fields. However, it does not explicitly state when not to use the tool or compare with siblings, though siblings exist.

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, so agent knows it's safe. Description adds valuable context: pulls latest financials from SEC EDGAR, handles off-calendar fiscal years correctly, results sorted by primary metric, returns citation URIs. Describes behavior 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?

Description is concise (5-6 sentences) and well-structured. It front-loads with common query phrases, then states core purpose, then adds details about data sources and behavior. Every sentence contributes valuable 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?

Despite no output schema, description explains returns 'paired data + pipeworx:// citation URIs per entity' and mentions results are sorted by primary metric. This is sufficient for agent understanding. Could mention error handling or missing data, but overall complete for a comparison 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 has 100% coverage: both parameters are described. Description adds meaning: explains that 'type' can be 'company' or 'drug' and gives examples for 'values' (tickers/CIKs for company, drug names). It also details what data is pulled per type, which is not in 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and specifies resources ('companies or drugs'). It distinguishes from sequential single-pack lookups, which are sibling tools, by explicitly stating preference. Gives examples of common user queries.

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

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

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states it replaces 8-15 sequential lookups. This provides clear guidance on when to use. However, it does not explicitly mention when not to use or list alternatives beyond sequential lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds critical context: account requirements, parallel decomposition, return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[]), the fact that it returns empty gaps for unstructured topics, and expected 15-60s response time. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading critical prerequisites (account required, alternative). Each sentence adds unique value, from parallelism to return format to limitations. Minor reduction possible (e.g., repeating 'ask_pipeworx' multiple times), but overall efficient for the complexity.

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

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

Given the tool's complexity (2 params, full schema coverage, annotations covering safety, no output schema), the description is complete. It covers scope, usage boundaries, return format, and behavioral nuances. The agent can confidently decide when and how to invoke this tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the enum values for 'depth' (quick=3, standard=5, thorough=8) and clarifying that 'question' can be broad or multi-part, which is not obvious from the schema alone. A 4 reflects meaningful addition beyond the schema.

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

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

The description uses specific verbs ('decomposes', 'routes', 'returns') and clearly identifies the resource ('Pipeworx's 1242 STRUCTURED data sources'). It distinguishes itself from sibling tools like ask_pipeworx, ask_pipeworx_grounded, and validate_claim by emphasizing parallel multi-source research over structured data, not open-web 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?

Explicitly states when to use (broad/multi-part questions over structured data) and when not to use (single lookup → ask_pipeworx; breaking/current news → ask_pipeworx). Provides account requirement and fallback tool for non-signed-in users. No ambiguity.

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, covering safety. The description adds value by stating that results include 'full input schemas (with curated examples)' and that each result 'is ready to call directly, no second schema lookup needed.' It also mentions returning 'top-N most relevant tools.' This adds behavioral context beyond annotations.

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

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

The description is a single paragraph that front-loads the core purpose: 'Find tools by describing the data or task.' It then efficiently lists domains and key features. While it is somewhat long, every sentence adds value. Could be slightly more concise, 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?

With no output schema and 6 parameters (1 required), the description compensates by stating it returns 'top-N most relevant tools with names, descriptions, and full input schemas.' It also specifies default and max limit (20, 50). This is adequate for a discovery tool, though it does not detail the exact format of results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new information about parameters beyond what the schema provides (e.g., aliases for query are already listed in the schema properties). The description includes examples of query values, which is helpful but adds minimal semantic depth.

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 lists many example domains (SEC filings, financials, etc.), distinguishing this discovery tool from sibling tools like 'ask_pipeworx' or 'entity_profile' which serve specific 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also describes when to use: 'when you need to browse, search, look up, or discover what tools exist.' This provides clear context for usage.

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

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

The description extensively details the tool's behavior beyond annotations: it fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies return fields, mentions a soft-fail for patents, and notes it makes a parallel call. No contradictions with annotations.

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

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

The description is front-loaded with common use case examples and well-structured with enumerations. It is somewhat dense but every sentence adds information. Could be slightly more concise, but it's effective.

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, no output schema), the description is remarkably complete. It lists all return components, mentions URIs, soft-fail, and parallel call. It lacks only minor details like rate limits, but annotations mitigate 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?

Schema coverage is 100% so baseline is 3. The description adds value by clarifying the value parameter format (ticker or CIK, not names) with examples, and reiterating the fallback to resolve_entity. This provides helpful context beyond the schema.

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

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

The description clearly states the tool's purpose: generating a full cross-source profile of US public companies. It provides specific verb-resource pairs like 'tell me about X' and distinguishes from siblings by explicitly preferring this tool over chaining single-pack lookups.

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

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

The description gives explicit guidance on when to use this tool (for holistic company profiles) and when not to (for names, recommending use resolve_entity first). It also provides example queries and indicates that this tool is preferred over alternative chaining approaches.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not discuss idempotency or behavior on missing keys. 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?

Two sentences with no filler. Front-loaded with the action and purpose, then usage guidance. Every sentence adds value.

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

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

Given low complexity, comprehensive annotations, and no output schema needed, the description fully covers purpose, usage, and pairing with siblings. No gaps.

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

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

Schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete'. The description does not add new semantic information beyond what is in the schema, meeting the baseline.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes from sibling tools like 'remember' and 'recall' by specifying deletion rather than storage or 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?

Provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', giving clear context about alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral details (fetches page, extracts title/description/key links, emits markdown) which complements annotations well. 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?

Four sentences, front-loaded with the main action, no unnecessary words. Every sentence adds value: purpose, process, output format, and use cases.

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

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

Given the simple tool with only two parameters, full schema coverage, and comprehensive annotations, the description is complete enough for an agent to understand and 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 clear parameter descriptions. The tool description does not add additional meaning beyond the schema for parameters; it only gives high-level context of what the tool does with the fetched content.

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 generates an llms.txt file for a given URL, specifying the output format and listing use cases and supported AI crawlers. Distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than 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?

Provides explicit use cases (client indexing, own project drafting, competitor auditing) but does not mention when to avoid this tool or suggest alternatives. The context is clear but lacks explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds that it returns specific fields and mentions the include_inactive parameter indirectly by stating 'active subscriptions,' but does not elaborate on behavior 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?

Two concise sentences that front-load the main action and key details. 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?

Tool has one optional parameter and no output schema. Description sufficiently covers the return fields and usage context, making it complete for an AI agent to use effectively.

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

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

Schema coverage is 100% with a clear description of the include_inactive parameter. Description mentions 'active subscriptions' but does not add extra semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states it lists the caller's active subscriptions and enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count), leaving no ambiguity about tool purpose.

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

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

Provides explicit guidance on when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This is helpful context, though it does not explicitly contrast 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 false, indicating a safe, idempotent read operation. The description adds value by specifying the external data source (pypistats.org) and the return format (per-day download counts), which are behavioral traits beyond what annotations provide.

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

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

The description consists of two clear, front-loaded sentences. Every sentence provides essential information without redundancy. It efficiently covers purpose, source, optional filter, and return format.

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

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

Given the tool's simplicity (2 parameters, output schema exists), the description covers the source, data type, return format, and optional filter. It could mention date range or limitations, but overall it provides sufficient context for an agent to understand the tool's behavior.

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

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

With 0% schema description coverage, the description must explain parameter meanings. It explains 'mirrors=false' as excluding mirror traffic, which adds value. However, it does not explicitly describe the 'package' parameter's format or constraints beyond the tool's purpose, leaving a gap. The explanation is adequate but not comprehensive.

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 'Fetch', the resource 'daily PyPI download timeseries for a package', and the source 'from pypistats.org'. It also notes the optional filter and return format, making the tool's purpose distinct from any sibling 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 implies the tool should be used to get PyPI download stats for a package, but it does not explicitly state when not to use it or mention any alternatives. Since no sibling tool provides similar functionality, the lack of explicit guidance is acceptable but still leaves room for improvement.

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

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

Discloses rate limits (5 per identifier per day) and that it's free and doesn't count against tool-call quota. No contradiction with annotations (readOnlyHint=false is appropriate for a feedback submission).

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 at 4-5 sentences, front-loaded with purpose, then usage, constraints, and quota info. Every sentence adds value without fluff.

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

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

Given no output schema, the description covers what happens (team reads daily, roadmap impact) and all input details (rate limits, quota, message guidelines). Complete for a feedback 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 value by explaining the enum types in plain language and providing guidance on message content (specific, avoid prompts). The description enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Tell' and the resource 'Pipeworx team' with specific feedback types (bug, feature, data_gap, praise). It distinguishes the tool's purpose from siblings by being a dedicated feedback channel.

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

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

Explicitly states when to use (for bugs, missing features, praise) and what not to do (avoid pasting end-user prompts, describe in tool/pack terms). Provides clear context for 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 read-only, idempotent, non-destructive behavior. The description adds valuable context: data source ('CF analytics-engine'), no PII, and caching details (5min-1h). This goes beyond annotations without contradicting them, providing a complete behavioral picture.

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 (three sentences plus a bulleted list) with no wasted words. It is front-loaded with the main purpose, followed by return details and use cases. Every sentence serves a clear function.

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

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

Given the simplicity (one optional param, no output schema, rich annotations), the description covers all necessary aspects: input meaning, output content, use cases, data origin, privacy, and caching. No critical information is missing.

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

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

Schema coverage is 100% with a well-described enum parameter. The description further reinforces the meaning of the window parameter by linking it to recency vs. steady-state. This adds semantic value beyond the schema's description.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows. It uses specific verbs ('returns', 'calling on') and differentiates from sibling tools like 'ask_pipeworx' (query) and 'discover_tools' (listing). This makes the purpose distinct and unambiguous.

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

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

The description provides three explicit use cases for when to use this tool, e.g., discovering hot data sources or confirming a popular tool. It explains the trade-off between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly state when not to use it or suggest alternatives, leaving a minor gap.

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 comprehensively explains the algorithmic behavior: monotonicity checks, partition-sum comparisons, semantic anchoring (Jaccard threshold), placeholder filtering, and fill check integration. It discloses output structure and actionable signals, complementing annotations that indicate read-only, idempotent, non-destructive behavior.

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

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

The description is detailed but well-structured, front-loading the core purpose and using clear separations for modes. Although lengthy, each sentence adds value, covering modes, algorithms, filters, and outputs.

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

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

Despite lacking an output schema, the description fully specifies the response structure (opportunities[], partition_check details) and integration with fill_check. It covers all major behavioral aspects, making it complete for a complex arbitrage detection 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?

Both parameters ('event' and 'topic') are described in the schema with examples. The description adds contextual guidance on when to use each mode and what they do (e.g., walks child markets, computes partition_check), going beyond the schema's field-level descriptions.

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

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

The description clearly states the tool's purpose: detecting arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three usage modes (no args, event, topic) and distinguishes itself from sibling tools like polymarket_fill_risk.

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

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

The description explicitly advises when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It recommends event mode and warns against acting on signals without fill check, referencing 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?

The description adds significant behavioral context beyond annotations: it explains the three model families, the caching policy (1h at KV level), the diagnostics structure for empty segments, and the algorithmic details (e.g., per-leg Kelly, profit conditions). This is valuable since annotations already indicate read-only, idempotent behavior, so the description enriches understanding without contradiction.

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

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

The description is very long and dense, lacking clear structure. It is a single paragraph that mixes high-level purpose, algorithmic details, and output format. While comprehensive, it sacrifices conciseness and could benefit from breaking into sections (e.g., purpose, models, output, caching).

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the three response segments, the diagnostic fields so callers understand why a segment is empty, the caching policy, and the algorithmic justification for models. This fully compensates for the missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the role of 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and the meaning of min_kelly as half-Kelly fraction. This provides context that helps agents use the parameters effectively, moving above baseline.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also includes a use-case phrase 'Built for what should I bet on today.' While it distinguishes from siblings implicitly by focusing on 'edges' vs. 'arbitrage', it does not explicitly differentiate from the sibling polymarket_arbitrage.

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

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

The description provides usage context: agents can discover opportunities without paging through many markets. It mentions Fed bets are included but excluded from ranking with a caveat. However, it does not explicitly state when not to use this tool or compare directly to alternatives like polymarket_arbitrage or bet_research.

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

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

Adds significant behavioral details beyond readOnlyHint annotations: explains response structure (tracked, expired, snapshot_dates), limits (60-day TTL, daily closes), and how decay is computed. 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?

Front-loaded with purpose, then details. Somewhat verbose but all sentences add value. Could be slightly more concise, but effectively communicates complex behavior.

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

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

Despite no output schema, the description fully explains all response fields (tracked, expired, snapshot_dates) and their subfields. Schema covers params completely. Description is self-contained for an agent to understand usage and output.

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

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

Schema coverage is 100%, but description adds value by explaining defaults (14 days, 1wk) and clamping (2-30) for days, and that window refers to snapshot family. Also clarifies how parameters affect the response.

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 provides edge persistence and decay telemetry from daily snapshots, answering a specific question. It distinguishes from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

Provides context on when to use (to differentiate between fresh and old wide edges) and implies limits (60-day TTL, not intraday). Does not explicitly name alternative tools, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: it walks the ladder, returns fill details, and warns about partial fills becoming unhedged. It does not contradict any annotation. The added detail is valuable but not essential given 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 long but dense and well-structured with headings for SINGLE-MARKET and BASKET. Every sentence provides necessary information. While it could be slightly tighter, the structure and front-loading of requirements (REQUIRES one of...) make it efficient for an AI agent.

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

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

Given the tool's complexity (two modes, multiple return fields, important caveats), the description is extremely complete. It covers input requirements, behavioral details, return values (without an output schema), and practical warnings about partial fills and directional risk. No gaps are apparent.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it explains the two modes (market vs event), side options with defaults, interpretation of size_usd for buys vs sells and for basket vs single, and default side for baskets (auto from partition sum). This goes well beyond the schema's basic parameter descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket) and lists the return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and a verdict. It also distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by explaining when to use this tool before acting on their signals.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale—theoretical overround on thin books is not capturable and partial basket fills convert an arb into an unhedged directional position—offering clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate read-only and idempotent. The description goes beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains conditions under which spreads are meaningless. No contradictions with annotations.

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

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

The description is long but well-structured: starts with a one-sentence summary, then breaks into modes, response, and safety fields. Every sentence provides critical information; however, slight trimming could improve conciseness without losing content.

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

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

Despite no output schema, the description thoroughly explains the response format, including raw prices, matched spreads, and safety fields. It covers compatibility warnings, temporal alignment, and skipped types. The description is complete for the tool's complexity and compensates for the lack of output schema.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds value by explaining the two modes, how parameters override each other, and provides examples. This exceeds the baseline of 3 for high-coverage schemas.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself by explaining two modes (topic shortcuts and explicit pairs) and details the response content, making the purpose specific and unambiguous.

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

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

The description explicitly outlines two usage modes (topic and explicit) and provides warnings about compatibility and when spreads are invalid. It advises that most pre-mapped topics are not tradeable, guiding against misuse. This meets the highest bar for 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and side effects. The description adds that it returns per-version download counts, but doesn't disclose the source or any potential rate limits 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?

Two sentences, 17 words, front-loaded with the verb and resource, no redundant information.

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

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

Given the tool's simplicity (one parameter, simple API), the description covers the purpose and return values adequately. The presence of an output schema further reduces the need to describe the return format in the description.

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 description coverage, the description compensatingly explains that the 'package' parameter is the name of the PyPI package, providing meaning beyond the bare 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 verb 'Fetch' and the resource 'PyPI download breakdown for a package by Python major version' and distinguishes from sibling 'python_minor' which handles minor versions.

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 PyPI major version breakdown, providing clear context for when to use it, but does not explicitly mention when not to use it 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?

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds value by specifying the data source (pypistats.org) and the return format (per-version download counts), which is helpful context beyond the structured metadata.

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

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

The description is extremely concise: two sentences, no fluff. It front-loads the action and resource, and every sentence adds value.

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

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

Given the tool's simplicity (one parameter, output schema exists, annotations cover safety), the description is nearly complete. It explains the source and output. A minor gap is the lack of differentiation from python_major, but this does not significantly hinder completeness.

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

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

The single parameter 'package' is self-explanatory from the tool name and description. Schema coverage is 0% but the schema includes an example ('scipy'). The description does not add further clarification on parameter format, but the minimal context is sufficient for this straightforward parameter.

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

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

The description clearly states the verb 'Fetch', the resource 'PyPI download breakdown for a package by Python minor version', the source 'from pypistats.org', and the output 'Returns per-version download counts'. It effectively distinguishes from the sibling python_major by specifying 'minor version' (e.g., 3.10, 3.11).

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 fetching minor version breakdowns but does not explicitly state when to use this tool versus alternatives like python_major. No guidance on prerequisites or scenarios is 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 already declare readOnlyHint true, destructiveHint false, idempotentHint true. The description adds critical behavioral context: scoping to identifier (anonymous IP, key hash, account ID) and pairing with remember/forget. This goes 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 highly concise, with no wasted words. It front-loads the primary function, then provides usage examples, scoping, and pairing instructions in a logical order.

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

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

For a simple tool with one optional parameter, no output schema, and clear annotations, the description is fully complete. It explains both modes (retrieve specific key, list all keys), and covers scoping and pairing, leaving no ambiguity for an AI agent.

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

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

Schema coverage is 100% with a description for the key parameter. The description reinforces the behavior of omitting the key to list all, adding meaningful usage context beyond the schema field. Baseline 3, but the added context merits a 4.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys when omitted. It specifies the action (retrieve/list), resource (saved memory), and scope (by key or all), distinguishing it from sibling tools like 'forget' and 'remember'.

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

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

The description provides explicit use cases (e.g., looking up user context, target ticker, address, research notes) and mentions scoping and pairing with remember/forget. It does not explicitly state when not to use, but the positive guidance is strong and clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the count comes from pypistats.org and that it returns a single aggregate count, providing useful context without contradicting 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?

Two sentences, front-loaded with the core purpose, and no unnecessary words. Every sentence adds value.

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

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

With two parameters, one required, and an output schema present, the description is fairly complete. It explains the return value (single aggregate count) and the source. Minor missing detail: the units (downloads) and requirement that the package exists on PyPI, but overall adequate for a simple 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 descriptions cover 50% of parameters (period has a description, package does not). The description adds meaning by clarifying period values (day, week, month) but does not elaborate on the package parameter, leaving it as a generic string.

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 (fetch), resource (total PyPI download count for a package), and scope (over a recent period of day, week, or month). It distinguishes this tool from siblings like 'recent_alerts' or 'recent_changes' by specifying PyPI statistics.

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 the tool is for retrieving recent download counts, but it does not explicitly state when to use it versus alternatives (e.g., 'overall' for total counts), nor does it provide when-not-to-use conditions.

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 behavior like returning specific fields, how mark_read affects subsequent calls, and the feed availability via REST. No contradictions.

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

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

Concise at 4 sentences. Front-loaded with the main action, then details on returned fields, filtering, mark_read flag, and a note on alternative access. Every sentence serves a purpose 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?

Covers key aspects: what is returned, filtering options, mark_read behavior, and alternative access. Missing explicit structure of the return object, but the description mentions core fields (source, citation_uri, raw event payload). With no output schema, it is fairly 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?

All 5 parameters are described in the schema, and the description adds further meaning: gives an example for type ('sec_8k'), explains 'since' as ISO timestamp, and clarifies that mark_read flags events as read. 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 defines the tool's purpose: 'Pull fired events from your subscription feed.' It specifies what is returned (recent alerts with source, citation_uri, raw payload) and distinguishes from siblings like 'list_subscriptions' by focusing on event feed 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?

Provides useful usage guidance: mentions filtering by type and since, explains mark_read behavior, and notes that polling works fine. Also points to an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus 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 indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral details: fans out to multiple APIs, fallback from GDELT to GNews, soft-failure for USPTO, and parameter behaviors, 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?

Single paragraph that starts with concrete query examples, then explains fan-out, parameter formats, return structure, and sibling distinction. Every sentence adds value; no filler.

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

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

Covers parameters, return structure (changes[], total_changes, URIs), and use cases. No output schema, so description compensates well. Lacks explicit mention of empty result behavior, but overall 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 has 100% coverage with descriptions. The description adds value by explaining 'since' accepts ISO or relative formats and suggests typical usage, and clarifies that 'value' can be ticker or CIK. This goes 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 clearly defines the tool as a change feed for a company, listing example queries like 'What's new with X' and explicitly contrasting with sibling tool entity_profile for static 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?

Provides explicit guidance on when to use (recent changes) and when to use entity_profile instead. Also details fallback logic for news sources. Could be more explicit about when not to use, but the alternative is clearly 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 idempotent and non-destructive behavior. The description adds valuable context: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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?

Four sentences, front-loaded with purpose, no wasted words. Clear structure with usage guidance and pairing with siblings.

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

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

Given the simple tool with 2 params, no output schema, and rich annotations, the description covers all necessary context: purpose, usage, behavior, and scope. Complete for effective use.

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

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

Schema description coverage is 100% with examples for both key and value. The description does not add additional parameter semantics beyond the schema. Baseline 3.

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

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

The description clearly states the tool's purpose: saving data for reuse across conversations/sessions. It specifies the action (save), the resource (data as key-value pairs), and distinguishes from sibling tools like recall and forget.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward' and pairs with recall/forget. Also explains scope by identifier and persistence differences for authenticated vs anonymous users.

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, and idempotentHint. The description adds that it cascades through several lookup endpoints internally, auto-disambiguates for company, and returns structured output with citation URIs. This goes beyond what annotations provide, though it could mention rate limits or failure modes.

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 natural language queries and a usage directive. Every sentence adds substantive value: supported types, output details, internal cascading. No fluff or repetition. Efficient for its length.

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

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

Despite lacking an output schema, the description fully specifies the return structure for both entity types, including citation URIs and internal cascading. An agent can infer the tool's capabilities and output format without guessing. The information is sufficient for safe and effective invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples of valid inputs (ticker, CIK, name for company; brand/generic for drug) and explicitly maps each type to the output format (ticker+CIK+… for company, RxCUI+ingredient for drug). This semantic enrichment helps the agent understand how inputs translate to outputs.

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

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

The description opens with concrete query examples and explicitly states the tool resolves a name to a canonical identifier. It contrasts with sibling tools like entity_profile and compare_entities by focusing on ID lookup. The verb 'resolve' and resource 'entity' are clear.

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

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

The description directly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not explicitly state when not to use, but the idempotent and read-only annotations make it safe to use broadly. No alternative tools are named, 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?

Description adds significant behavioral context beyond annotations: it internally calls 'ai_visibility_check', ranks results, and surfaces most/least recognized. It also details output structure (score, confidence, signal density). No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Three sentences: first front-loads the core action, second explains mechanism, third gives use case and expected output. No extraneous text. Every sentence earns its place.

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

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

Despite no output schema, the description sufficiently describes return values (ranked list with score, confidence, signal density). For a tool with 4 parameters and moderate complexity, the description covers all necessary aspects including internal tool call and use case.

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

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

Schema coverage is 100% (baseline 3). Description adds value by clarifying that the first element in 'entities' is treated as 'subject' for narrative, and explains conditional use of '_apiKey' when 'models' includes 'anthropic'. This enriches parameter understanding.

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

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

The description uses specific verbs ('compare', 'probe', 'rank', 'surface') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes itself from sibling tool 'ai_visibility_check' by emphasizing side-by-side comparison versus single entity probe.

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 use case ('competitive AI-marketing audits') with a concrete example. Implies that for a single entity check, 'ai_visibility_check' should be used. Does not explicitly list when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: bundlephobia's first call can take 5-30s and partial failures degrade gracefully with sources_failed listed. No contradictions with annotations.

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

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

The description is front-loaded with the primary purpose, then systematically covers sources, usage, return structure, and edge cases. Every sentence provides distinct value without redundancy, achieving conciseness for the complexity of the tool.

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 thoroughly lists return fields (summary block with 8 fields, per-advisory detail, links, alternative versions) and explains graceful degradation. No gaps for the tool's functionality and behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new parameter-level information beyond what the schema already provides (package name, scoped packages, version optional with default). Context is integrated but not additional semantic value.

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

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

The description starts with a clear, specific purpose: 'Composite should I add this npm package to my project check in ONE call' and details the sources consulted (deps.dev, bundlephobia). It distinguishes from sibling tools by noting the NPM-only scope and referencing alternative usage for other ecosystems via deps.dev:version directly.

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

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

Explicit guidance on when to use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' Also clarifies limitations ('NPM ecosystem only in v1') and points to alternatives for PyPI/Maven/Cargo/Go via 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 mark the tool as readOnly, idempotent, and non-destructive. The description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping 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 a single paragraph with clear sentences and front-loaded main idea. It is dense but every sentence adds value. Minor room for improvement in brevity.

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 explains the return values (top-N passages with offsets and similarity scores). It covers truncation behavior and pairing with another tool, making it comprehensive for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about how the search works but does not provide new parameter-specific information beyond what the schema already conveys. It reinforces the purpose but doesn't add semantic depth to the parameters.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific examples like SEC 10-K and articles. It distinguishes from siblings by emphasizing its role in reducing context usage and pairing with ask_pipeworx_grounded.

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 advises using this tool when the record is too large for the prompt, and mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or alternative tools for other scenarios.

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

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

Discloses auth requirement, subscription id return, delivery channels, SMS cap (10/day), webhook HMAC signing and auto-disable after 10 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?

Well-structured but dense with many details. Slightly verbose 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?

Covers prerequisites, params, delivery options and return value. Lacks error cases but sufficient given no output schema.

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

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

Adds detailed type-specific examples and required fields for params and delivery, beyond schema enums and 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?

Clearly states 'Create a proactive monitoring subscription' and lists return value. Distinguishes from list_subscriptions and unsubscribe.

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

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

Explicitly states OAuth requirement and mentions delivery limits. Lacks explicit when-not-to-use scenarios but provides context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context about the nature of the output (category-bucketed examples with tool shapes) and that results are drawn from a live catalog. 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 slightly lengthy but well-structured with examples and clear purpose. It front-loads the common queries and separates into use-cases. Could be trimmed slightly, but is effective.

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

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

Despite no output schema, the description explains the return structure (category-bucketed example questions with tool+argument shapes) adequately. Covers the onboarding scenario and mentions meta-tools for further actions.

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

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

Schema coverage is 100%, and the description provides additional meaning for the 'topic' parameter by listing example values and explaining that omitting it gives a cross-category spread.

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

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

The description clearly states that the tool is the onboarding entry point, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by advising to use it first when the agent doesn't know what Pipeworx can do.

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 to use this tool first when the user is unfamiliar with Pipeworx. Explains when to omit or provide the 'topic' argument but does not explicitly contrast with alternative tools for similar queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds value by specifying the external source 'pypistats.org' and the return format ('per-OS download counts'). 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?

A single, front-loaded sentence that efficiently conveys the tool's purpose and key details. No extraneous text.

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

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

The description is adequate for a simple tool with one parameter, existing output schema, and comprehensive annotations. It covers what, how, and source. Minor omission: no mention of output schema contents, but that is provided separately.

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 partially compensates by implying that 'package' is the PyPI package name. However, it adds no further detail about the parameter's format or constraints beyond the schema's basic 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?

The description clearly states the action ('Fetch'), the resource ('PyPI download breakdown for a package'), and the specific dimension ('by operating system (Linux, Windows, Darwin, null)'). It also distinguishes from sibling tools that likely fetch overall or by-version stats.

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 per-OS breakdown is needed, but does not explicitly state when to use versus alternatives like 'python_major' or 'overall'. No exclusions or prerequisites are mentioned.

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 value beyond annotations: describes ownership enforcement, deactivation vs deletion, and that historical events remain. Annotations (destructiveHint=false, idempotentHint=true) are consistent and description enriches them.

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

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

Two sentences, front-loaded with action, then constraints, then behavioral details. 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 single parameter, no output schema, and good annotations, the description fully covers purpose, usage constraints, and behavioral outcome.

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 description for 'id' already present. Description does not add additional meaning beyond what schema provides, so baseline 3.

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

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

Description clearly states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation and ownership.

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 mentions ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated not deleted, giving clear context. Does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it returns a verdict with structured form, actual value with citation, and percent delta. It also mentions efficiency gains by replacing multiple sequential calls. No contradictions with annotations.

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

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

The description is front-loaded with common query patterns and a clear usage statement. It is detailed but every sentence adds value. Slightly long but not excessive; could be trimmed slightly but remains effective.

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

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

Despite lacking an output schema, the description fully explains the return values (verdict, structured form, actual value, citation, percent delta). It also clarifies the supported claim domain. For a single-parameter tool with comprehensive annotations, this is 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%, so the parameter is already well-defined. The description reinforces the parameter's purpose with examples but does not add new information beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs (validate, verify) and identifies the resource (claims, particularly company-financial). The examples and scope distinguish it from sibling tools like ask_pipeworx or bet_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also mentions the current scope (company-financial claims). While it doesn't explicitly list when not to use or name alternatives, the context is clear enough for appropriate tool selection.

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