Football Data

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds value by explaining that probing Anthropic requires a BYO key (cost implications) and the return format (per-model score, confidence, signals, raw_response). This goes beyond annotations, though potential issues like rate limits are not disclosed.

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 roughly 4 sentences, front-loading the core purpose, then model options, return format, and use cases. Every sentence adds value, and there is no redundancy. It is efficiently 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?

Given no output schema, the description adequately explains return values (per-model score, confidence, signals, raw_response plus combined view). It covers purpose, parameters, models, and use cases. Missing error handling or edge cases, but overall sufficient for an AI agent to understand invocations.

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 description adds meaning by specifying default model (Workers AI Llama-3.3-70b), the role of _apiKey for Anthropic, and context for disambiguation. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the verb 'probe' and resource 'LLMs for what they know about a business/brand/product/topic'. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' or 'ask_pipeworx'.

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: useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains model selection (default Workers AI, add Anthropic via _apiKey) with cost implications. However, it does not explicitly exclude alternatives or mention 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing safety and statelessness. The description adds valuable behavioral context: it routes internally, fills arguments, returns structured answers with pipeworx:// URIs, works on every tier, and requires only one fast call. This enriches the agent's understanding beyond the annotations.

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

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

The description is well-structured and front-loaded: begins with a preference directive, lists covered domains, explains internal operation, provides examples, and concludes with usage escalation criteria. Every sentence serves a purpose, and the length is appropriate for a complex, primary entry-point 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 tool's complexity (routing to thousands of sub-tools) and the absence of an output schema, the description is remarkably complete. It covers functionality, scope, behavior, usage context, examples, and alternatives. No output schema is needed because the description explains the structured answer with citations.

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 aliases for the question parameter. The description adds practical guidance on what kinds of questions to ask (SEC filings, FDA data, etc.) and provides examples, which is useful beyond the schema's simple 'Your question or request in natural language' explanation. This helps the agent formulate appropriate input.

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 routes questions to 4,552 tools across 1,160 verified sources and returns structured answers with citation URIs. It distinguishes from siblings like web search, ask_pipeworx_grounded, and deep_research, 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 provides explicit when-to-use guidance (factual questions about real-world data) and when-not-to-use (hallucination-resistant single answer → ask_pipeworx_grounded; broad multi-part → deep_research; breaking news already covered). It also lists example queries and suggests preferring this over web search, fully covering usage context and alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds return format details (answer, evidence, confidence, source, refusal_reason) and explains the cost of one extra LLM call. 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 somewhat long but well-structured with clear sections (process, output, usage guidance). Every sentence adds value, though could be slightly more concise without losing detail.

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?

Even without an output schema, the description thoroughly explains return values and refusal reasons. It covers success and error cases, making it complete for high-stakes 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 coverage is 100%, and the description explains the question parameter accepts natural language and lists aliases (query, q, prompt, text, input). This adds meaning beyond the schema.

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

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

The description clearly states 'hallucination-resistant answer mode for high-stakes reads' and explains the process: picks the right tool, fetches data, extracts answer from tool result. It distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and specific use cases.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' Provides clear context for when to use vs the alternative sibling tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral details: low-confidence resolution short-circuits, closed market handling, wide-spread liquidity notes, resolution-rule risk parsing, and response shapes. 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 lengthy but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the main purpose. Every part adds value, but could be slightly more compact for agent parsing.

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 fully explains return fields (result.market, analysis, evidence, match confidence) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Covers all necessary context for tool selection and 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 coverage is 100% with all three parameters described. The description adds context: market input can be slug, URL, or question text; depth enum with default; include_raw explains when to use true (full payloads vs summaries). This goes 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 it researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text) and output evidence packet. It distinguishes from sibling tools like polymarket_edges by focusing on comprehensive data aggregation.

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 listed use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides fan-out examples. However, it does not explicitly state when not to use or mention alternative tools among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specific behavioral context: pulls latest 10-K from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years for companies, and FAERS data for drugs. It also notes results are sorted by primary metric and returns citation URIs.

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 verbose but each sentence contributes value. It is front-loaded with example queries and essential guidance. Slightly more concise could be possible, 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?

Given the schema fully describes parameters and the description covers usage, behavior, and output (citation URIs), the tool is fully documented. No output schema is needed as the return format is described adequately.

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

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

Schema coverage is 100%, but the description significantly adds meaning: clarifies enum values with examples (tickers/CIKs for company, drug names), specifies min/max items (2-5), and explains how each type works. This goes well beyond the schema's basic descriptions.

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

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

The description clearly uses specific verbs like 'compare', 'rank', and 'head to head' and specifies the resource (companies or drugs). It distinguishes from siblings by emphasizing one parallel call vs sequential lookups, and mentions alternatives like 'entity_profile' for single entities.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries ('compare X and Y', 'rank these companies'), guiding the agent on when to use this tool over others.

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

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

Discloses decomposition into facets, parallel routing to 4,552 tools, return format with evidence and gaps[], expected duration of 15-60s, and limitation that it returns empty gaps for topics not in structured catalog. This adds significant 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?

Though verbose, the description is well-structured with sections for account, capabilities, and usage guidance. Every sentence adds value, but minor trimming could improve conciseness without losing information.

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

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

Given the tool's complexity, the description fully covers prerequisites, limitations, performance, and output format. No output schema exists, but the description compensates with detailed findings packet description. Annotations further support completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8) and clarifying that the question can be broad/multi-part. This goes 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 that the tool performs 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and contrasts with ask_pipeworx for single queries. It specifies the verb 'research' and the resource 'Pipeworx's structured data sources', distinguishing it from siblings like ask_pipeworx.

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 notes that an account is required, with free tier and paid plan for 'thorough' depth. Provides a direct alternative ('if not signed in, use ask_pipeworx') and states when to prefer ask_pipeworx for single lookups or breaking news.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N tools with full input schemas and curated examples, each ready to call directly. No contradictions; provides useful 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?

Description is front-loaded with purpose, then usage guidance, then return details. Every sentence adds value; no fluff. Slightly verbose but justified for a discovery 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 no output schema and 6 parameters, the description covers purpose, when to use, return format (top-N tools with schemas), and parameter aliases. Sufficiently complete for agent to use 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 6 parameters all described. Description adds examples, clarifies aliases for 'query' (task, q, description, search), and provides usage examples. Adds meaning beyond schema.

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

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

The description precisely states 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, FDA drugs, etc.). It clearly distinguishes this meta-tool from sibling tools which are domain-specific endpoints.

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 '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 for...' Lacks explicit exclusion for 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?

Beyond annotations (readOnlyHint, etc.), the description details the multi-source fan-out, specific outputs (cik, filings with URIs, fundamentals, patents with sunset note, news fallback, LEI), and parameter constraints. It adds significant behavioral context without contradicting annotations.

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

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

The description is dense but well-organized: front-loaded with examples, then a general statement, then output details and constraints. Every sentence adds value, though it could be slightly more concise. The structure is clear and scannable.

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

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

Given no output schema and complex behavior, the description is remarkably complete. It lists all output components with examples, explains fallbacks (patents soft-fail, GDELT→GNews), and provides URIs and field names. Limitations are clearly 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%, so baseline is 3. The description reinforces the parameter meanings (type='company', value=ticker or CIK) and adds the critical note that names are not supported, suggesting resolve_entity. This adds value beyond the schema, though it mostly rephrases.

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 concrete user queries like 'Tell me about X' and states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from siblings by saying '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?

It explicitly says when to use: when the user asks for a holistic view. It also tells what not to do: avoid chaining lookups, and that names are not supported—use resolve_entity first. This provides clear context for choosing 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?

The annotations already declare destructiveHint=true and idempotentHint=true, so the description carries less burden. The description adds that the memory is 'previously stored', implying existence, which is useful. 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 extremely concise: two sentences, no fluff. It front-loads the purpose and immediately follows with usage guidelines. 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?

For a simple single-parameter delete tool, the description covers purpose and usage well. It might lack detail on behavior when the key doesn't exist or on the return value, but given the simplicity and good annotations, 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?

Schema coverage is 100% and the schema already describes the 'key' parameter as 'Memory key to delete'. The description does not add meaning beyond what the schema provides, so the 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 'Delete a previously stored memory by key', specifying a verb (Delete) and a resource (memory by key). It also distinguishes from siblings by mentioning 'Pair with remember and recall', making it easy for an agent to understand its 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 explicitly provides when to use this tool: when context is stale, task is done, or to clear sensitive data. It also mentions pairing with related tools, giving useful context. However, it does not explicitly state when not to use it, but the guidance 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?

Adds value beyond annotations by explaining the process (fetch, extract, emit standard markdown) and output format (text blob for site-root/llms.txt). Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description complements 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?

Extremely concise: two sentences plus a bullet list. Every sentence is informative. Front-loaded with action and purpose.

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

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

Covers core functionality, output format, and usage scenarios well. Lacks mention of error handling or site inaccessibility, but for a simple generative tool with good annotations, it is sufficiently complete.

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

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

Schema coverage is 100% so baseline 3. Description adds minor value with URL example and default for max_links, but does not significantly extend beyond schema descriptions.

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

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

Description uses specific verb 'generate' with resource 'llms.txt file' for 'any URL'. It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than AI presence scanning.

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, drafting, auditing competitors) but lacks exclusions or when-not-to-use guidance. No alternatives are mentioned, 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, idempotentHint, and non-destructive behavior, so the description adds little beyond stating the filtering capability. No additional behavioral traits like pagination or data freshness are mentioned.

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 (one sentence with enumeration) and front-loads the main purpose. It could be slightly more structured, but it is effective without excess.

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 (7 parameters, competition context) and the presence of an output schema, the description provides a good overview. It lacks details on ordering or pagination but is adequate.

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 100% schema description coverage, the baseline is 3. The description enumerates filter types (status, date range, etc.) but adds no new meaning beyond what the schema already provides for each 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 uses the specific verb 'List' with the resource 'matches in a competition', clearly distinguishing it from sibling tools like get_team_matches or get_competition_standings.

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 by listing competition-specific filters, but does not explicitly state when not to use it or suggest alternatives like get_team_matches for team-level 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 safety traits (readOnly, idempotent, non-destructive). Description adds minimal extra beyond return format (total/home/away tables). No contradictions.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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 output schema exists, description covers basic functionality. It could mention optional filtering or data freshness, but overall sufficient for a simple lookup 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 all parameters with descriptions (100% coverage). Description does not add meaning beyond schema; the mention of table breakdowns is generic.

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 returns league tables for a competition season, broken down into total, home, and away. This differentiates it from sibling tools like get_competition_matches (matches) and list_competitions (list of competitions).

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 standings but does not explicitly state when to use versus alternatives or exclude other tools. Context from sibling names suggests differentiation, but no explicit 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. The description adds minimal context beyond what data is returned, but does not disclose other behavioral traits like authentication or rate limits.

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

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

The description is a single concise sentence, front-loaded with key information, with 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 the tool's simplicity (1 param, output schema present), the description fully covers purpose and returned data. No need to explain return values since output schema exists.

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

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

Schema coverage is 100%, so the schema already documents the parameter. The description adds no extra meaning 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 verb ('get' implied), resource ('team'), and specific fields returned ('current squad, coach, competitions, venue'). This distinguishes it from sibling tools like get_team_matches that get matches.

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

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

The description implies use when needing team details but provides no explicit guidance on when not to use or alternatives among siblings like entity_profile or get_team_matches.

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 safe, idempotent, read-only behavior. The description adds minimal behavioral context beyond filters, omitting details like pagination or performance.

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 (one sentence) and front-loaded. However, it sacrifices structure by not separating the main action from filter 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?

Output schema exists but the description does not mention return format or pagination (though limit parameter hints at it). The missing 'competitions' filter reduces completeness.

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

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

Schema coverage is 100% but the description mentions 'competitions' as a filter, which is not present in the input schema. This mismatch confuses parameter meaning.

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

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

The description clearly states 'A team's matches across competitions' with specific verbs and resource. It distinguishes from sibling like 'get_competition_matches' which focuses on a single competition.

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 filtering capabilities but does not explicitly state when to use this tool versus alternatives like get_competition_matches. It lacks exclusion 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 readOnly, idempotent, non-destructive. Description adds plan-dependent behavior (free tier: 12 majors) which is useful context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with main purpose, no wasted words. Very 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 zero-parameter tool with output schema, description covers purpose, usage, and output semantics completely. 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?

No parameters, schema coverage 100%. Description adds value by explaining the output field `code` and its use downstream.

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 verb and resource: 'List competitions accessible on your plan'. It distinguishes from sibling tools like get_competition_matches by focusing on listing, not matches or standings. The mention of free tier and majors adds specificity.

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

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

Explicitly says to use output `code` for downstream calls, indicating it's a prerequisite for other tools. Implicitly suggests when to use (to get list of competitions). Could be more explicit about 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 cover readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds that it lists active subscriptions by default and mentions the include_inactive parameter's effect, providing helpful 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?

Two concise sentences: first states purpose and returns, second gives usage guidance. 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?

Despite no output schema, the description lists return fields. The tool is simple with one optional parameter, and the description covers purpose, parameters, and usage context completely.

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 single optional parameter include_inactive. The tool description adds minimal extra value, only implying the default active filter.

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 lists the caller's active subscriptions and specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Explicitly advises using this tool before adding more subscriptions or to find an ID for cancellation. Provides clear context but lacks explicit when-not 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?

Description adds key behavioral details beyond annotations: rate limit (5 per identifier per day), free usage, no quota impact, and how feedback is processed (daily digests, roadmap influence). 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?

Description is compact, front-loaded with purpose, and every sentence adds value. No fluff or repetition.

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

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

Given the simplicity of the tool (feedback submission), the description fully covers usage, behavior, and constraints. Output schema is not needed. Schema covers all parameters. Complete guidance 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 covers 100% of parameters with descriptions. Tool description adds extra context for the 'type' enum (explains each value) and advises against including end-user prompts. For 'context' and 'message', schema descriptions are sufficient; minor additional 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?

Description clearly states the tool is for sending feedback about broken, missing, or needed functionality (bug, feature/data_gap, praise). It uniquely identifies itself among siblings (no other feedback tool exists).

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 when to use each feedback type, advises against pasting end-user prompts, and mentions rate limits and free usage. Provides clear context for appropriate 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?

The description adds significant behavioral context beyond annotations: it explains the data source (CF analytics-engine), that no PII is involved, the caching behavior (5min-1h), and the non-destructive nature. Annotations already indicate read-only and idempotent, but the description enriches with specifics.

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, front-loading the main function in the first sentence, then using bullet points for use cases and a final sentence for data handling details. Every sentence adds value without redundancy, achieving high information density.

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 the tool's simplicity (one parameter, no output schema), the description covers all necessary aspects: return values, data source, caching, use cases, and behavioral notes. The annotations complement this, making the description complete for effective tool selection and invocation.

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

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

The input schema already provides full coverage (enum and description) for the single window parameter. The description adds value by explaining the semantics of shorter vs. longer windows ('surface what's hot right now' vs. 'show steady-state demand'), offering insight 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 returns 'top tools, top packs, and total call volume' for a specified time window, using specific verbs and resource identification. It distinguishes itself from sibling tools by focusing on trending usage data, a unique offering among the listed 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 provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) that guide when to use the tool. While it doesn't explicitly state when not to use or name alternatives, the context is clear and the guidelines are actionable.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing internal logic (monotonicity checks, partition-sum checks, semantic anchor, partition filter, fill check) and response structure. 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 lengthy but well-organized, with clear sections and examples. It covers all necessary details without redundancy. While not extremely concise, the length is justified by the tool's complexity.

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

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

No output schema is provided, but the description thoroughly explains the response structure (opportunities[] with fields, partition_check details, fill_check behavior) and edge cases. This ensures the agent understands what to expect and how to interpret results.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value by explaining each mode in depth, providing example slugs and topics, and noting that full URLs are accepted. 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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This is a specific verb and resource, and it distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique methodology.

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 explains when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also mentions alternatives like polymarket_fill_risk for custom sizing, providing clear usage guidance and exclusion cases.

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 goes far beyond by detailing internal logic (model families, cached with 1h keyed on knobs), tradeable-edge filters, and response diagnostics. 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 quite verbose, with extensive detail on model families and internals. While well-structured with numbered segments and bold headings, it could be more concise. The front-loaded purpose is clear, but the density may overwhelm 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 has 9 parameters, no output schema, and complex behavior, the description comprehensively covers response structure (by_segment, fed_candidates, diagnostics), caching behavior, and all parameter interactions. No gaps in contextual information.

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

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

Schema coverage is 100% with good descriptions. The description adds context beyond schema, such as explaining how min_partition_leg_kelly applies to partition overround and how tradeable-edge knobs filter opportunities. This adds meaning without redundancy.

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

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

The description clearly states it scans Polymarket markets for edges where Pipeworx data disagrees with market price, and specifies the use case 'what should I bet on today'. It does not explicitly differentiate from sibling tools like polymarket_arbitrage, but the unique focus on Pipeworx disagreement provides sufficient distinction.

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 context for when to use ('discover opportunities without paging hundreds of markets') and explains the segments and knobs. It does not explicitly mention when not to use or alternatives, but the context is sufficiently clear for an AI agent.

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, etc. The description adds significant behavioral context: snapshots written on cache-miss, gaps meaning no scan, history bounded by 60-day TTL, decay from daily closes not intraday. 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 relatively long but well-structured and front-loaded with the core purpose. Every sentence adds value, though some redundancy exists. It could be slightly trimmed but remains informative without waste.

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 details the expected response: tracked[] with fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. This is comprehensive for a tool of this 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 description coverage is 100%, so the baseline is 3. The description mentions defaults and clamping but these are already in the schema. No additional semantic value is added beyond what the schema provides.

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

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

The description states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes from likely siblings like polymarket_edges by focusing on historical time-series rather than current snapshot, and gives an example contrasting fresh vs old 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?

It clearly says when to use: to understand edge history and decay. It does not explicitly list when not to use or name alternatives, but the context implies siblings like polymarket_edges serve different purposes (e.g., current edges). The guidance is strong but not exhaustive.

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 context beyond annotations: it 'walks the ladder', returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, and verdict, and warns about partial fills causing directional risk. No contradiction with annotations. The bar is lowered due to existing annotations, so a score of 4 is appropriate.

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

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

The description is somewhat lengthy but well-structured, using bold headers for modes and bullet points for return fields. Every sentence adds necessary information, though a slightly tighter rewrite could improve conciseness. Front-loaded with purpose and usage guidelines.

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 parameters, no output schema, and complex behavior (two modes, multiple return fields), the description is remarkably complete. It details input parameters, return values for each mode (top_of_book, vwap fill, slippage, verdict, etc.), and even warns about thin legs and directional risk. No missing information for an agent to use this tool correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The tool description adds further meaning: e.g., `size_usd` is clarified for single-market vs basket, `side` default logic (auto for basket), and `market` vs `event` distinction. This adds value 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 states it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly distinguishes between single-market and basket modes. It uses specific verbs ('walks the ladder', 'returns') and differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial baskets create unhedged directional risk) and specifies required parameters (either `market` or `event`).

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 detail beyond annotations: compatibility warnings, temporal alignment, skipped cross types. Annotations already mark readOnlyHint, so description supplements 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?

Well-structured with clear sections and bold keywords, but slightly verbose; every sentence adds value so no waste.

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 output schema, description covers response structure (leg prices, matched spread, safety fields) and edge cases (compatibility warning, temporal alignment). Adequate for 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?

With 100% schema coverage, description adds value by explaining mode interactions and behavior (e.g., topic overrides both sides, explicit tickers override topic).

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 computes cross-venue spread between Kalshi and Polymarket, distinguishing it from siblings like polymarket_arbitrage by emphasizing the 'same resolving question' and two-venue comparison.

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

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

Explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, but lacks explicit '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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds scoping by identifier, which is beyond annotations. No contradictions.

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

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

Two sentences, no fluff. Information is front-loaded 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?

For a simple retrieval tool with one optional parameter, the description is complete. It explains purpose, usage, scoping, and pairing with siblings. 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% and schema describes the single optional parameter well. Description reiterates the behavior of omitting the key to list all keys, adding marginal 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?

Description clearly states it retrieves a saved value or lists keys, with specific verb and resource. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says when to use (to look up stored context) and provides examples. Does not explicitly state when not to use, but context is sufficient.

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

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

The description discloses the mark_read behavior, which is a side effect not fully captured by the readOnlyHint annotation. It also notes polling works fine, confirming idempotency. This adds value beyond annotations, though the mark_read feature contradicts the readOnlyHint.

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) and front-loaded with the purpose. Each sentence contributes essential information: what is returned, filtering, mark_read effect, and alternative access. 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 the lack of output schema, the description partially covers return fields (source, citation_uri, raw payload). It explains filtering and mark_read, but does not address pagination or limit behavior beyond schema. Still adequate for correct tool 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 coverage is 100%, so the description adds little beyond the schema. It restates filtering by type and since, but does not introduce new parameter meaning or examples. 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 'Pull fired events from your subscription feed', specifying the action (pull) and resource (fired events). It also details what each event carries (source, citation_uri, raw payload), distinguishing it from sibling tools like list_subscriptions.

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

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

The description mentions filtering options (type, since) and polling suitability. It also provides an alternative HTTP endpoint for scripts, offering usage context. However, it does not explicitly state when to avoid this tool or compare it to alternatives.

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

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

Beyond annotations (readOnlyHint, etc.), the description details fan-out to multiple sources, fallback behavior (GDELT preferred, GNews on rate limit), soft-fail for USPTO, and return structure (changes[], total_changes, citation URIs). Adds significant context.

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?

Every sentence is informative, front-loaded with user question examples. No fluff; compact yet comprehensive.

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

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

Given no output schema and three required params, the description adequately explains return format, data sources, fallback behavior, and includes a comparison with sibling tool. Covers all necessary aspects for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial value: explains 'since' accepts ISO date or relative shorthand with examples, suggests using '30d' or '1m', clarifies 'value' accepts ticker or CIK, and notes 'type' is only 'company' for now.

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 a change feed for a company in a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and examples of user queries. It distinguishes from sibling tool 'entity_profile' by specifying when to use the alternative.

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 directs users to use 'entity_profile' for static profiles, providing a clear alternative. It includes example queries for typical use cases but does not explicitly state when not to use this tool.

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

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

Annotations are already present (idempotentHint=true, etc.), and the description adds valuable behavioral context beyond annotations: authentication-based persistence and 24-hour retention for anonymous sessions. 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 concise with 5 sentences, each providing essential information without redundancy. It is well-structured, front-loaded with the primary action 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 simplicity, high schema coverage, and presence of annotations, the description covers all necessary aspects: purpose, usage, persistence behavior, and relationship to sibling tools.

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

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

Schema coverage is 100% with clear parameter descriptions. The description does not add new meaning beyond the schema, so a 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: to save data for later reuse. It uses specific verbs and resource ('Save data' and 'memory key-value pair'), and distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning them.

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

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

The description provides explicit guidance on when to use the tool ('when you discover something worth carrying forward') and mentions complementary tools ('recall' and 'forget'). It also notes scoping and persistence details, aiding decision-making.

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. Description adds that each call cascades through multiple endpoints, which is useful 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?

Single paragraph with clear structure, uses backticks for examples, front-loaded with usage patterns. Every sentence adds value.

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

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

No output schema exists, so description compensates by detailing return values (ticker, CIK, URI; RxCUI, brand). It also explains internal cascading workflow, making the tool's behavior 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 covers both parameters (100% coverage). Description adds examples, input variations (ticker, CIK, name), and notes auto-disambiguation, enriching 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?

Description clearly states it resolves names to canonical IDs (ticker, CIK, RxCUI) and contrasts with sibling tools like compare_entities and entity_profile by specifying its role as a lookup-preparation step.

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 instructs 'Use FIRST whenever you have a name but need an ID.' It provides supported entity types and input formats, setting clear expectations for when to invoke.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it uses ai_visibility_check per entity and returns a ranked list with score, confidence, signal density. This provides behavioral context beyond annotations, such as the specific sub-tool used and output structure. No contradictions.

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

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

Three sentences, front-loaded with the primary action. Each sentence earns its place: purpose, method, example use case. No fluff or repetition. Efficiently structured for quick parsing.

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 explains the return format (ranked list with score, confidence, signal density per entity). It covers the main use case and parameter constraints (2-8 entities). However, it doesn't mention error handling or edge cases (e.g., if an entity is not found). Still adequate for typical 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?

Input schema covers all 4 parameters with descriptions (100% coverage). Description adds value by noting that 'entities' first entry is treated as 'subject' for narrative, and for 'models' it clarifies 'Omit for just workers-ai'. This syntax nuance is not in schema, enhancing agent 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?

Description clearly states the tool's core function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probes, ranks, surfaces) and the resource (AI presence). It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility ranking.

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 advises when to use: 'Useful for competitive AI-marketing audits' and provides a concrete example question. It does not explicitly state when not to use or list siblings as alternatives, but the context implies for single entity use ai_visibility_check. Lacks explicit exclusion but is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), the description reveals that it fans out to external services, partial failures degrade gracefully with sources_failed, bundlephobia's first measurement can take 5-30s, and the return structure includes a summary block, advisories, links, and alternative versions.

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 the main purpose, but it is somewhat long. Every sentence adds value, covering purpose, usage, behavior, and return values. A minor deduction for verbosity, but overall appropriate for the tool's complexity.

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

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

Given there is no output schema, the description thoroughly details the return values (summary block fields, advisories, links, alternative versions), behavior on partial failures, and timing caveats. All necessary context for an agent to invoke the tool correctly is provided.

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

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

Schema coverage is 100%, so the schema already describes both parameters (package name with scoped packages, version with default to latest). The description does not add significant semantics beyond the schema; it mostly repeats the same information. A score of 3 is appropriate as the schema carries the burden.

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 this tool performs a composite check for adding npm packages, fanning out to deps.dev and bundlephobia. It specifies the scope (NPM ecosystem only in v1) and distinguishes from alternatives by noting that other ecosystems fall under 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?

Explicitly mentions when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides when-not-to-use guidance (non-NPM packages) and directs to alternative (deps.dev:version directly). Partial failure handling is also described.

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 details beyond the annotations: it specifies the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and the 200K char limit with truncation flagging. The annotations already declare readOnlyHint, idempotentHint, etc., and the description complements this 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 concise and well-structured: it front-loads the core purpose, then adds usage guidance, behavioral details, and limitations. Every sentence adds value without unnecessary fluff. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description explains the return format (passages with character offsets and similarity scores). It covers limitations (200K char cap, truncation), embedding details, and pairing with a sibling tool. The description is complete for an agent to understand input, output, and constraints.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for the query parameter (e.g., 'supply-chain risk') and clarifying the text max length and limit range. It also explains how the parameters relate to the tool's behavior, which goes beyond the schema descriptions.

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

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

The description clearly states it performs semantic search inside a fetched record, provides examples (SEC 10-K, article), and specifies it returns top-N passages with offsets and similarity scores. It also distinguishes itself from sibling ask_pipeworx_grounded by mentioning pairing, making its purpose specific and well-articulated.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also mentions pairing with ask_pipeworx_grounded and warns about the 200K char cap and truncation. However, it does not explicitly state when not to use it or list alternative tools beyond the one 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?

Annotations already indicate non-readOnly (mutation) and idempotent. The description adds valuable behavioral details: webhook secret returned once, auto-disable after 10 failures, SMS cap, and phone verification requirement. These are beyond annotation scope. 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 fairly long but every sentence provides essential information. It is front-loaded with the primary purpose and then details. Could benefit from bullet points for clarity, but current prose is structured and readable.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers return values (subscription id, webhook secret). It also explains delivery behavior and constraints. Missing explicit error handling or full response structure, but sufficient for a subscription creation tool.

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

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

With 100% schema coverage, the description significantly enriches parameter meaning: for each 'type', it gives real-world examples (e.g., 'sec_8k' items codes like '5.02' for officer change). It explains the 'delivery' object in detail, including webhook HMAC signing and SMS verification. This adds substantial 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 it creates a proactive monitoring subscription and returns the subscription ID. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation. Supported types and their parameters are listed with examples, making the purpose highly specific.

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

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

The description provides clear context on when to use (creating a subscription) and prerequisites (OAuth account, phone verification for SMS). It also mentions limitations (anonymous/BYO cannot persist, 10/day SMS cap). While it doesn't explicitly exclude other tools like 'recent_alerts' or 'polymarket_edges', the guidance is adequate for most agents.

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 behavioral context by explaining the output structure (category-bucketed examples with tool+argument shapes) and that it draws from a live catalog, which goes beyond the annotations.

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

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

The description is relatively long but efficient, front-loaded with user question examples and a clear purpose. Every sentence adds value, though minor trimming could improve conciseness. 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?

Given no output schema, the description fully explains return values (category-bucketed questions with tool+argument shapes) and behavior with and without arguments. It also places the tool in the broader onboarding context, making it highly complete for a 1-parameter 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 one optional 'topic' parameter described. The description adds value by listing example values (finance, pharma, etc.) and clarifying that omitting it returns a cross-category spread, which enriches the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool calls, and explicitly distinguishes itself as the onboarding entry point for learning what Pipeworx can do. It uses specific verbs and resources, and differentiates from sibling meta-tools like ask_pipeworx and discover_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 specifies when to use the tool ('FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools') and how to adjust behavior (no arguments vs. passing 'topic'). While it doesn't explicitly state when not to use, the guidance is clear and actionable.

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

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

Annotations already indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false) behavior. The description adds valuable context about ownership enforcement and row deactivation for preserving historical events, which goes beyond 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?

Two sentences, no fluff, front-loaded with the primary action. Every sentence adds essential information. Perfectly concise.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all necessary aspects: purpose, ownership constraint, behavioral impact, and historical data preservation. It leaves no gaps for an agent to misinterpret.

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

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

Schema coverage is 100%, and the schema already documents the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add further parameter-level detail but reinforces the source of the id, providing marginal 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 clearly states 'Cancel a subscription by id' which is a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and the effect of deactivation rather than deletion.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains the non-destructive nature ('deactivated, not deleted'). While it does not provide explicit alternatives or when-not-to-use scenarios, the context is clear enough for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds value by detailing return verdict types, structured form, actual value with citation, and percent delta, as well as noting it replaces multiple calls. 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?

Well-structured and front-loaded with trigger phrases, then use case, scope, and return information. Every sentence adds value; no wasted words. Length is appropriate for the tool's complexity.

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

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

Despite only one parameter and no output schema, the description is complete: explains what it does, when to use, what it returns, its scope, and why it's efficient. No gaps for an agent to need additional context.

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

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

Only one parameter 'claim' with 100% schema coverage. Description provides rich context: examples of natural-language claims, the supported domain (company-financial), and implies the format (natural-language). Adds significant value beyond the schema 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 it's for claim verification/fact-checking with specific examples ('Is it true that...' / 'fact check'), and distinguishes itself by noting it replaces 4-6 sequential calls, setting it apart from 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes it to company-financial claims via SEC EDGAR. Does not explicitly state when not to use, but the scope implies it's only for financial claims, so excluding alternatives like deep_research is implied.

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