Espn

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context: how Anthropic billing works (BYO key, pay directly), return structure (per-model scores, confidence, signals, raw_response), and default model. No contradictions found.

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 tightly written sentences. First sentence front-loads core purpose, default model, and key parameters. Second sentence covers return format and use cases. 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 all essential aspects: what, how, parameters, return format, use cases, billing nuance. No output schema exists, but description compensates. Slightly missing edge cases (e.g., rate limits), but overall complete for a non-destructive probe 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 description adds meaning: 'disambiguate common names' for context, clarifies the pass-through nature of _apiKey, and explains the models array options. Complements schema rather than repeating.

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 'Probe one or more LLMs for what they know...' with specific verb and resource. It uniquely identifies the tool among siblings like compare_entities or scan_competitor_ai_presence by focusing on visibility scoring per model.

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 context for use cases (AI-marketing audits, pre-launch checks) and model selection (default free Workers AI, Anthropic requires key). Lacks explicit when-not-to-use or direct sibling comparisons, but sufficient for typical usage decisions.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds context about routing to 3,547 tools and returning structured answers with citation URIs, which is helpful but not critical 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 front-loaded with the key instruction to prefer this over web search, followed by domain examples and usage triggers. It is slightly lengthy but each sentence adds value; could be tightened slightly.

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 broad-scope tool with no output schema, the description fully covers purpose, use cases, behavior (routing to tools, citation URIs), and provides concrete examples. It leaves no significant gaps for an agent to understand when and how to invoke it.

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

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

Schema description coverage is 100% (all parameters documented as aliases for 'question'). The description adds example questions but does not provide additional semantic meaning beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: answering factual questions about current/historical data from authoritative structured sources. It lists specific domains (SEC filings, FDA data, etc.) and contrasts with web search, clearly distinguishing it from siblings.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for factual questions, provides extensive examples, and lists trigger phrases like 'what is', 'look up', 'find', making it clear when to use this tool over alternatives.

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

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

Beyond annotations (read-only, idempotent), the description details fan-out logic, classifier categories, resolver confidence levels, parent event extraction, news fallback handling, safety short-circuits, and tradeability warnings. 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 main purpose and structured with clear sections (classifiers, fan-out examples, response shapes, safety). However, it is verbose and could be more concise while retaining key details.

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

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

Given no output schema, the description thoroughly covers response shapes, including fields like market_match_confidence, parent_event, news fallback indicators, and status codes. It compensates fully for the lack of an 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%, and the description adds significant meaning: explains 'market' accepts slug, URL, or question text; 'depth' enum with quick vs. thorough; 'include_raw' with response size implications. Examples in schema enhance clarity.

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 in one call. It gives specific scenarios ('should I bet on X') and differentiates from sibling tools like 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?

Explicitly specifies use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides warnings about low-confidence matches and closed markets, guiding appropriate vs. inappropriate usage.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: for companies, it pulls latest 10-K financials from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, it pulls FAERS counts, FDA approvals, and active trials; results are sorted by primary metric; returns paired data and citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with trigger phrases and purpose. It is slightly long but every sentence adds value, covering trigger phrases, entity types, data sources, sorting, and return format. Could be more concise, but overall efficient.

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

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

The description provides a good overview of input and output (paired data + citation URIs), but lacks exact return format details (e.g., fields for each entity). Given the complexity and absence of an output schema, slightly more detail on the response structure would improve completeness.

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

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

The input schema has 100% coverage, but the description adds significant meaning: it clarifies that 'type' accepts 'company' or 'drug', and for 'values' it specifies tickers/CIKs for companies and drug names, with examples and min/max constraints. This 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 tool performs side-by-side comparisons of 2–5 companies or drugs in a single call. It distinguishes from sibling tools like entity_profile by emphasizing preference over sequential lookups and providing specific trigger phrases.

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

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

The description explicitly states when to use ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides example queries ('Compare X and Y', 'X vs Y', etc.). It also implies alternatives (sequential lookups) and gives conditions (2–5 entities, company or drug).

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, so no safety surprises. The description adds valuable behavioral context: it returns top-N relevant tools with full schemas, ready to call directly, and notes no second schema lookup is needed. This complements the annotations well.

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

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

The description is front-loaded with purpose, then usage, then return specifications. It is somewhat lengthy but every sentence contributes value. Could be slightly more concise, but overall well-structured and efficient.

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

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

For a meta-tool that discovers other tools, the description covers purpose, usage context, return format (names, descriptions, schemas), and includes examples. Annotations cover safety. Without an output schema, the description adequately explains what to expect. It is complete for an agent to understand and invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions aliases but the schema already documents them with examples. The description reinforces the use of natural language queries but does not elaborate on parameters further.

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

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

The description explicitly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from siblings by being a meta-tool for discovery, with specific examples and the directive 'Call this FIRST when you have many tools available and want to see the option set.'

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 clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a list of domains. It also advises calling this tool first for option discovery. It does not explicitly state when not to use it, but the positive 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails for patents, returns specific fields with URIs. No contradictions.

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

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

The description is front-loaded with examples and key usage. It is relatively long but each sentence adds unique value (source details, constraints, return fields). Minor verbosity could be trimmed, but overall efficient.

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

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

Given no output schema, the description thoroughly explains return values: cik, company_name, recent_filings with URIs, fundamentals, patents (with sunset note), news via GDELT→GNews, and LEI. 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%, with both parameters (type and value) described in the schema. The description adds valuable context: value accepts ticker or zero-padded CIK, names not supported, and references resolve_entity. This clarifies usage beyond the schema's enums.

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: providing a full cross-source profile of a US public company. It uses specific verbs like 'profile' and 'research' and distinguishes itself from chaining single-pack lookups by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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 usage guidance is provided: 'ALWAYS PREFER over chaining...' for holistic views, and when not to use: 'names not supported (use resolve_entity first)'. This clearly differentiates from sibling tools like resolve_entity.

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, so the burden is lower. The description adds context about clearing sensitive data, which is consistent but doesn't add new behavioral traits beyond annotations.

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

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

Two sentences, each serving a distinct purpose: action and usage guidance. No wasted words.

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

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

For a simple tool with one parameter and clear annotations, the description fully covers what the tool does and when to use it. No output schema needed.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description mentions 'by key' but adds no new meaning beyond the schema.

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

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

The description uses a specific verb 'Delete' and resource 'memory by key', clearly stating the tool's action. It also distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, implying when not to 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. This aligns with annotations and provides process details beyond structured fields.

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

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

The description is concise (two paragraphs, ~70 words), front-loaded with the core action, and efficiently covers output, use cases, and format. 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?

Given the tool's simplicity (2 params, no output schema), the description adequately explains output format and use cases. It does not cover error conditions or dependencies, but the annotations mitigate safety concerns. Overall sufficient for an agent.

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

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

Schema coverage is 100%, with both parameters described in the schema. The description mentions 'Full URL' and 'Maximum number of link entries' but adds no significant semantic value beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate), output (llms.txt), and target audience (AI crawlers). It distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by its unique output.

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

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

The description lists specific use cases (indexing clients' sites, drafting for own projects, auditing competitors) but does not explicitly state when not to use the tool or mention alternative sibling tools. The guidance is clear but lacks exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that the tool returns 'articles with summaries and links,' which is beyond the annotations. No contradiction.

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

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

The description is a single sentence with a list of examples. It is front-loaded with the purpose and uses no fluff. Every part serves a purpose (clear verb, resource, and actionable examples).

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 is read-only and has no output schema, the description adequately covers it returns articles with summaries and links. It also explains the sport/league pairs. However, it does not explicitly mention default limit (but schema does) or pagination. Still sufficient for most use cases.

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

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

Although schema coverage is 100% (all parameters documented), the description significantly enriches by providing a detailed list of common sport/league pairs (e.g., 'football/nfl', 'soccer/eng.1'). This adds practical guidance not in the schema, helping the agent select correct values.

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 'latest sports news headlines' for a league, with a specific verb ('get') and resource ('news headlines'). It distinguishes from sibling tools like get_scoreboard or get_teams by focusing on articles with summaries and links.

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

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

The description lists common sport/league pairs, guiding which parameters to use. While it doesn't explicitly state when not to use the tool, the context of other sibling tools implies alternatives. The examples are helpful for correct invocation.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds value by detailing output fields (teams, scores, status, clock, period) and providing common sport/league pairs, aiding correct invocation.

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 yet informative, front-loading the core purpose, then listing return fields and common examples with no unnecessary text.

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

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

With no output schema, the description sufficiently explains what the tool returns and covers the main use cases for multiple sports and leagues.

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 parameters have schema descriptions, and the description enriches them with concrete examples of valid sport/league pairs, reducing ambiguity for the agent.

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

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

Clearly states it provides live sports scores for multiple leagues, listing specific sports and example league slugs. Distinguishes from siblings like get_teams and get_news by focusing on scores and game status.

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?

Implicitly guides usage by specifying it returns scores and game details for today's games, with optional date filter. Does not explicitly contrast with sibling tools or state when not to use, but context makes differentiation 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?

The description discloses the exact data fields returned (names, abbreviations, locations, colors) beyond what annotations provide. Annotations indicate read-only and idempotent behavior; the description adds actionable details on output contents, which is valuable for the agent.

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

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

The description is concise: two clear sentences covering purpose and valid inputs. It is front-loaded with the core action, and the list of examples is efficiently formatted. Every sentence contributes useful information without redundancy.

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

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

Given the tool's simplicity (two required params, no output schema), the description is fully sufficient. It explains the returned fields, lists valid sports and leagues, and provides example pairs. The agent has all necessary context to use the tool correctly.

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

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

Schema coverage is 100% with basic descriptions. The description enriches parameter semantics by providing concrete examples of valid sport/league pairs (e.g., 'soccer/eng.1'), helping the agent construct valid inputs. This adds value 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 states the action ('List'), resource ('all teams'), and scope ('for a league'), specifying the data returned (names, abbreviations, locations, colors). It distinguishes from sibling tools by focusing exclusively on team data, whereas siblings like get_scoreboard or get_news serve different purposes.

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

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

The description provides explicit context on when to use the tool by listing supported sports and common sport/league pairs (e.g., 'football/nfl', 'basketball/nba'). It implicitly guides the agent on valid inputs, though it does not explicitly state when not to use it or mention alternative tools for related 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?

The description discloses rate limiting (5 per identifier per day), free usage, no tool-call quota impact, and that the team reads digests daily. These are beyond the annotations, which only indicate non-read-only, non-idempotent, non-destructive behavior. No contradiction.

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

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

The description is concise (single paragraph, ~120 words), front-loaded with the core purpose, and each sentence adds essential 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?

For a feedback tool with 3 parameters and no output schema, the description covers purpose, usage scenarios, behavioral constraints, and parameter expectations completely. It leaves no significant gaps for an AI agent to understand tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining the feedback process, rate limits, and how to frame the message, which enhances the meaning of the parameters beyond the schema definitions.

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

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

The description explicitly states the tool's purpose: telling the Pipeworx team about something broken, missing, or needing to exist. It lists specific categories (bug, feature/data_gap, praise) and clearly distinguishes from sibling tools which are about research, discovery, and other functions.

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

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

The description provides explicit when-to-use guidance: for wrong/stale data (bug), missing tools (feature/data_gap), or positive feedback (praise). It also gives instructions on how to describe issues (in terms of tools/packs, not end-user prompts) and mentions rate limits and quota.

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. Description adds valuable context: data source ('CF analytics-engine'), no PII, caching details (5min-1h). This goes beyond annotations 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?

Three sentences, front-loaded with the core output, followed by use cases, then technical details. No filler, 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?

Covers purpose, usage, behavior, caching, and parameter semantics. No output schema, but description implies the structure (top tools, packs, count). Could mention return format explicitly, but not essential for 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 covers 100% of the single parameter with enum and description. Description adds meaning by explaining the trade-off between shorter windows ('what's hot right now') and longer windows ('steady-state demand'). 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?

The description clearly states the tool returns 'top tools, top packs, and total call volume' over windows. It uses specific verbs and resources, and distinguishes from sibling tools like 'discover_tools' or 'get_scoreboard' by focusing on trending/aggregate 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?

Explicitly lists three use cases (1) discovering hot data, (2) confirming canonical tool, (3) checking alignment. Provides clear context on when to use. No explicit when-not or alternatives, but the guidance is sufficient.

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

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

The description discloses key behavioral traits: mode selection, monotonicity checks, partition-sum calculations, Jaccard similarity thresholds, placeholder filtering, and response structure. It adds detail beyond annotations, which only indicate read-only, open-world, and idempotent 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 well-structured with clear sections, front-loaded requirements, and every sentence adds value. Despite length, it is organized and avoids redundancy, making it effective for a complex 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?

The description provides complete context for the tool's usage, including caveats about Jaccard similarity, placeholder filtering, and response format. Although no output schema exists, the response structure is sufficiently described.

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

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

The input schema provides parameter descriptions, but the tool description adds significant value by explaining the algorithmic difference between event and topic modes, giving example slugs, and detailing the partition_check logic.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between single-event and cross-event modes with specific examples, setting it apart from sibling tools like polymarket_edges.

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

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

The description explicitly requires 'one of `event` or `topic`' and warns that calling with no args fails. It recommends the event mode for specific markets and the topic mode for cross-event scanning, providing examples and explaining when each is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds significant behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, diagnostics), limitations ('Fed bets... excluded from ranking'), and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.). No contradiction with annotations.

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

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

The description is long but well-structured: purpose first, then segments, response details, knobs, and diagnostics. It front-loads the key action and uses bullet-like structure with parentheses and dashes. While dense, every sentence adds value for an AI agent. Could be slightly more concise, but the detail is warranted given tool complexity.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the three segments' models, response structure including diagnostics and Fed note, caching behavior, tradeable-edge knobs, and per-opportunity fields. It even addresses edge cases like why Fed bets are excluded. Without an output schema, the description fully compensates.

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 well-described parameters (e.g., 'Top N edges to return after ranking. Default 10, max 25.'). The main description adds high-level context by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their role, but does not provide additional semantic meaning beyond the schema. 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets, opportunities), and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on disagreement with market price. The phrase 'Built for "what should I bet on today"' reinforces its unique discovery role.

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

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

The description provides clear usage context: 'agents discover opportunities without paging hundreds of markets' and explains the three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). It implies when to use this tool (for high-level opportunity scanning) but does not explicitly state when not to use it or compare to specific siblings like 'bet_research' or 'polymarket_arbitrage'. However, the context is clear enough for an agent to infer appropriate 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?

Annotations already mark the tool as readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral context: explains response structure (leg prices, spread), safety fields (compatibility_warning conditions), temporal_alignment, and counters for skipped comparisons. 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 dense but well-organized: starts with main purpose, then modes, response details, safety warnings. Every sentence adds value, though the length might be slightly verbose for a tool with high schema coverage. Front-loaded with the core idea.

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

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

No output schema exists, so description must explain return values. It does so comprehensively: leg prices, spread, compatibility_warning with two cases, temporal_alignment, skipped counters. Given the tool's complexity, the description covers all necessary information for an agent to use it correctly.

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

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

Schema covers all 3 parameters with descriptions (100% coverage), so baseline is 3. The description provides additional context like the list of pre-mapped topics and examples, but these are not essential since schema already explains the parameters adequately.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies the action (compute spread), resource (two venues), and distinguishes from sibling tools like polymarket_arbitrage which focus on intra-venue arbitrage.

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

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

Explicitly describes two modes (topic and explicit pairing), provides concrete examples (e.g., 'fed', 'btc'), warns when spreads are meaningless (compatibility_warning cases, temporal_alignment false), and cautions that pre-mapped topics are not necessarily tradeable. This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnly, idempotent, etc.), adds details about scope (anonymous IP, key hash, account ID) and pairing with remember/forget. 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 concise sentences, each earning its place. Front-loaded with main action and examples. No unnecessary words.

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

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

Given no output schema, description adequately explains behavior (retrieve value or list keys). Sufficient for an agent to understand usage, though return format is not explicitly stated.

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%. Description adds meaning by explaining that omitting key lists all saved keys. Provides additional behavioral context beyond the schema's basic description.

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

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

Description clearly states the tool retrieves saved values or lists all keys, with specific examples like 'user's target ticker, an address, prior research notes'. It distinguishes from siblings by naming 'remember' and 'forget'.

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

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

Explicitly says when to use: to look up stored context without re-deriving. Mentions scoping to identifier. Does not explicitly state when not to use, but provides clear context for appropriate usage.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description goes beyond by detailing how the tool fans out to multiple sources, including fallback logic (GDELT→GNews) and soft-failure for USPTO, and describes the return structure (grouped by source, total_changes count, citation URIs). 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 concise but covers all necessary aspects without redundancy. It front-loads common query patterns and maintains a logical flow. A minor improvement could be shortening some details, but overall it is efficient.

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

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

Given 100% schema coverage and no output schema, the description adequately explains the return format (changes[], total_changes, citation URIs). It also mentions the alternative tool for static profiles. Slightly more detail on potential rate limits or error handling could enhance completeness, but it is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter formats (ISO date or relative shorthand like '7d', '30d') and clarifying that 'value' accepts tickers or zero-padded CIK. The 'type' parameter is correctly noted as only supporting 'company'.

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 change feed for a company that aggregates recent activity from SEC EDGAR, GDELT/GNews, and USPTO. It provides concrete query examples and distinguishes itself from the sibling 'entity_profile' tool by specifying when to use each.

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

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

The description explicitly tells when to use this tool ('What's new with X', 'updates on Acme') and when not to ('Use entity_profile instead when you want the static profile'), naming the alternative directly. It also explains the fallback behavior for news sources.

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 value beyond annotations. It discloses that data is stored as key-value pairs scoped by identifier, and explains persistence differences between authenticated users (persistent) and anonymous sessions (24 hours). Annotations already indicate idempotentHint=true and non-destructive, and the description is consistent.

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, well-structured, and front-loaded with the core purpose. Every sentence adds value, and there is no repetition or 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 the tool's simplicity, the description, schema, and annotations together provide complete information. The description covers storage mechanism, scoping, persistence duration, and pairing with sibling tools. No gaps remain.

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

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

Schema has 100% coverage with clear descriptions for both params (key and value). The tool description adds context on usage but does not provide additional semantic detail beyond the schema for the parameters themselves.

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

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

The description specifies the verb 'save' and the resource 'data (key-value pair)'. It clearly distinguishes from sibling tools recall and forget by stating the purpose of remembering data for later reuse, including across sessions.

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

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

The description provides clear when-to-use guidance with concrete examples ('resolved ticker, target address, etc.') and mentions pairing with recall and forget. It lacks explicit when-not-to-use instructions but effectively communicates usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds internal cascading behavior, auto-disambiguation, and citation URI returns, surpassing 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?

Well-structured with examples first, then purpose, then details. Efficient but could be slightly tightened; still 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?

No output schema, but description fully explains return data per type, usage context, and internal processing. 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 covers both parameters fully. Description adds significant value by detailing return values (ticker, CIK, RxCUI, etc.) and input format clarifications, enriching beyond schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, provides specific examples for each supported type (company, drug), and distinguishes itself from sibling tools by focusing on ID lookup.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID' and mentions efficiency gains. Lacks explicit when-not-to-use, but context from sibling tools implies alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds substantial behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. It also reveals that the first entity is treated as the 'subject' for narrative. No contradictions.

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

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

The description is three sentences, each carrying essential information: what the tool does, how it works, and when to use it. It is front-loaded with the main action and avoids redundancy. 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 specifies the return format (ranked list with score, confidence, signal density). It covers input constraints (2-8 entities, first as subject) and internal logic. The tool's moderate complexity (4 params, 1 required) is fully addressed, leaving no obvious gaps for an agent to misuse it.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds valuable nuance beyond the schema: it explains that the first entity in 'entities' is the subject and the rest are competitors, and clarifies the role of 'models' and 'context' by linking to the internal ai_visibility_check call. This extra context justifies a score above the 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and surfaces the most/least recognized. It distinguishes from the sibling ai_visibility_check by being a comparative, multi-entity tool, and provides a concrete use case ('does Claude know about us as well as our competitors?').

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

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

The description explicitly says it's useful for competitive AI-marketing audits and implies use when comparing multiple entities. It does not explicitly exclude cases (e.g., single entity) but the context makes it clear. No direct comparison to siblings like compare_entities, but the purpose is well-defined.

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 elaborates on the composite nature, timing delays, and graceful degradation on partial failures. Annotations already declare read/idempotent, but the description adds substantive behavioral detail like the 5-30s first measurement and the 'sources_failed' field, which helps the agent understand edge cases.

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 comprehensive without being wasteful, though it could be shorter. It uses clear headings-like structure (composite, use when, returns, notes). The timing detail is important but adds length. Overall, it's well-organized and front-loaded.

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

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

Despite lacking an output schema, the description enumerates the return structure in sufficient detail: summary block fields, per-advisory detail, links, and alternative versions. It also handles edge cases like partial failures and timing. This gives the agent a solid mental model of the response.

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

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

The schema already documents both parameters with descriptions. The description adds practical nuance: scoped packages are accepted and version defaults to latest. This aids the agent in constructing valid calls without requiring external knowledge.

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 composite check for npm packages, listing all the data sources and return fields. It also explicitly states the ecosystem limitation (NPM only in v1) and when to use it, differentiating it from broader tools like entity_profile or resolve_entity.

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

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

The description provides explicit usage scenarios, ecosystem limitation with alternative fallback (deps.dev:version), and mentions timing behavior for bundlephobia. This gives the agent clear guidance on when to invoke this tool versus other dependency lookup 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, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: it returns a verdict, extracted form, actual value with citation, and percent delta, and mentions it replaces 4-6 sequential calls.

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

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

Two concise sentences with a clear structure, front-loaded with user intents and function, 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?

With one parameter and no output schema, the description fully explains the claim input and return structure, making it complete for effective usage.

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

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

Schema description coverage is 100% with a good description. The description adds concrete examples of claim formats, enhancing understanding beyond schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific examples. It distinguishes the tool's function from siblings, though it does not explicitly name alternatives.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It doesn't give when-not-to-use, but the unique functionality among siblings makes it unnecessary.

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