Twilio

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds behavioral details: it probes LLMs, returns per-model scores, and notes that Anthropic calls require a BYO key and incur external costs. It does not cover error handling or rate limits, but the added value over annotations is moderate.

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, well-structured paragraph that front-loads the core action ('Probe one or more LLMs'), then succinctly covers return format, default model, optional parameters, and use cases. No unnecessary words; every sentence earns its place.

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

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

Given the lack of an output schema, the description adequately explains the return structure (per-model fields and combined view). It covers all important aspects: entity, models, API key, context. For a tool with 4 parameters and a clear purpose, this is complete and actionable.

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 meaning by clarifying the default model ('Workers AI Llama-3.3-70b (free)'), the BYO key requirement for Anthropic, and the purpose of the 'context' parameter for disambiguation. This provides useful nuance 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 the tool probes LLMs for entity knowledge and scores visibility (0-100) per model. It uses specific verbs ('probe', 'score') and identifies the resource ('business/brand/product/topic'). The mention of return fields and use cases (AI-marketing audits) makes the purpose unambiguous.

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

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

The description provides context on when to use it ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. BYO key models. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' or 'compare_entities', nor does it state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds valuable context: it routes to 3,770 tools, returns structured answers with stable citation URIs, and covers authoritative structured data. No contradiction with annotations.

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

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

The description is concise at ~150 words, front-loaded with the key recommendation, and efficiently covers domain list, operation, usage cues, and examples without redundancy.

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

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

For a tool with no output schema, the description explains it returns structured answers with citation URIs. It covers the routing mechanism to many tools but omits fallback behavior for out-of-scope queries. Overall, it's sufficiently complete for the tool's purpose.

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

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

Schema coverage is 100% with a single required question parameter and five aliases. The description provides example queries that show how to phrase questions, adding meaning beyond the schema's property descriptions.

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

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

The description clearly states the tool routes questions to thousands of verified sources for factual answers, listing specific domains like SEC filings, FDA drugs, economic stats, etc. It distinguishes itself from web search with 'PREFER OVER WEB SEARCH' and provides example queries.

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

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

The description explicitly recommends using this tool over web search for factual questions and gives examples of when to use it ('what is', 'look up', 'find', etc.). It lacks explicit when-not-to-use guidance but the positive guidance is strong and clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds substantial behavioral context: hallucination resistance, explicit refusal reasons (not_in_source, no_tool_match, etc.), and extra LLM call cost. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with key purpose and usage. However, it is somewhat verbose with multiple clauses. Still efficient and clear, but could be slightly tighter.

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 no output schema and 6 aliased parameters, the description compensates by detailing the return structure (answer, evidence, confidence, etc.) and refusal reasons. It covers key behavioral and output aspects completely for a complex routing tool.

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

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

Schema description coverage is 100% with each alias documented. The description does not add parameter-level details beyond explaining that question accepts multiple aliases. Baseline 3 is appropriate as schema already covers 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: picks the right tool, fills arguments, fetches data, and extracts answer solely from tool result. It distinguishes from the sibling ask_pipeworx by noting extra cost and different use case.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not: 'prefer ask_pipeworx for casual lookups.' Provides concrete examples like 'financial verdicts, legal claims, medical lookups, public statements.'

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

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

Annotations already declare read-only and idempotent behavior. The description adds extensive behavioral context: resolver contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback mechanism (429s, backfill), handling of closed markets, wide spread tradeability, resolution-rule risk, and even arb-bot ledger anecdotes. No contradiction.

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

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

The description is front-loaded with the core purpose and usage, then proceeds with detailed examples and edge cases. It is somewhat verbose but well-structured with sections (classifiers, fan-out examples, response shapes). Every sentence adds value, though it could be trimmed for an agent without losing essential information.

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

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

The tool has 3 parameters and no output schema, yet the description fully explains the response shape (result.market, result.analysis, result.evidence) and covers all critical edge cases: low-confidence matches, closed markets, wide spreads, cancellation rules, and fallback mechanisms. It is exceptionally complete for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining parameter usage in context (e.g., market input types, depth default behavior, include_raw impact on response size). However, the schema already includes clear descriptions, so the increment is modest.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and the action (research with data pull), and distinguishes from siblings by focusing on Polymarket bet research with Pipeworx data. The use cases ('should I bet on X', etc.) further clarify 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 provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when not to trust results via resolver contract and low-confidence matches. However, it does not compare directly to sibling tools like polymarket_edges or polymarket_arbitrage, missing an opportunity to guide tool selection.

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 not destructive. The description adds valuable context: it pulls latest SEC 10-K data for companies handling off-calendar fiscal years, and FAERS data for drugs, includes sorting by primary metric, and returns citation URIs. No contradiction.

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

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

The description is front-loaded with example queries, then describes data sources and special handling, all in 3-4 sentences. It is efficient and structured, though slightly long for a simple tool. Still, every sentence adds value.

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

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

Given no output schema, the description explains return includes paired data + citation URIs and sorting. It covers entity types and data sources comprehensively. The annotations handle safety/idempotency. Could explicitly list return fields, but overall complete.

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

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

Schema coverage is 100% with descriptions. The description adds meaningful context: explains 'company' pulls 10-K data and 'drug' pulls FAERS data, gives examples for values (tickers/CIKs, drug names), and specifies min/max items. This enhances understanding beyond schema.

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

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

The description clearly states it performs side-by-side comparison of entities (companies or drugs) with example queries like 'X vs Y' and 'rank these companies'. It distinguishes from sibling tools by specifying it replaces multiple sequential lookups, and the name and title align.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also differentiates from siblings like entity_profile by emphasizing parallel comparison.

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 behavioral traits beyond annotations: decomposition into sub-questions, parallel routing, extraction of grounded answers with gaps array (never invented), pre-verified facts, and citation format. Annotations only note readOnly, openWorld, idempotent, non-destructive; description adds critical process and output details.

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

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

Front-loaded with key capability and then structured into specifics. Slightly long but every sentence adds value. Could trim 'in ONE call' redundancy with title, but overall efficient.

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

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

Given the tool's complexity (parallel multi-source research across 3,772 tools) and no output schema, the description fully explains return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps). Covers prerequisites, constraints, and timing. Completely fills the informational gap.

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

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

Schema coverage is 100%, and description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies that question is natural language and decomposition is intended. Adds value beyond the minimal 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 specifies the tool's verb ('researches'), resource ('multi-source research in ONE call'), and mechanism (decomposes, routes to 3,772 tools across 894 sources in parallel). It distinguishes from sibling ask_pipeworx by contrasting single vs. multi-facet 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 states when to use ('broad or multi-part questions') and when not to use ('single lookups' → use ask_pipeworx). Also covers prerequisites (Pipeworx account, paid plan for 'thorough'), expected duration (15-60s), and depth selection.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so safe. Description adds that it returns top-N tools with full schemas and curated examples, and that results are ready to call directly. 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?

Front-loaded with core purpose, but the list of domains is somewhat lengthy. Everything is relevant and no wasted sentences.

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

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

No output schema, but description explains what is returned (names, descriptions, schemas). Covers the use case well, including limit parameter. Lacks explicit return format details but sufficient.

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

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

Schema description coverage is 100%, so the schema already documents parameters. Description adds examples of queries and mentions alias parameters, but doesn't add significant new meaning beyond schema.

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

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

Clearly states 'Find tools by describing the data or task' and enumerates specific domains. Distinguishes from siblings by emphasizing 'discover what tools exist' and 'call this FIRST, not just one answer'.

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: 'when you need to browse, search, look up, or discover what tools exist'. Also says 'Call this FIRST when you have many tools available and want to see the option set'.

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), the description reveals internal fan-out across sources, includes a note about patents API sunset and soft-failure, and details what each source contributes. 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 detailed and front-loaded with example queries, but it is somewhat verbose. Every sentence contributes value, making it well-structured, though a bit lengthy.

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 absence of an output schema, the description comprehensively lists what is returned (CIK, filings, fundamentals, patents, news, LEI) and explains fallbacks and limitations. It is complete 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 coverage is 100%, so baseline is 3. The description adds significant context: type is limited to 'company' for now, value must be ticker or CIK (zero-padded), and names are unsupported. This enriches the schema definitions but does not introduce new parameters.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call,' listing example queries and distinguishing itself from chaining individual lookups. It is a specific verb-resource combination that differentiates from siblings like 'resolve_entity' and 'deep_research'.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies input limitations: ticker or zero-padded CIK only, not names, and directs to use 'resolve_entity' first if only a name is available.

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 mentions 'clear sensitive data' beyond annotations' destructiveHint. No contradiction with annotations. Adds context about data sensitivity.

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 efficient sentences, front-loaded purpose, then usage guidance. No wasted words.

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

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

Simple tool with one parameter and no output schema. Description covers purpose, usage, and sibling context, making it complete for its complexity.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Tool description adds no extra meaning beyond schema's parameter description.

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

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

Description states 'Delete a previously stored memory by key' - specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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

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

Description explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It pairs with remember and recall, but doesn't explicitly state 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral detail: fetches the page, extracts title/description/key links, and emits markdown format. 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 concise (two sentences plus bullet list), front-loaded with action, and every sentence serves a purpose. No wasted words.

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

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

For a simple tool with 2 parameters, no output schema, and rich annotations, the description covers purpose, process, and use cases. Lacks error handling or output format details, but adequate overall.

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 minimal value: an example for 'url' but nothing for 'max_links'. It does not elaborate on parameter constraints beyond the schema.

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

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

The description explicitly states the verb 'Generate' and the resource 'llms.txt file', explaining its purpose for AI crawler indexing. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It clearly indicates when to use the tool, though it 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, destructiveHint=false, openWorldHint=true, idempotentHint=true, so the description adds minimal behavioral context beyond listing return fields. This is adequate given the annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, well front-loaded with essential information.

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

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

With one optional boolean parameter, full schema coverage, and annotations, the description is largely complete. It lists return fields and usage context. Could mention ordering or pagination, but not essential for this simple tool.

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

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

Schema coverage is 100%, and the parameter 'include_inactive' is fully described in the schema. The description does not add extra meaning beyond what the schema provides, so 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 'List the caller's active subscriptions' and lists the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe. It also provides a specific use case: reviewing monitoring before adding more or finding an ID to cancel.

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

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

The description explicitly tells when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies not to use for subscribing or unsubscribing, but lacks an explicit 'do not use when X' statement.

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 behavioral context beyond annotations: rate-limited to 5 per identifier per day, doesn't count against quota, and signals directly affect roadmap. Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description significantly enhances the understanding of the tool's behavior.

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

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

The description is front-loaded with the action and purpose, then provides usage guidelines and notes. It uses concise sentences with no redundancy. Every sentence serves a purpose, making it both informative and efficient.

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

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

Given the tool's simplicity and lack of output schema, the description completes the picture: it explains what happens after submission (team reads digests, signals affect roadmap). No missing information for an agent to understand the tool's value and behavior.

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

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

With 100% schema description coverage, the description still adds value by explaining enum values (bug, feature, data_gap, praise, other) in plain language, specifying message length limit (2000 chars), and describing optional context fields (pack, tool, vertical). This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and the context distinguishes it 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?

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and provides usage notes like rate limit (5 per day) and that it's free. It gives clear criteria for each feedback type, making it easy 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=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the tool's safety profile is clear. The description adds valuable context beyond annotations: data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'), making behavior fully transparent.

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 three sentences and a bullet list, front-loading the main action. Every sentence provides distinct, non-redundant information, and there is zero 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?

Given the tool's simplicity (one optional parameter, no required params, clear annotations, no output schema), the description is complete: it explains the return value (top tools, packs, volume), use cases, data source, privacy, and caching. Nothing essential is missing.

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

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

The schema already provides enum descriptions for the single parameter 'window', achieving 100% coverage. The description adds further value by explaining the semantic difference between window lengths ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema's static 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 returns top tools, top packs, and total call volume over a recent window, using the verb 'returns' and specifying the resource. However, it does not explicitly distinguish itself from sibling tools like 'discover_tools' or 'ask_pipeworx', though its unique purpose is implied.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment) which provide clear context for when to use the tool. It does not mention when not to use it or suggest 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 indicate read-only, open-world, idempotent, non-destructive. Description adds substantial behavioral context including algorithmic details (monotonicity, partition check), fill check mechanics, and similarity thresholds—all consistent 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 lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes value; slight verbosity is justified by tool complexity.

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

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

Given the tool's complexity, absence of output schema, and rich annotations, the description is remarkably complete. It covers input requirements, algorithmic behavior, edge cases, and links to related tools. No gaps.

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

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

Schema already describes both parameters. Description adds significant extra meaning: explains the difference between event and topic modes, provides example inputs, and describes the logic applied to each. Valuable beyond schema.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and includes specific examples of slugs and topics, making the purpose unambiguous.

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

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

Explicitly states that exactly one of 'event' or 'topic' must be provided, with clear guidance on when to use each mode. Also advises on fill check and custom sizing via sibling tool, leaving no ambiguity.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds immense detail: model families, Kelly sizing, slippage, caching, diagnostics, and tradeable-edge filters, far exceeding annotation info.

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 bold terms and parentheses, but very long and dense. Every sentence adds value, but the length may overwhelm some agents. Could be tighter.

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?

Explains response structure (by_segment, diagnostics) and edge cases (Fed bets, empty segments) even without an output schema. Covers caching and diagnostics so callers understand why results might be empty.

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, but description adds significant context for parameters like min_kelly (half-Kelly fraction) and slippage_pp (Polymarket fees), making them more actionable.

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 and returns opportunities where Pipeworx data disagrees. It specifies three model families and is built for 'what should I bet on today', distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Clear context on when to use (daily betting decisions) and what knobs to adjust. No explicit exclusions or comparisons with alternatives, but the description provides enough detail for an agent to choose appropriately.

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 readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: snapshot write-on-cache-miss, gaps meaning no scan, 60-day TTL, decay from daily closes. 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 detailed and well-structured, starting with the core purpose and then elaborating on response fields and limits. While every sentence adds value, it is slightly verbose, earning a 4 rather than a 5.

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

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

Without an output schema, the description comprehensively explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, start date). It covers all necessary context for an agent to understand what the tool returns.

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 fully describes both parameters (days, window) with defaults and constraints. The description merely restates them without adding extra meaning, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: providing edge persistence and decay telemetry from daily snapshots. It distinguishes between fresh and old wide edges, and the detailed response structure sets it apart from sibling tools like polymarket_edges.

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

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

The description explains when to use the tool (to understand edge persistence and decay), but does not explicitly mention when not to use it or name specific alternatives, though the sibling list provides context.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) indicate a read-only check. Description adds behavioral context: it walks the order book ladder, returns fill details and a verdict, and warns about partial basket fills converting arb into unhedged positions. No contradiction with annotations. However, it could explicitly state it does not execute trades.

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 details requirements and modes, ending with use-case guidance. Every sentence adds necessary information. Slightly long (~200 words) but justified by tool complexity. Could be more concise without losing clarity.

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

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

Despite lacking an output schema, the description thoroughly explains return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and basket-specific returns (theoretical_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It addresses the key risk of partial fills, making it complete for a complex tool.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The tool description adds value by clarifying parameter interdependencies (e.g., REQUIRES one of market or event), different interpretations of size_usd between modes, and default side logic for baskets. This goes beyond the schema's baseline information.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It defines two modes (single-market and basket) and explicitly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their signals.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills lead to directional risk), giving clear when-to-use and when-not-to-use context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: two modes, compatibility_warning conditions, temporal_alignment field, skipped_cross_type/counters, and note that pre-mapped topics often return warnings. This goes far beyond what annotations provide, fully disclosing behavior.

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

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

The description is relatively long but well-organized with sections for modes, response, and safety fields. It is front-loaded with the core purpose. While every sentence adds value, some redundancy could be trimmed, but overall structure is effective.

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

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

Given the tool's complexity (cross-venue comparison with edge cases) and no output schema, the description thoroughly explains the return fields: leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and skipped counters. It addresses all necessary behavioral aspects for correct invocation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by explaining the topic list, the relationship between topic and explicit parameters, and provides examples. This enriches the schema beyond mere field names.

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

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

The description clearly states it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit pairing) and explains the output. This is a specific verb+resource description that differentiates from sibling tools like polymarket_arbitrage.

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

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

The description gives explicit when-to-use context: 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so.' It warns that most pre-mapped topics return compatibility warnings and explains temporal alignment. While it does not explicitly name sibling alternatives, the detailed context enables an agent to decide appropriateness.

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 ensure read safety; description adds valuable context about scoping and pairing with remember/forget, no contradictions.

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

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

Two sentences, front-loaded with purpose, no redundant information.

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

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

Covers all necessary aspects for a simple tool: retrieval, listing, scoping, pairing, and usage scenarios.

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?

Description essentially restates the parameter schema, which already has 100% coverage, so minimal added value beyond baseline.

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

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

Description clearly states the verb (retrieve/list), resource (saved values/keys), and distinguishes from siblings (remember, forget) with concrete usage examples.

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

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

Provides explicit when-to-use context (lookup saved data) and scoping (per identifier), but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds meaningful behavioral context like mark_read side effects and alternative feed endpoint, without contradicting annotations.

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

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

Single paragraph is concise and front-loaded with key action. Every sentence adds value, though a more structured format (e.g., bullet points) could improve readability.

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

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

Covers return fields and key behaviors (mark_read, filtering). Lacks pagination details beyond limit, but sufficient for a list-retrieval tool without output schema.

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

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

Schema coverage is 100%, and the description adds real value by explaining parameters in context (e.g., filter by type, mark_read for read tracking). Complements schema effectively.

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 pulls fired events from the subscription feed and returns recent alerts with specific fields. It distinguishes itself from sibling tools, none of which target alert retrieval.

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

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

Provides clear usage context: mentions polling is fine, offers alternative access via URL, and explains filtering options. However, it does not explicitly compare to siblings or state 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, idempotentHint, openWorldHint, and non-destructive behavior. The description adds substantial behavioral context: it details the multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-failure), explains the fallback logic, and mentions the return format (changes[] grouped by source, total_changes, pipeworx:// URIs). 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 verbose but well-structured: it starts with example queries (front-loaded), then explains sources, parameter details, and alternatives. Every sentence adds value, though a slight trim 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 complexity (multiple sources, fallback, soft-failure) and absence of an output schema, the description adequately explains what the tool returns (grouped changes, total count, citation URIs). It could be more complete by specifying the shape of individual change objects or mentioning limits, but it provides sufficient context for an agent to decide when to use the tool.

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

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

Schema coverage is 100%, so the baseline is high. The description adds significant meaning beyond the schema: it explains the 'since' parameter with examples (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and provides typical usage advice. It clarifies that 'value' can be a ticker or CIK. This guidance is valuable for correct invocation.

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 provides a change feed for a company, with example queries like 'What's new with X' and 'latest on Y'. It distinguishes itself from the sibling tool entity_profile, which is for static profiles. The purpose is specific, concrete, 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 example queries, explains when to use the tool (for change feed queries), and explicitly tells when to use the alternative sibling tool entity_profile ('Use entity_profile instead when you want the static profile...'). It also gives recommended values for the 'since' parameter ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. Description adds context about scoping by identifier, session persistence limits, and pairing with recall/forget, which are not in 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?

Three sentences: purpose, usage guidance, and behavioral detail. Each sentence adds value with no redundancy. Front-loaded with key message.

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 key-value store with two parameters and no output schema, the description fully explains what, when, and how the tool behaves across sessions and authentication states.

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 with descriptions (100% coverage). Description adds example key patterns and clarifies value type, but does not introduce new semantics 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?

Clearly states 'Save data the agent will need to reuse later' with specific verb (save) and resource (data). Distinguishes from sibling tools like recall and forget by naming them and explaining the pairing.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, user preference). Also notes the difference between authenticated (persistent) and anonymous (24-hour) sessions.

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 read-only, idempotent, open-world. Description adds that it cascades through several endpoints, replaces 2-3 manual lookups, and auto-disambiguates. 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?

Description is slightly long but front-loaded with examples and well-organized. Every sentence adds value; could be slightly more concise but not wasteful.

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

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

Despite no output schema, the description fully explains what each type returns (ticker+CIK+citation for company; RxCUI+ingredient+brand+citation for drug). Covers internal cascading and disambiguation.

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

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

Schema coverage is 100%, but description goes beyond by providing concrete examples (e.g., ticker, CIK, name for company; brand/generic for drug) and explaining return fields per type.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific examples and supported types (company, drug). It distinguishes itself from siblings by positioning itself as the first step when an ID is needed.

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 FIRST whenever you have a name but need an ID.' Provides detailed supported types and what they return. Lacks explicit 'when not to use' but is generally clear.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that it ranks entities by score, surfaces most/least recognized, and returns score/confidence/signal density. 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 purpose. Every sentence adds value: purpose, mechanism, example use case. 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 tool's complexity (4 params, orchestration of another tool), the description covers purpose, usage expectations, and output format. No output schema needed as description lists return fields.

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

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

Schema descriptions cover 100% of parameters. Description adds semantics: first entity is treated as 'subject' for narrative. This clarifies parameter usage beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verb-verb 'Compare AI visibility' and resource 'multiple entities'. It distinguishes from sibling 'ai_visibility_check' by describing orchestration of multiple probes.

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 clear usage context ('competitive AI-marketing audits') with an example question. Implicitly differentiates from sibling 'ai_visibility_check' by stating it probes each entity with that tool. Lacks explicit exclusions or alternative tools, but the context is strong.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds critical behavioral details: it is a composite call that fans out to two services, may have partial failures (bundlephobia can take 5-30s), and gracefully degrades by listing sources_failed. This surpasses annotation coverage.

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

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

The description is a single paragraph but efficiently packs information without redundancy. It uses front-loaded structure (composite, use case) and every sentence contributes. A slightly more structured format (e.g., bullet points) could improve readability, but current version is adequate.

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 the return format (summary block with fields, advisory detail, links, alternative versions) and edge cases (NPM only, bundlephobia timing). It provides enough detail for an agent to understand the tool's complete behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages are accepted (e.g., '@types/node') and that the version parameter defaults to latest when omitted. This provides practical context 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 that the tool performs a composite check for evaluating npm packages, using specific verbs ('scan') and resource ('dependency'). It distinguishes itself from sibling tools by focusing on npm ecosystem and combining deps.dev and bundlephobia data.

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 instructs when to use the tool ('when an agent asks is X safe / popular / small') and provides limitations (NPM only in v1) with alternative suggestions for other ecosystems (PyPI, Maven, etc.). This helps the agent decide correctly.

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 annotations: it specifies the embedding model (BGE-base-en), similarity method (cosine), windowing (500-char overlapping), and character cap (200K chars with truncation flag). Annotations already indicate read-only, idempotent, and open-world hints.

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: opening sentence states core function, followed by usage guidance, companion tool mention, and technical details. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity and lack of output schema, the description fully covers input behavior, internal mechanics, limits, and integration context. It implicitly describes return values (passages with offsets and scores) without needing an output schema.

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

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

With 100% schema coverage, the description still adds value by giving examples for the query parameter, clarifying the text parameter's role, and explaining the limit parameter's range. This exceeds 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 clearly states the tool performs semantic search inside a fetched record. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded as a companion and focusing on searching within already-fetched text.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns relevant passages with offsets) and mentions pairing with another tool for grounding.

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 requirements (OAuth account, phone verification) and limitations (10/day SMS cap). The annotations include idempotentHint=true, but the description does not clarify whether creating the same subscription twice returns the existing ID or creates a new one. However, the openWorldHint and readOnlyHint are consistent. Overall, the description adds behavioral context beyond annotations.

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

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

The description is detailed but well-structured, starting with the core purpose, then listing types with examples, and finishing with delivery options. It is slightly dense but front-loads key information without unnecessary 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 tool's complexity (multiple types, optional delivery channels, nested params), the description covers all critical aspects: requirements, type-specific filters, delivery constraints, and the return value (subscription id). No output schema is provided, but the description adequately explains the return.

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

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

Schema coverage is 100%, and the description adds rich examples for each subscription type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}') and elaborates on delivery channels with specific constraints (webhook signing, phone verification, caps). This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (Create), resource (subscription), and distinguishes from siblings like list_subscriptions and unsubscribe by detailing subscription types and delivery channels.

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 context on when to use: it requires a Pipeworx OAuth account, lists supported types with examples, and notes optional delivery channels with constraints (phone verification, 10/day cap). It implicitly guides usage by mentioning the always-on feed and referencing recent_alerts for pulling. However, it does not explicitly state when not to use or compare 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, idempotentHint, openWorldHint), description reveals it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and that omitting topic gives full spread. 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 somewhat long but front-loaded with aliases and purpose. Uses clear structure with examples and bullet points. A bit verbose for the simple tool, but every sentence adds value.

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

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

Given no output schema, description fully explains return structure (category-bucketed example questions with tool+argument shapes). Covers the tool's purpose, usage, and scope completely for a simple, read-only, optional-param 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 describes 'topic' with examples, but description adds value by explaining default behavior (full spread) and listing valid values (finance, pharma, etc.). With 100% schema coverage, the description still enhances 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 defines the tool as 'the onboarding entry point' with aliases and explicit purpose: helping an agent discover what Pipeworx can do and how to call meta-tools. It clearly distinguishes from sibling tools by stating 'use this FIRST' and listing example 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?

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also mentions optional topic to narrow focus. Lacks explicit when-not-to-use, but the context strongly implies it's for initial exploration, not for direct 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 provide readOnlyHint, idempotentHint, and destructiveHint, indicating safe and idempotent behavior. The description adds the specific action of retrieving details by SID, which is consistent and adds minimal context. No contradictions.

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

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

The description is a single concise sentence that front-loads the action and resource. Every word is essential and there is no wasted 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?

Given the low complexity (three simple string parameters), the presence of annotations covering safety/idempotency, and an output schema documenting return values, the description is complete enough for an agent to select and invoke 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 description coverage is 100%, so the schema already documents the three parameters. The description does not add any additional meaning or guidance beyond what is in the schema, meeting the baseline of 3.

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

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

The description clearly states the verb 'Get details' and the resource 'specific Twilio message by its SID'. It distinguishes from sibling tools like twilio_list_messages which lists multiple messages.

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 context is clear: use this tool when you have a specific message SID. No explicit exclusion of alternatives, but the sibling tools are available and the description implies a one-by-one retrieval.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return fields but no additional behavioral traits 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, front-loaded with purpose and return info, no wasted words.

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

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

Adequate for a simple list tool with good annotations and output schema. Missing explicit mention of date range or ordering, but 'recent' implies recency. Mostly complete.

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

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

Schema description coverage is 100%, so parameters are well-documented in schema. Description does not add meaning beyond what schema already provides.

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

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

Description clearly states 'List recent phone calls from your Twilio account' with a specific verb and resource, and lists return fields (SID, status, duration, direction), distinguishing it from siblings like twilio_make_call and twilio_list_messages.

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?

Implied usage from title and description, but no explicit guidance on when to use this tool versus alternatives like twilio_list_messages or twilio_make_call. No when-not-to-use or exclusion criteria.

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, so the description doesn't need to emphasize safety. However, it adds no behavioral context beyond 'recent' (e.g., how recency is determined, pagination details, rate limits). It does not contradict annotations, but it also doesn't enrich the behavioral understanding.

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

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

Two concise sentences that are front-loaded with the core function. Every word is necessary and no extraneous information is present. The structure allows an agent to quickly understand the tool's 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?

For a simple list tool with comprehensive annotations and an output schema (as per context signals), the description is nearly complete. It covers the main purpose and filtering capabilities. However, it could mention default pagination limits (though present in schema) or error scenarios, but this is not critical given the tool's simplicity.

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 all parameters already described in the schema. The description mentions filtering and pagination, but this is a restatement of what the schema already provides. No additional semantic context is added, 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 the action (list), the resource (SMS/MMS messages from a Twilio account), and notes filtering and pagination. This distinguishes it from sibling tools like twilio_get_message (single message) and twilio_send_sms (send), providing a clear purpose.

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

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

The description implies usage for listing recent messages but does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or cases where it should not be used. The sibling names provide some contextual guidance, but explicit when-to-use and when-not-to-use are missing.

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 contradicts the annotations: readOnlyHint is true but making a call is a mutation, and idempotentHint is true but calls are not idempotent. The description does not clarify side effects like costs or call state changes.

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 brief (two sentences) and front-loaded with the action. It could be slightly more informative without losing conciseness, but it is not verbose.

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 (external API, cost implications, authentication required), the description omits crucial context such as the need for valid Twilio credentials, potential failure modes, and billing impact. The presence of an output schema reduces the need to explain return values, but the overall completeness is lacking.

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 baseline is 3. The description adds no new parameter meaning beyond the schema, only reiterating the TwiML URL requirement that is already in the schema.

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

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

The description clearly states it initiates a phone call via Twilio, which distinguishes it from sibling tools like twilio_send_sms or twilio_list_calls. However, it mentions requiring a TwiML URL or application SID, but the schema only includes a URL parameter, causing slight confusion.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not specify prerequisites, such as needing a valid Twilio account, or scenarios where another tool (e.g., twilio_send_sms) would be more appropriate.

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

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

The annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the return value (SID and status) but does not elaborate on potential non-idempotency (each request sends a new message), authentication requirements (though parameters include auth fields), or error conditions. The idempotentHint=true annotation may be misleading, but the description does not contradict it.

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

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

The description is a single sentence with no wasted words. It is front-loaded and efficiently conveys the core purpose and output.

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

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

Given the presence of an output schema (context says 'Has output schema: true'), the description need not explain return values. However, it lacks context about authentication, error handling, and prerequisites. It is adequate but not thorough for a tool with five required parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it only mentions the return values, not parameter details.

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 action ('Send an SMS message'), the service ('via Twilio'), and what it returns ('Returns the message SID and status'). It distinguishes itself from sibling tools such as twilio_make_call or twilio_list_messages.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or compare to other Twilio tools like twilio_get_message or twilio_make_call.

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

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

Annotations indicate non-destructive and idempotent. The description adds that it's a soft deactivation (not deletion) and enforces ownership, which is beyond what annotations provide. No contradiction.

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

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

The description is two sentences, front-loaded with the purpose, and every sentence adds important information. There is no redundancy or unnecessary 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?

Given the single required parameter and simple behavior, the description is complete. It covers what happens, ownership constraints, and impact on historical data, leaving no ambiguity for the agent.

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

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

Schema coverage is 100% and already describes the 'id' parameter. The description adds value by linking the id to the 'subscribe' tool and explaining ownership enforcement, enhancing understanding beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id' and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. It also explains the effect (deactivation, not deletion), making the purpose unambiguous.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions') and clarifies that the row is deactivated, not deleted, so historical events remain available. This provides clear when-to-use and implications.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which convey safety and idempotence. The description adds value by detailing the verdict types (confirmed, approximately_correct, etc.), source (SEC EDGAR + XBRL), and output format (structured form, actual value with citation, percent delta). No contradiction with annotations.

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

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

The description is concise (about 5 sentences) and front-loaded with user-facing phrases like 'Is it true that...'. Every sentence serves a purpose: defining use cases, specifying scope, describing output, and explaining efficiency benefits. 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 has only one required parameter and no output schema, the description sufficiently explains the input, output, use context, and source. It covers the return format, supported claim types, and why this tool is beneficial (replaces multiple calls). No gaps left for an agent to infer.

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

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

The single parameter 'claim' has 100% schema description coverage with examples. The tool description adds meaning by clarifying it accepts natural language claims, providing sample phrasing, and specifying the supported claim type (company-financial). This enhances the semantic understanding beyond the schema.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It distinguishes from sibling tools by highlighting it replaces 4-6 sequential calls, indicating a specialized function. The verb 'validate' and resource 'claim' are directly aligned.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies scope: 'v1 supports company-financial claims'. This provides clear when-to-use guidance, though it does not explicitly mention alternatives for non-financial claims. The statement about replacing 4-6 calls implicitly suggests it is the preferred option for these use cases.

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