Paypal

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

The description adds significant behavioral context beyond the annotations: it discloses that the default model is free, that anthropic probing requires a BYO key with direct billing, and that it returns per-model {score, confidence, signals, raw_response} plus a combined view. This complements the readOnlyHint and idempotentHint annotations perfectly.

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 of 5 sentences, front-loaded with the core purpose. Every sentence adds value: purpose, default model, API key rule, return format, and use cases. No redundant or vague wording is present.

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 4 parameters (1 required), no output schema, and moderate complexity, the description covers the key aspects: purpose, parameters, return format, and use cases. It could be enhanced by mentioning potential errors, rate limits, or response size, but the provided information is sufficient for effective tool selection.

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 100% description coverage for parameters. The description adds extra semantics: it specifies the default model by name (Workers AI Llama-3.3-70b), clarifies that _apiKey is only needed for anthropic and is passed directly to api.anthropic.com, and explains that context helps disambiguate common 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 the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe), resource (LLMs), and outcome (score). This distinct purpose differentiates it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the _apiKey parameter (to probe Anthropic) and notes the free default model. However, it does not mention when not to use this tool or present alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds value by explaining that the tool routes questions to the appropriate source among 4,819 tools and returns structured answers with citation URIs. No contradiction with annotations.

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

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

The description is relatively long but well-structured, front-loading the most important guidance ('PREFER OVER WEB SEARCH') and providing examples and alternatives. Every sentence contributes value, though slight trimming could improve conciseness.

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 (6 parameters, no output schema), the description is very complete: it clarifies the tool's purpose, usage boundaries, behavioral details, and provides numerous examples. Leaves no major gaps for an agent to interpret.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional parameter-level semantics beyond what the schema provides (all parameters are aliases for 'question'). The examples illustrate usage but don't deepen parameter understanding.

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

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

Description clearly states the tool is for asking questions about current or historical data from a wide range of authoritative sources, with examples. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance, including examples and when to step up to alternative tools. Effectively guides the agent on 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 convey readOnly, idempotent, non-destructive, and openWorld hints. The description adds valuable behavioral context: the extra LLM call, the refusal reasons enum, and the exact output shape. 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, highly informative but the second sentence is dense with multiple clauses. Could be slightly more structured (e.g., bullet points for refusal reasons), but overall efficient and front-loaded.

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

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

Given the tool's complexity (routing across thousands of tools, extracting constrained answers), the description covers all essential aspects: when to use, return format (including refusal reasons), cost tradeoff, and comparison to sibling. No output schema exists, but the description enumerates the return fields sufficiently.

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 description does not need to add much. It confirms the aliases for the 'question' parameter but adds no new semantic 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 clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb-resource pairing. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call cost and the exact use case of fact-sensitive 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims). Also advises preferring the parent tool for casual lookups, providing clear context versus alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations, including how the tool resolves markets, fans out to data packs, handles low-confidence matches, closed markets, wide spreads, and cancellation rules. It warns about inspecting market_match_confidence and provides details on news fallback mechanisms. No contradiction with annotations.

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

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

The description is quite long and detailed, which may be necessary for a complex tool. However, it could be more concise. The structure is logical, but the length detracts from quick scanning.

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

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

Given the complexity of the tool and the absence of an output schema, the description comprehensively covers market resolution, fan-out logic, response shapes, safety mechanisms, and edge cases. It provides enough detail for an agent to understand the tool's behavior and outputs.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by providing examples of market input, clarifying depth options (quick vs thorough), and explaining include_raw defaults. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research) and resource (Polymarket bet), and distinguishes from siblings by focusing on Polymarket-specific data and Pipeworx integration.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly contrast with sibling tools like deep_research or entity_profile, the context makes it clear when this tool is appropriate.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR, FAERS), sorting by primary metric, return of paired data and citation URIs, and handling of off-calendar fiscal years. 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 a single paragraph but well-structured: starts with query examples, then usage guidance, then per-type details, then output format. It is informative without being verbose, efficiently conveying all necessary 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 good annotations and comprehensive schema, the description fully covers purpose, usage, behavior, parameter semantics, and output format (paired data plus URIs). It leaves no major gaps for an AI agent to understand how to select and invoke this tool.

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

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

Schema coverage is 100% with both parameters described. The description adds meaningful examples (tickers/CIKs for company, names for drug) and clarifies the purpose of each type, which exceeds the schema's minimal 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 compares 2–5 companies or drugs side-by-side in one parallel call, with specific query examples like 'Compare X and Y' or 'X vs Y'. It distinguishes from sibling tools by explicitly preferring over sequential single-pack lookups.

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

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

The description explicitly states when to use this tool (comparing entities, head-to-head) and to always prefer it over sequential lookups. It provides detailed context on what data is pulled for each type (financials from EDGAR for companies, adverse events for drugs) and constraints (2–5 items).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond these: account requirement, free vs paid plan limitation, expected response time (15-60s), output format (findings packet with gaps), and the fact that it returns empty gaps for topics not in the structured catalog. 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 relatively long but structurally sound: it front-loads the critical account requirement and alternative, then explains functionality, output, and limitations. Every sentence adds value, though some could be tightened. Still, it avoids wordiness.

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, lack of output schema, and many siblings, the description is remarkably complete. It covers output format (verbatim evidence, confidence, source, fetched_at, citations, gaps), expected timing, and when results may be empty. No significant gaps remain.

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

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

Schema coverage is 100% (both parameters described). Description adds meaning by explaining the depth enum values (quick=3, standard=5, thorough=8 facets) and clarifying that the question field accepts broad/multi-part questions. This exceeds the baseline of 3.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources. It specifies the verb 'research' and resource 'structured data sources', and distinguishes from sibling tools like ask_pipeworx by noting deep_research decomposes questions into facets and uses parallel tool execution.

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

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

Explicit guidance on when to use (broad/multi-part questions over structured data) and when not to use (breaking news or current events). It also names the alternative ask_pipeworx for single lookups and live news, ensuring agents can choose 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?

Annotations indicate read-only, idempotent, non-destructive. The description adds that it returns top-N tools with full schemas and examples, 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?

The description is informative but somewhat lengthy due to the domain list. However, every sentence adds value and it is front-loaded with the core 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?

Despite no output schema, the description clearly explains what is returned (tools with names, descriptions, schemas, examples). It covers all essential context for using this discovery tool.

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

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

Schema coverage is 100% with all parameters described. The description explains aliases (task, q, description, search) and provides examples, adding value beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task.' and provides an extensive list of domains and use cases. It distinguishes itself from sibling tools which are specific data retrieval tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use this tool versus alternative specific tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), the USPTO sunset and soft-fail behavior, and output structure. No contradictions.

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

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

The description is dense but essential: it includes example queries, purpose statement, usage guidance, data source details, and output fields. It front-loads key information. Slightly long 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?

With no output schema, the description must detail return values, which it does comprehensively: CIK, company name, filings with URIs, fundamentals, patents, news, LEI. It also covers failure modes (patent API sunset). All essential context is present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples ('AAPL', '0000320193') and clarifies that names are not supported, which is not fully captured in the schema. This pushes the score to 4.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs ('get profile', 'research', 'brief me') and distinguishes from siblings like 'resolve_entity' by noting name resolution is needed first.

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 provides negative guidance: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description reinforces the destructive nature ('delete') and adds behavioral context about clearing sensitive data. No contradiction, but the description adds only moderate extra behavioral insight beyond annotations.

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

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

Two sentences: first states core purpose, second provides usage guidance. Every sentence adds value; no wasted words. Front-loaded with the action verb.

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

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

For a simple single-parameter tool with no output schema, the description covers what the tool does, when to use it, and related tools. No gaps remain given the tool's complexity.

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

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

Schema coverage is 100% for the single 'key' parameter, with a clear description. The description adds 'by key' but no further semantic detail (e.g., allowed characters, length, case sensitivity). Baseline 3 is appropriate as the schema already documents the parameter adequately.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools by mentioning 'remember' and 'recall' for pairing, making the purpose unmistakable.

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

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

The description explicitly provides when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also points to alternatives ('Pair with remember and recall'), giving clear guidance on context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's confirmation of fetching and non-modification adds limited value beyond restating the profile. No additional behavioral traits disclosed.

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

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

Two concise paragraphs: first explains functionality, second lists use cases. All sentences are purposeful and front-loaded with key information.

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

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

Despite no output schema, description fully explains output format and use cases. Covers inputs, behavior, and practical applications, making it complete for a simple tool.

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

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

Schema covers both parameters fully. Description provides a URL format example and default/max for max_links, adding minimal extra value. Baseline 3 is appropriate.

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

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

Explicitly states it generates a production-ready llms.txt file for any URL, detailing the extraction and output format. Clearly distinguishes from sibling tools which focus on other tasks like visibility checks, disputes, or entity profiles.

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

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

Lists specific use cases: indexing a client's site, drafting llms.txt for own project, auditing competitor visibility. No explicit when-not-to-use or alternatives, but context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral details: it returns the caller's subscriptions, optionally including inactive ones, and lists the return fields. This adds value beyond annotations.

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

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

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

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

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

For a simple read-only list tool with full annotation coverage and explicit return fields, the description is complete and provides all necessary context for an AI agent.

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

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

Schema coverage is 100% with one parameter fully described. The description does not add additional meaning to the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions', using a specific verb and resource, and implies distinction from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit when-not-to-use but is sufficient for the task.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns line items, amounts, due dates, and payment status, which aligns with annotations and provides useful behavioral context.

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

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

Two sentences, no superfluous words. Front-loaded with the action and purpose. 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 an output schema exists, the description does not need to expand on return values. It covers the core functionality adequately, though it omits mention of authentication requirements (handled by schema). Adequate for a simple read tool.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The tool description does not add any additional meaning to the parameters 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?

Description clearly states the tool retrieves full details of a PayPal invoice by ID, listing specific fields. It distinguishes from sibling tools like paypal_list_invoices by focusing on a single invoice retrieval, though not explicitly contrasting with them.

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

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

No guidance on when to use this tool versus alternatives such as paypal_list_invoices or paypal_get_order. A brief note about use cases or constraints would significantly improve clarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the return content (buyer info, items, amounts, fulfillment status). However, it omits authentication requirements beyond schema, though parameters are clear.

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: the first states the purpose with an example, the second lists return fields. Every sentence is informative and front-loaded.

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

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

The description covers what the tool does and what it returns. With an output schema present, return values are fully documented. However, it does not mention error handling or authentication steps, though the required parameters imply setup.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any parameter-level meaning beyond what the schema already provides. The example order ID is also in the schema examples.

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

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

The description uses specific verb 'Get' and resource 'full details of a PayPal order by ID', clearly distinguishing from sibling tools like paypal_get_invoice or paypal_list_transactions. It also lists the types of details returned (buyer info, items, amounts, fulfillment status), making the purpose precise.

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

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

The description implies usage when order details are needed but does not explicitly state when to use this tool versus alternatives like paypal_get_invoice or paypal_list_transactions. No when-not-to-use or alternative guidance is provided.

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

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

Annotations declare readOnlyHint=true, which aligns with the description's listing action. However, the description does not disclose behaviors like pagination, result ordering, or authentication requirements beyond what the schema provides. It is adequate but not enhanced beyond annotations.

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

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

The description is a single compact sentence that conveys the main purpose and return fields without extraneous information. It is well front-loaded 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 presence of an output schema (context signal), the description does not need to detail return values. It lists key fields. However, it lacks guidance on usage context, pagination, or error handling, which would enhance completeness. Overall adequate for a simple list 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 schema fully documents parameters. The description adds no additional meaning about parameters (e.g., authentication usage, sandbox behavior). Baseline score of 3 applies as the description does not extend beyond schema.

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

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

The description clearly states the tool lists chargebacks and claims (disputes) against the account, specifies returned fields (IDs, amounts, statuses, reasons), and distinguishes it from sibling tools like paypal_list_invoices and paypal_list_transactions.

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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention filtering or prerequisites. The purpose is clear enough to imply usage, but lacks explicit recommendations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns 'invoice numbers, amounts, statuses, and dates,' which is useful but not deep behavioral detail. No mention of rate limits or auth beyond credentials.

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

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

Two sentences, no wasted words. The key action and purpose are front-loaded.

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

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

With an output schema present, the description need not detail return structure. It covers purpose, return fields, and usage context sufficiently for a filtered list tool with strong annotations.

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

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

Input schema has 100% description coverage for all 5 parameters, so the schema already documents parameter meaning. The description does not add additional parameter context beyond confirming it returns listed fields.

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 'List your PayPal invoices' – a specific verb and resource. Differentiates from siblings like paypal_get_invoice (single invoice) and paypal_list_transactions.

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 usage context: 'Use to track billing and outstanding payments.' While not explicitly excluding alternatives, it gives a clear scenario for when this tool should be used.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that the tool returns specific fields but does not disclose other behaviors like authentication, rate limits, or pagination, which are already partially covered by schema.

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, front-loaded with the core purpose, and every sentence adds value without redundancy.

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

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

Given the simple nature of a list tool with rich annotations and full schema coverage, the description is complete. It covers purpose, return fields, and usage context, and an output schema exists to define return structure.

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

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

Schema coverage is 100%, with each parameter having a description. The tool description does not add additional semantic meaning beyond what is already provided in the input schema, so the baseline score of 3 applies.

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 finds PayPal transactions within a date range and lists returned fields (amount, status, payer info, IDs). It distinguishes from siblings like paypal_list_disputes and paypal_list_invoices through the return fields, but does not explicitly differentiate.

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 suggests using the tool to audit payments or track cash flow, providing clear usage context. However, it does not specify when not to use it or mention alternatives among sibling tools.

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

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

Beyond annotations, the description adds critical behavioral info: rate limiting (5/day), free usage, no impact on quota, and that feedback affects roadmap. No contradiction with annotations (readOnlyHint=false, etc.).

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

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

The description is a single, well-structured paragraph that front-loads purpose, then usage, then constraints. Every sentence adds value with no superfluous content.

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

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

Given the tool's complexity (3 params, 2 required, nested object, no output schema), the description fully covers input expectations, rate limits, and outcome (digests). Complete and sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining enum meanings, message length limits, and context usage beyond the schema. Slight over-delivery justifies 4.

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

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

The description explicitly states the purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature, data_gap, praise) and distinguishes the tool from all siblings, none of which are feedback-related.

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 detailed guidance on when to use (each feedback type), what to include (tool/pack context, not end-user prompt), and constraints (rate-limited to 5 per day, free). This is comprehensive and clearly differentiates from alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds value by disclosing the data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 4 sentences, well-structured with bullet points for use cases. Every sentence adds value without redundancy.

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

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

Given no output schema, the description briefly mentions return components (tools, packs, count), which is sufficient for this simple trend tool. Annotations cover safety. Could include more detail on response structure but not critical.

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

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

Schema coverage is 100% with a description for the only parameter. The description enhances it by explaining the semantics of different window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description uses specific verbs ('Returns') and clearly defines the resource (top tools, top packs, total call volume over a recent window). It distinguishes from siblings like discover_tools by focusing on trending 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?

Three explicit use cases are listed, covering discovery, confirmation, and alignment. While it doesn't provide negative guidance (when not to use), the context signals and sibling list offer implicit alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral details: trending scan scope (top 200 markets), fill check logic with realizable edge, semantic anchor (Jaccard similarity ≥0.30), placeholder filtering, and response structure for both modes. 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 well-structured with clear sections (purpose, mode selection, semantic anchor, partition filter, fill check) and front-loaded with key information. While slightly long, every sentence contributes to understanding the complex tool, so it earns its place.

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

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

Despite no output schema, the description thoroughly explains the response structure for both modes, including fields like `gap_pp`, `suggested_trade`, `reasoning`, and `placeholders_filtered`. It covers edge cases like low similarity skipping and placeholder filtering. The fill check section ensures agents know when not to trade.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds significant context: for `event` it explains slug format and that it walks child markets; for `topic` it explains cross-event scanning and similarity threshold. The description greatly enhances understanding beyond the schema.

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

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

The description states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two specific modes (`event` and `topic`). It clearly distinguishes from sibling tools by explaining its unique role in Polymarket arbitrage detection.

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

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

The description provides explicit guidance: no args for trending scan, `event` for per-event checks, `topic` for cross-event scans. It recommends `event` for specific markets and explains when cross-event mode is better, but does not directly compare to sibling tools like `polymarket_edges`.

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, so agent knows it's a safe read operation. Description adds rich behavioral context: caching (1h KV), diagnostic fields, filter behavior (placeholder-slug filters, partition fraction skips), and market movement warnings. No contradictions with annotations.

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

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

Description is lengthy but necessary given tool complexity. Front-loaded with purpose and model families. Could be trimmed slightly (e.g., detailed GDELT period and alpha values), but overall structured well with segments and clear explanations.

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 thoroughly details response structure: by_segment, fed_candidates, diagnostics with funnel counters. Explains all returned fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning). Covers knobs and their effects comprehensively.

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

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

Schema coverage is 100%, but description adds significant value beyond schema. For example, min_kelly explains 'Skips opportunities that are too small to bet sensibly even if the edge is large.' Slippage_pp explains zero trading fees but typical bid/ask costs. Each parameter gets practical usage guidance and defaults.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Specific verb+resource+scope. Distinct from siblings like 'polymarket_arbitrage' which focuses on different cross-market opportunities.

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?

Framed around 'what should I bet on today' and describes use cases for each model family. However, does not explicitly contrast with sibling tools like 'polymarket_arbitrage', leaving the agent to infer when to use which. Guidance is implied but not explicit about alternatives or exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: 'LIMITS: history depth is bounded by the 60-day snapshot TTL and starts from when snapshotting was enabled; decay numbers come from daily closes of edge_pp_net (net of default slippage), not intraday.' It also describes the response fields in detail.

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

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

The description is moderately sized and well-structured: it starts with the core purpose, then explains the response fields (tracked, expired, snapshot_dates), and ends with limitations. Every sentence adds value, though some could be condensed. It is front-loaded with the key question the tool answers.

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

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

Given the complexity of the tool and no output schema, the description is very complete. It explains all parts of the response (tracked, expired, snapshot_dates) with detailed sub-fields (first_seen, trend, decay_pp_per_day, lifespan_days). It also covers limitations (60-day TTL, snapshot enablement, daily closes). No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'Args: days (lookback, default 14, max 30), window (snapshot family, default “1wk”).' This adds minimal meaning beyond the schema, which already provides defaults and clamp ranges. The concept of 'snapshot family' is introduced but not elaborated.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers “how long has this edge existed and is it shrinking?”' It uses specific verbs and resources, and the context distinguishes it from sibling tools like polymarket_edges (raw edges) and polymarket_arbitrage (arbitrage).

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

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

The description provides clear context for use: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies when to use this tool to assess edge longevity, but does not explicitly state when not to use it or name alternatives. However, the sibling list includes polymarket_edges as an alternative for raw edge data.

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

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

Description adds context beyond annotations (readOnlyHint, idempotentHint, etc.): it checks live order book, walks the ladder, returns verdict, and explains required parameters. Warns about risks (thin books, partial fills) and clarifies behavior constraints like no user/workspace filtering.

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 relatively long but well-structured: starts with a concise one-line summary, then uses bullet-like sections for modes, and concludes with explicit usage guidance. Every sentence serves a purpose, though could be slightly more terse.

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

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

Despite no output schema, description lists all return fields (top_of_book, vwap_fill_price, etc.) and basket-specific fields (theoretical_sum, realizable_sum, thin_legs, forced_directional_risk). It fully explains two modes, parameter defaults, and provides critical usage context 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 coverage is 100% but description enriches: e.g., for size_usd explains 'max spend on buys, target proceeds on sells' (single-market) and 'settlement notional — shares per leg' (basket). Side parameter default behavior clarified. Adds value beyond schema.

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

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

Description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It lists specific outputs like top_of_book, vwap_fill_price, slippage_pp, and verdict, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why theoretical overround on thin books is not capturable and warns about partial fills converting arb into unhedged directional position.

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 goes far beyond annotations, detailing safety fields (compatibility_warning with two cases, temporal_alignment, skipped_cross counters) and response structure. It also explains limitations like non-equivalent bet shapes, making the tool's 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 relatively long but well-organized with sections for modes, response, and safety fields. Key information is front-loaded. Every sentence adds value given the tool's complexity.

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

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

Without an output schema, the description explains the main response elements (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment). It covers both input modes and edge cases. A sample output would make it more complete, but it is already sufficient for agent 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?

All three parameters are described in the schema (100% coverage). The description adds extra context: the list of macro shortcut values, the effect of overriding with explicit params, and that most topics trigger warnings. This adds meaningful semantics beyond the schema alone.

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

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

The description clearly states the tool computes cross-venue spreads between Polymarket and Kalshi for the same question. It defines two modes (topic and explicit) and distinguishes from siblings like polymarket_arbitrage by focusing on spread across venues.

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 (for cross-venue spreads), provides guidance on the two modes, and cautions that most pre-mapped topics currently return a compatibility_warning. However, it does not explicitly compare with sibling tools like polymarket_arbitrage.

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

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

Adds scoping detail (identifier-based) beyond annotations (readOnlyHint, idempotentHint, destructiveHint). 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 with zero wasted words, front-loaded with action and purpose.

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

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

Fully explains retrieval, listing, scoping, and pairing with remember/forget. No missing information 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 covers the key parameter fully; description adds the behavior of omitting key to list all keys, which is not in 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 verb ('Retrieve' or 'list') and resource ('value saved via remember' or 'saved keys'), distinguishing from siblings like remember and forget.

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

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

Explicitly states when to use (look up stored context) and provides examples (ticker, address, notes). Lacks explicit when-not-to-use but the context is clear.

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

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

The description adds behavioral context beyond annotations: it explains that setting mark_read:true flags events as read to affect subsequent calls, and that polling is suitable. No contradiction with annotations (readOnlyHint, idempotentHint).

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 no wasted words. It front-loads the main purpose ('Pull fired events'), then efficiently covers return details, filtering, side effects, and alternative access. Every sentence contributes 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 and five optional parameters, the description adequately covers core functionality, return format, filtering, and usage context. It does not explicitly mention 'limit' or 'unread_only', but the schema covers these. The alternative endpoint mention adds extra value.

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 description adds minor value over the input schema (e.g., example filter 'sec_8k'), but schema coverage is 100% and each parameter already has clear schema descriptions. The description largely reinforces existing 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 the tool pulls the most recent alerts from the user's subscription feed, specifying the return fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like 'recent_changes' by focusing on subscription feed alerts.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint, but it does not explicitly guide when to use this tool versus sibling tools like 'recent_changes' or 'list_subscriptions'. It lacks explicit when-to-use and when-not-to-use advice.

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 fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, and soft-fail for PatentsView API. These details add value beyond the annotations (readOnlyHint, idempotentHint) which already indicate safety.

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

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

The description is relatively long but well-structured with examples and clear distinctions. It is front-loaded with usage examples. While every sentence is necessary for a complex tool, it could be slightly more concise.

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

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

Given the tool's complexity (multiple sources, fallback, various input formats) and absence of an output schema, the description is remarkably complete. It explains return structure (changes[], total_changes, citation URIs) and provides guidance on relative time formats.

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 each parameter described. The description adds significant context: 'since' accepts ISO dates or relative shorthand like '7d', '30d', '1y'; 'value' accepts ticker or CIK. This enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company, listing specific use cases like 'What's new with X' and 'updates on Acme'. It distinguishes from the sibling tool 'entity_profile' by contrasting 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?

The description explicitly provides when to use this tool (e.g., 'What's new with X', 'latest on Y') and when to use an alternative ('Use entity_profile instead when you want the static profile'). It also mentions fallback behavior between GDELT and GNews.

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 scoping by identifier, persistence duration (24h for anonymous), and pairing behavior. Annotations already provide idempotentHint=true and destructiveHint=false; description adds valuable 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?

Three concise sentences with front-loaded purpose, followed by usage guidance and behavioral details. Every sentence adds value.

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

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

Covers purpose, usage, behavior (scoping, persistence), and pairing. No output schema exists, so return values are not needed. Complete for a key-value store tool.

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

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

Schema coverage is 100% with clear descriptions (e.g., examples for key and value). The description adds usage context but does not significantly extend parameter semantics beyond schema. Baseline 3, raised to 4 for the contextual examples.

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 the tool saves data for later reuse, with specific examples (resolved ticker, target address, user preference). Distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on persistence (authenticated vs anonymous) and pairs with recall/forget.

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 the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This informs the agent about internal complexity and efficiency.

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

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

The description is somewhat lengthy but well-structured. It opens with example queries, then gives a usage guideline, followed by detailed type explanations. Every sentence adds value, though it could be slightly more concise 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 there is no output schema, the description fully specifies the return values for each type, including URIs. It also explains how the tool replaces multiple manual lookups. For a tool with only two parameters and low complexity, this is complete and informative.

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

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

Schema coverage is 100%, but the description enriches parameter understanding beyond the schema. For 'type', it lists the enum values and describes the return format for each. For 'value', it provides concrete examples ('AAPL', '0000320193', 'ozempic'). This helps the agent construct valid inputs.

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

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

The description clearly identifies the tool's purpose: resolving a user-spoken name to a canonical/official identifier. It provides specific examples for each supported type ('company' and 'drug'), distinguishing it from sibling tools like 'compare_entities' or 'entity_profile'.

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

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

The description explicitly states when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It does not explicitly state when not to use it, but the context of sibling tools provides implicit alternatives. A slight improvement would be to mention when to prefer other tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides process details beyond annotations. No contradiction. Could mention potential external API dependencies (e.g., Anthropic key) but omitted.

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 3-4 well-crafted sentences without filler. Front-loaded with the core action, then explains process, then provides a use case. 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 tool's complexity (4 params, no output schema), the description adequately explains the output (ranked list with score, confidence, signal density) and references the probing mechanism. It could be more specific about interpreting scores or confidence, but overall it provides enough context for an agent to understand what to expect.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds valuable context: the first entity is treated as 'subject' for narrative, others as competitors; the 'context' param disambiguates common names; and it links to the sibling tool ai_visibility_check. This enriches the 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and provides ranking. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic). The verb 'compare' and specific resource 'AI visibility across entities' make the purpose unmistakable.

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

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

Description explicitly notes it's useful for competitive AI-marketing audits and gives an example use case. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or fully list alternatives. However, the context is clear enough for an agent to differentiate from single-entity probes.

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

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

Annotations provide readOnlyHint=true, destructiveHint=false. Description adds significant behavioral context: fans out across two external services, bundlephobia's first measurement may take 5-30s, partial failures degrade gracefully with sources_failed list, and return structure details. No contradiction with annotations.

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

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

Description is a single paragraph but efficiently packs key information: composite behavior, use case, ecosystem constraints, failure handling, and return fields. Each sentence adds value, but it could be more structured (e.g., bullet points) for easier parsing. Still, it is concise and front-loaded.

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

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

Given the tool's complexity (composite service, partial failures, no output schema), the description fully covers all necessary aspects: it lists the return summary fields (is_latest, license, etc.), explains failure modes, timeout behavior, and alternative version list. The agent can use this tool correctly without ambiguity.

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

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

Input schema has 100% coverage for its two parameters (package and version) with clear descriptions. The tool description does not add further semantic details about parameters beyond what the schema already provides. Per guidelines, baseline is 3.

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

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

Description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project' across deps.dev and bundlephobia. It specifies the resource (npm package) and the action (one call check), distinguishing it from unrelated sibling tools like validate_claim or discover_tools.

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

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

Description explicitly says when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also defines scope: NPM only in v1, with fallback guidance for other ecosystems. Additionally, it mentions partial failures and graceful degradation, clarifying behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: BGE-base-en embeddings, 500-char windows, 200K char cap with truncation flag, and offset-for-verification feature, going beyond what annotations provide.

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

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

The description is a single dense paragraph with no wasted words, but it could be more scannable with bullet points. 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?

Despite lacking an output schema, description details return values (passages with offsets and similarity scores). It also explains pairing with sibling tools and provides implementation context (model, window size, cap). Fully complete for this tool.

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

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

Schema coverage is 100%. Description adds meaning by clarifying the 'text' parameter (fetched record), 'query' parameter (natural-language), and 'limit' parameter (max passages, default 5). It also explains the 200K cap and truncation flag, enriching 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 uses a specific verb ('Semantic search INSIDE') and clearly identifies the resource (a fetched record). It distinguishes from siblings like ask_pipeworx_grounded by explaining the use case and 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 states when to use ('Use when the record is too big to cram into the prompt') and names an alternative (ask_pipeworx_grounded), providing clear context for 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds critical behavioral details: authentication requirements, delivery channel behaviors (always-on feed, optional email/SMS/webhook), SMS daily cap, webhook HMAC verification, and auto-disable after 10 consecutive failures. 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 well-structured with the main purpose first, followed by prerequisites, type examples, and delivery details. It is dense but not overly verbose; every sentence adds value. Minor room for tightening, but overall efficient for the complexity.

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

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

Given three parameters (one nested) and no output schema, the description covers all necessary aspects: input types with examples, return value (subscription ID), delivery channels, authentication, constraints, and failure handling. It is fully complete for an agent to understand 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?

Although the input schema already has 100% description coverage, the description significantly enriches parameter meaning with concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topics, fred_series series_id) and detailed delivery constraints (verified phone, email validation, webhook signing). This adds substantial value beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Specific examples of supported types (sec_8k, polymarket_edge, etc.) further clarify 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 explicitly states the prerequisite of a Pipeworx OAuth account and notes that anonymous/BYO accounts cannot persist subscriptions. It also outlines delivery channels and constraints (phone verification, daily cap). However, it doesn't explicitly contrast with alternatives like recent_alerts for 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: it returns example questions drawn from live catalog, with options for full spread or topic focus. 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?

Starts with user intent phrasings, then explains purpose, return shape, and usage. Efficient but slightly long; 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?

Despite no output schema, description fully explains what is returned (category-bucketed examples with tool calls) and covers purpose, usage, parameter, and behavior. 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 coverage is 100% with a single optional parameter. Description adds meaning by listing valid topic values (finance, pharma, etc.) and explaining the effect of omitting vs providing topic.

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

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

Description clearly states it returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and advises how to call meta-tools. Does not explicitly exclude alternatives like discover_tools, but context is clear.

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

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

Description adds non-destructive behavior ('deactivated not deleted') and historical availability via recent_alerts, complementing annotations (destructiveHint=false, idempotentHint=true).

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

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

Two sentences, no waste. Front-loaded with verb and object, then adds constraints and effects.

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 simple signature (single param, no output schema), description covers behavior, constraints, and side effects fully.

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

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

Input schema already fully describes the id parameter (100% coverage). Description repeats 'by id' without added value beyond schema.

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

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

Clearly states 'Cancel a subscription by id', specifying the action and resource. Distinguishes from sibling tools like subscribe (create) and list_subscriptions (list).

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?

Includes ownership enforcement ('you can only cancel your own subscriptions') as a usage constraint. Lacks explicit alternatives or when-not-to-use guidance, but context is clear.

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

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

The description discloses the data sources (SEC EDGAR + XBRL), the return format (verdicts, structured form, actual value, citation), and that it replaces multiple sequential calls. Annotations already provide readOnlyHint, openWorldHint, etc., and the description adds significant context beyond that.

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 dense paragraph, but it is front-loaded with the core purpose and examples. It is efficient but could benefit from slightly more structure, like separating the return 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 description fully covers the tool's purpose, domain, usage, return values (verdict types, structured form, citation), and integration context. With only one parameter and no output schema, the description provides all necessary context.

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

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

The input schema has 100% description coverage for the single 'claim' parameter. The description adds value by providing examples of valid claims and clarifying the expected natural-language format, going beyond just 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 claims against authoritative sources, specifically for company-financial claims. It provides examples of natural language prompts and distinguishes itself as a specialized verification tool, with clear verb and resource.

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 to use it whenever the agent needs to fact-check a user's statement. It provides context on domain (company-financial claims) but does not mention when not to use it or suggest alternative tools for non-financial claims.

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