Tavily

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

Annotations already provide safety (readOnly, idempotent, non-destructive). The description adds operational context: the default model (Workers AI Llama-3.3-70b, free) and BYO key requirement for Anthropic. It also mentions the output structure (per-model {score, confidence, signals, raw_response}) and combined view, which is useful 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 three sentences, front-loaded with the core purpose, and every sentence adds essential information. No fluff or redundancy. It efficiently covers what, how, and when.

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 parameters, no output schema), the description is fairly complete: it explains default model, optional parameters, output structure, and use cases. It could optionally mention rate limits or error handling, but the provided info is sufficient for an agent to invoke correctly.

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

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

Schema descriptions cover all 4 parameters (100% coverage). The description adds value by explaining the default model behavior ('Omit for just workers-ai'), the purpose of the _apiKey ('passed straight through to api.anthropic.com'), and the disambiguation role of context. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs for brand visibility and scoring it 0-100. It specifies the verb 'probe', the resource (LLMs), and outputs (score per model). It also distinguishes from siblings by mentioning default model and BYO key option, making it specific and not a tautology.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It provides context on when to use, though it does not explicitly state when not to use or name alternatives. Still, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating safe, read-only, and idempotent behavior. The description adds valuable context: that the tool routes questions to the right tool among 3,547, fills arguments, and returns structured answers with pipeworx:// citation URIs. This goes beyond annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the key message to prefer over web search. It lists domains, then usage guidance, then examples. It is somewhat long but every sentence adds value. Minor redundancy (e.g., listing 'current' twice) keeps it from a perfect 5.

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

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

Given the tool's complexity (routing to 3,547 tools), the description is very complete: it explains the core mechanism, when to use it, what output to expect (structured answer with citation URIs), and provides examples. There is no output schema, but the description sufficiently describes the return format.

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

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

Schema coverage is 100%, so the schema already documents all parameters (question and its aliases). The description adds meaning by explaining that the tool 'fills arguments' and routes the question, implying the parameter is natural language. The examples in the schema also help. Baseline is 3, but the description elevates clarity slightly.

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

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

The description starts with 'PREFER OVER WEB SEARCH' and lists many specific domains (SEC filings, FDA drug data, etc.). It clearly states the tool routes questions to one of 3,547 tools and returns structured answers with citations. The verb 'ask' and resource 'pipeworx' are well-defined, and it distinguishes itself from web search and sibling tools like search.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides explicit when-to-use guidance: for factual questions about real-world entities, events, or numbers. It gives examples of question triggers ('what is', 'look up', etc.) and specific use cases like 'current US unemployment rate'. It even states to use it even if web search could answer, making the guidance very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds details about extraction from tool results only, explicit refusal reasons, and extra LLM call. No contradiction.

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

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

The description is dense but each sentence adds value. It front-loads the main function. Could be slightly more concise but still efficient.

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

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

Given the tool's complexity, the description covers purpose, usage, return format (success and failure), tradeoffs, and cost. No output schema exists, so describing return values is appropriate and complete.

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

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

With 100% schema coverage, baseline is 3. The description does not add significant meaning beyond the schema for the parameter, only listing aliases which are already in the schema.

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

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

The description clearly states the tool provides hallucination-resistant answers by extracting from tool results, with explicit refusal patterns. It distinguishes from the sibling ask_pipeworx by noting the extra cost and grounded nature.

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

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

The description explicitly advises when to use ('when answer will be quoted, cited, or acted on') and when to prefer ask_pipeworx ('casual lookups'). It also mentions cost tradeoff.

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 fully discloses behavioral traits beyond annotations. It explains the resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback, safety mechanisms (low-confidence resolutions, closed markets), and response shapes. The annotations (readOnlyHint=true, idempotentHint=true) are consistent; no contradictions. The description adds rich context about what happens internally, which is crucial for AI agents.

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

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

The description is very long and dense, containing extensive details and examples. While well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), the length may hinder quick parsing by AI agents. Each sentence carries important information, but the description could be more concise. Score 3 reflects adequate structure but limited 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 (3 parameters, no output schema), the description is remarkably complete. It covers all aspects: input formats, classifier types, fan-out behavior per bet type, resolver contract, parent event extraction, news fallback with error handling, safety mechanisms, closed market handling, and illiquid spread warnings. This ensures the AI agent can understand and use the tool correctly in various scenarios.

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

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

Schema description coverage is 100% with all 3 parameters described. The description adds value beyond schema by providing examples of market input (slug, URL, question) and elaborating on depth and include_raw behaviors (e.g., 'quick = 2-3 evidence sources', 'include_raw keeps responses under ~20KB'). This additional context improves parameter understanding, though the schema already does a good job. Baseline 3, plus 1 for added context.

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 input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). The description also distinguishes the tool by detailing classifier types and fan-out examples, providing a clear, specific verb+resource definition.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed scenarios and classifier examples. However, it does not explicitly contrast with sibling tools or state when not to use it, though the extensive examples imply the scope. A 4 is appropriate for clear but not exhaustive usage guidance.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds significant behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/drug trials for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and inclusion of pipeworx:// citation URIs. This enriches understanding without contradiction.

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

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

The description is a single dense paragraph that is front-loaded with user-facing examples. Every sentence adds value, explaining supported queries, data types, source handling, and output. No extraneous information; it is maximally informative in a compact form.

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

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

Despite lacking an output schema, the description thoroughly covers return values (paired data, sorted by metric, citation URIs) and edge cases (off-calendar fiscal years). It provides enough detail for an AI agent to correctly invoke the tool and interpret results, making it fully complete for its complexity.

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

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

Schema coverage is 100% with descriptions, but the description adds crucial semantics: it specifies that 'company' uses tickers/CIKs and pulls financial data, while 'drug' uses names and pulls adverse events, approvals, and trials. It also clarifies array constraints (2–5 items) and the intended format, going well 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 performs side-by-side comparisons of 2–5 companies or drugs, with specific natural language examples ('Compare X and Y', 'which is bigger'). It explicitly contrasts with sequential lookups, making the purpose unambiguous and distinguishing it from siblings like 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 advises to 'ALWAYS PREFER over sequential single-pack lookups' and provides clear usage patterns. While there is no explicit when-not-to-use, the context strongly implies that this tool is for comparative queries, not single-entity lookups, which is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns 'names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed'. This goes beyond annotations, though lacks mention of pagination or result limits.

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

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

Two sentences with front-loaded purpose and usage. Every sentence adds value: first sentence states purpose and domains, second sentence explains output and when to call. No wasted words.

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

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

Given the tool's discovery function, the description covers what it does, when to use, what it returns (including schemas), and example queries. No output schema exists, but description compensates by describing the output structure. Complete for the tool's role.

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 mentions aliases for query ('task, q, description, search') which are already in the schema's description field. No additional semantic value is provided beyond what the input schema conveys.

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' with specific verb 'find/discover' and resource 'tools'. It lists example domains and distinguishes from siblings by noting it returns top-N relevant tools with schemas, making the purpose unambiguous.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use this tool versus other search or lookup tools, fulfilling the guideline criteria.

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

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

Annotations already indicate safe read operation (readOnlyHint, idempotentHint, not destructive). The description adds significant context: fans out across multiple sources, returns specific fields with URIs, notes USPTO API sunset soft-fail, and clarifies it's a single parallel call. 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 fairly long but front-loaded with usage examples and purpose. Every sentence adds value, though it could be slightly more concise. It is well-structured, starting with example queries then detailing fan-out and specifics.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description covers what is returned, limitations (no name support, USPTO sunset), and how to use. It misses potential details like pagination or limits, but is sufficiently complete for a profile tool.

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

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

Schema coverage is 100% and description adds crucial context beyond schema: explains format of 'value' (ticker or zero-padded CIK), notes that names are not supported and directs to 'resolve_entity', and clarifies 'type' enum only has 'company' currently. This adds meaningful guidance.

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 'full cross-source profile of a US public company in one parallel call'. It lists example queries and explicitly distinguishes from chaining single-pack lookups, making its purpose specific and differentiating it from siblings like 'resolve_entity' or 'search'.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view'. Also tells when not to use: 'names not supported (use resolve_entity first)'. Includes example inputs and what the tool returns, making usage very clear.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description adds that the tool strips boilerplate/navigation and returns readable raw content. This provides valuable behavioral insight without contradicting annotations.

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

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

Two sentences plus an example. No extraneous information. Every sentence is necessary and placed effectively, making it easy to parse quickly.

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 extraction tool with full schema coverage and no output schema, the description sufficiently covers functionality, input format, and intended use. It omits nothing critical for correct invocation.

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

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

Schema description coverage is 100%. The parameter descriptions in the schema already fully explain 'urls' and '_apiKey'. The description adds an example but does not significantly enhance meaning beyond what the schema provides, earning a baseline 3.

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

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

The description clearly states the tool extracts clean article text from URLs, stripping boilerplate/navigation. It distinguishes itself from sibling tools like search or validate_claim by focusing on content extraction from specific URLs.

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 a clear use case ('ideal for feeding source pages into an LLM') and includes an example. It does not explicitly state when not to use or mention alternatives, but the context is sufficient for an AI agent.

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

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

Annotations already indicate destructiveHint=true. Description consistently says 'delete' but provides no additional behavioral details beyond the annotation. It adds usage context, but not new behavioral traits beyond what 'delete' implies.

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

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

Two sentences, front-loaded, no filler. Every word earns its place.

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

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

For a simple tool with one parameter, annotations, and no output schema, the description is complete. It covers purpose, usage guidelines, and relationship to sibling tools.

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

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

Schema covers 100% of the single parameter with description 'Memory key to delete'. Description adds no extra 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 starts with 'Delete a previously stored memory by key', which is a specific verb and resource. It clearly distinguishes from siblings like 'remember' and 'recall', making the tool's purpose unambiguous.

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

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

Explicitly states three clear use cases: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, giving guidance on 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the specific steps (fetch, extract, emit) and output format, though it does not cover error handling or rate limits.

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

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

The description is concise with three well-structured sentences: purpose, process, and use cases. Every sentence earns its place, and the key information is 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?

For a simple tool with 2 parameters, no output schema, and rich annotations, the description covers purpose, process, output, and use cases. It is complete enough for an agent to understand what the tool does and when to use it.

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

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

Schema coverage is 100%, and the description adds little beyond the schema: url is described as 'Full URL' and max_links as 'Maximum number of link entries'. The description implies usage but doesn't provide new meaning, 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?

Description clearly states the tool generates an llms.txt file for AI crawlers, specifying the verb 'generate', the resource 'llms.txt for any URL', and the process of fetching and extracting. It distinguishes itself from sibling tools by focusing on llms.txt generation, which none of the siblings do.

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

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

The description explicitly lists three use cases (client indexing, personal project, competitor audit), providing clear context for when to use. However, it does not mention when not to use or compare directly to siblings like ai_visibility_check, so some guidance is missing.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and active/inactive behavior, but no extra behavioral traits beyond annotations.

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

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

Two concise sentences: purpose+returns, then usage. No redundancy, 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?

Low complexity (1 optional param, no output schema). Description adequately covers purpose, return, and usage. No major 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 description coverage is 100% with clear parameter meaning. Description adds no new param info 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 'List the caller's active subscriptions' – a specific verb and resource. Describes returned fields. Distinct from siblings like subscribe/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?

Explicit usage advice: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not provide when-not-to-use or alternatives, but context is clear.

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

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

Annotations are default (readOnlyHint=false) and description adds behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. No contradiction with annotations, and the description provides transparent usage constraints beyond the structured fields.

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

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

The description is a single paragraph that efficiently covers purpose, usage, and constraints. It is front-loaded with the main verb and resource. A bullet or shorter sentences would improve scannability, but it remains concise and informative.

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

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

Given the tool's simplicity, the description fully covers behavior (rate limits, cost, side effects) and usage context. Schema covers all parameters, and no output schema is needed. The description is complete for an AI agent to understand when and how to use the tool.

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

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

Schema coverage is 100% with each parameter documented. The description adds value by specifying how to formulate the message (specific, 1-2 sentences, avoid user prompt) and clarifies the enum options, which goes beyond the basic 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 is for giving feedback (bug, feature, data_gap, praise) to the Pipeworx team, distinguishing it from sibling tools like search or ask_pipeworx by explicitly focusing on reporting issues or suggestions about 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 describes when to use each feedback type (bug for wrong data, feature/data_gap for missing tools, praise) and what not to do (avoid pasting user prompts). Also mentions rate limits and that it's free without counting against quota, providing clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by explaining the data source ('derived from CF analytics-engine, no PII'), caching behavior ('Cached 5min-1h'), and output structure ('just (pack, tool, count)'). No contradictions.

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

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

The description is three sentences with excellent structure: first sentence defines output, second lists use cases, third explains data source and caching. No extraneous text, every sentence adds value.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description covers all necessary context: what it returns, use cases, data source, caching, and privacy (no PII). Fully adequate for an agent to select and invoke 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?

The single parameter 'window' has full schema coverage (100%) with enum values described. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' going beyond the schema's basic description.

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

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

The description clearly defines the tool's purpose: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume...' This distinguishes it from siblings like 'discover_tools' (listing tools) and 'ask_pipeworx' (queries), providing a specific, differentiated function.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). However, it lacks explicit when-not-to-use guidance or direct comparisons to alternatives, leaving some room for improvement.

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

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint true, confirming safe read operations. The description adds valuable behavioral details: semantic anchoring with Jaccard threshold (0.30), partition filter for placeholder slugs, and the partition_check logic. 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 dense and includes technical details (thresholds, filter logic, response structure) that could be better organized or shortened. The first sentence is strong, but overall the text is verbose and lacks clear sectioning.

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

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

Despite lacking an output schema, the description explains the response structure (opportunities array, partition_check object) and conditions for null results. It covers both modes comprehensively, though lacks note on rate limits or performance. Given the tool's complexity, this is fairly complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds recommended usage and examples, but these are supplementary rather than essential. The baseline of 3 is appropriate as the added value is marginal.

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 arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, differentiating it from siblings like polymarket_kalshi_spread which focuses on cross-platform 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 begins with a requirement for one of the two parameters and explains when to use event mode (specific market) vs topic mode (cross-event scanning). It notes that cross-event mode catches patterns missed by single-event mode, but does not explicitly mention when not to use this tool or suggest alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: caching at KV level for 1h, explanation of tradeable-edge knobs, warnings about Fed bets unreliability, and diagnostic structures. No contradictions with annotations.

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

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

The description is thorough but verbose. It front-loads the purpose well, but the detailed technical breakdown of segments and parameters makes it lengthy. While the density is justified by complexity, it could be more concise with better structure (e.g., bullet points).

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

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

Given the absence of an output schema, the description fully explains the output structure: by_segment with three segments, fed_candidates, and diagnostics. It covers all key fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning) and explains why segments might be empty (cache, gates, knobs). Comprehensive 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% with descriptions for all 9 parameters. The description adds significant value by explaining the semantics behind each parameter, such as the purpose of min_partition_leg_kelly (filtering thin partitions), and the tradeable-edge knobs (min_liquidity, max_spread_pp). It expands on how parameters interact with the edge calculation and Kelly sizing.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the three segments (model_driven, structural_arbitrage, concentrated_longshot) and the overall purpose of discovering betting opportunities, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly states the use case: 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides context on when to use the tool, but does not explicitly exclude alternatives or mention when not to use it. Sibling tools like polymarket_arbitrage exist, but no direct comparison is made.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral detail: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, skipped comparison counters. 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 dense but well-organized: purpose, modes, response, safety fields, counters. Every sentence adds value, though could be slightly tightened without losing clarity.

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

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

No output schema exists, so description carries full burden. It fully explains response fields, compatibility warnings, temporal alignment, and skipped comparison counters, making the tool's behavior completely clear.

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

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

Schema covers 100% of parameters with descriptions. Description repeats parameter info but adds contextual list of topic shortcuts and clarifies override behavior, providing marginal added 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?

Description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket for the same resolving question, using verbs like 'spread' and 'compute'. It distinguishes from siblings by focusing on two-venue comparison, unlike polymarket_arbitrage or polymarket_edges which are single-venue.

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

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

Explains two modes (topic shortcuts and explicit tickers) with examples, and warns that most pre-mapped topics are not tradeable. Lacks explicit 'when not to use' but provides sufficient context for appropriate usage.

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

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

Annotations provide readOnly, idempotent, non-destructive. Adds scope (identifier scoped) and behavior on omitting key. No contradictions.

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

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

Three focused sentences. First states core function, second provides user context, third adds scope. No redundant text.

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

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

Covers purpose, usage, scoping, and pairing. Adequate for a simple tool with one optional param and no output schema.

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

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

Schema describes parameter and its behavior. Tool description adds use case context but no deeper semantics beyond schema. Baseline 3 due to 100% schema coverage.

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

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

Clearly states it retrieves values saved via remember or lists all keys when omitted. Uses specific verbs and resource. Distinguishes 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?

Explicit use case: 'look up context... without re-deriving from scratch'. Implies pairing with remember/forget. No direct when-not-to but context 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 states that setting mark_read:true flags events as read, which modifies state, contradicting the readOnlyHint=true annotation. This is a serious inconsistency. The description also implies state change contradicting 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?

The description is a single paragraph that efficiently conveys key information. However, it includes a reference to an external URL which may be extraneous, slightly reducing 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?

The description covers what is returned, filtering, marking read, polling, and an alternative access method. Given no output schema and 5 optional parameters, this provides sufficient context for usage, despite the annotation contradiction.

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 meaning beyond the schema by providing examples (e.g., 'sec_8k'), explaining usage of parameters like mark_read, and noting that polling works fine. With 100% schema coverage, this extra context earns a score above baseline.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts with specific fields. It distinguishes from sibling tools like list_subscriptions or search by focusing on alerts, though it 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 provides guidance on when to use the tool: for polling, and mentions an alternative HTTP endpoint for scripts/dashboards. It does not explicitly state when not to use it, 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?

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds significant value: it explains the parallel fan-out to multiple external sources, fallback behavior (GDELT→GNews), USPTO soft-fail after May 2025, and return format. This goes well beyond what annotations convey.

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: starts with purpose, explains fan-out, details parameters, describes output, and gives alternative tool. No wasted sentences despite moderate length.

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

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

Given no output schema, the description thoroughly describes the return structure (grouped changes, total count, citation URIs), sources, fallback, and parameter formats. It is complete for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter semantics by providing examples for 'since' (ISO and relative formats) and 'value' (ticker or CIK), adding context that helps correct usage.

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 over a time window, aggregating multiple sources (SEC, GDELT, USPTO). It uses specific verbs like 'fans out' and distinguishes from sibling 'entity_profile' by contrasting dynamic vs static profiles.

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

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

The description gives explicit guidance: 'Use entity_profile instead when you want the static profile...'. It also provides example queries ('what happened to Z this week'). While it doesn't exhaustively list when not to use, it provides clear context for when to use this tool versus an alternative.

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?

Disclosures about scoping (by identifier), persistence (authenticated vs anonymous, 24-hour memory) add significant value beyond annotations, which already indicate idempotence and non-destructiveness.

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 with a front-loaded purpose statement and no fluff, 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?

Although no output schema exists, the description covers key aspects like scoping and persistence; however, it does not mention expected return values, leaving a minor gap for a storage 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 descriptive examples; the description largely echoes schema details without adding new meaning, 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 the tool saves data for reuse across conversations or sessions, using a key-value pair, and distinguishes itself from sibling tools like recall and forget.

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

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

Explicit guidance on when to use (discover something worth carrying forward) and how to use with siblings (pair with recall, forget), providing clear context for selection.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that each call cascades through multiple endpoints internally, details exact return fields (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug), and notes auto-disambiguation. No contradictions.

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

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

Well-structured with examples, purpose, usage guidance, and type breakdowns. Every sentence adds value, though the description is slightly longer than necessary. Could be tightened without losing clarity.

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

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

No output schema, but the description fully explains return values for each type, including citation URIs. Covers both types, internal cascading, and disambiguation. Complete for an identifier resolution tool.

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

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

Schema covers all parameters with clear descriptions. The description enhances by giving concrete input examples (AAPL, 0000320193, ozempic) and explaining what each type returns, which isn't in the schema.

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

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

Starts with concrete query examples, then states the core purpose: resolving a name to a canonical ID. Lists supported entity types and what each returns, making the tool's purpose crystal clear.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' Mentions that it replaces multiple manual lookups. Lacks explicit when-not-to-use or comparison to sibling tools like compare_entities or entity_profile, but still provides solid guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and nondestructive. Description adds valuable behavioral details: it probes each entity, ranks by score, returns score/confidence/signal density. 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?

Concise 4-sentence description that front-loads the purpose. Every sentence provides value: action, method, use case, and output. No repetition or fluff.

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

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

Despite no output schema, description completely explains the return format (ranked list with score, confidence, signal density). Tool usage is clear for its intended purpose. No missing information.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds extra semantics: mentions that first entity is treated as 'subject' for narrative, and that models parameter defaults to workers-ai. 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?

Clearly states the verb (compare, probes, ranks) and resource (AI visibility of multiple entities). Explicitly differentiates from sibling ai_visibility_check by noting it probes each entity with that tool and ranks results. Also mentions use case: competitive AI-marketing audits.

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

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

Provides clear context for when to use: competitive AI-marketing audits to compare brand recognition across competitors. Implicitly differentiates from single-entity check (ai_visibility_check) by describing multi-entity functionality. No explicit when-not-to-use or alternative tool names, but sufficient for typical usage.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description adds details: fans out to two services, returns summary block, partial failure graceful degradation, and bundlephobia first measurement delay.

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

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

The description is front-loaded with core purpose, uses efficient prose, and every sentence adds value without redundancy. Perfectly concise for the information conveyed.

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 provides sufficient detail on what is returned (summary block, per-advisory detail, links, alternative versions) and failure modes. Complete for its complexity.

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

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

Schema coverage is 100% with descriptions. The description adds context: scoped packages accepted for 'package', and defaults to latest version for 'version'. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for adding an npm package, fanning out to deps.dev and bundlephobia. It uses specific verbs and resources, and distinguishes from sibling tools like '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 explicitly states when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes limitations like NPM ecosystem only and partial failures.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details such as returning a synthesized answer plus 'title, url, content snippet, relevance score,' and being optimized for RAG, which goes beyond annotations.

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

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

The description is two sentences plus an example, each sentence earning its place. It front-loads the purpose and outcome, with no unnecessary words.

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

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

Given the absence of an output schema, the description adequately details the return format (synthesized answer and ranked results with specific fields). The 6 parameters are fully described in the schema, and the tool's purpose is clear.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema provides for each parameter; it only gives an example call.

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 it is an 'AI/LLM-optimized web search built for RAG' that returns a synthesized natural-language answer plus ranked results. This clearly distinguishes it from generic search or scraping tools, avoiding tautology.

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 advises to 'Prefer this over scraping a generic search engine when you need grounded, citable web context,' giving clear guidance on when to use. It does not explicitly mention when not to use it, but the context is sufficient.

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

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

Discloses embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation and flagging), and that passages include offsets for verification. This goes well beyond the annotations which already declare read-only and idempotent behavior.

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

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

The description is a single paragraph of 5 sentences, front-loading the primary purpose and then adding usage guidance and technical details. Every sentence is informative and necessary, with no redundancy.

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

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

Covers input limits, chunking behavior, and return format (passages with offsets and scores). Mentions pairing with another tool for grounding. Lacks explicit output schema but provides enough context for an agent to understand the output.

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

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

Schema coverage is 100%. The description adds value by providing examples for the query parameter and reiterating the character limit for the text parameter, but does not introduce major new information beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning top passages with offsets. It distinguishes itself from sibling tools by specifying it is for searching within already-fetched text and pairs with ask_pipeworx_grounded for grounding over passages.

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

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

Explicitly states when to use: when the record is too large for the prompt. Provides context on how it complements ask_pipeworx_grounded, giving clear guidance on tool selection.

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

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

Annotations indicate non-read-only, non-destructive, open-world, and idempotent. Description adds behavior: returns new ID, delivery constraints (SMS cap), and account requirement. No contradictions.

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

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

Concise yet comprehensive. Uses bullet-like structure for types and delivery. Every sentence adds value.

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

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

Given no output schema, description adequately explains return (subscription id), all parameters, delivery options, prerequisites, and constraints. Complete for this complexity level.

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

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

Schema has 100% coverage, but description adds significant value beyond schema: detailed examples for params, delivery constraints (phone verification, SMS cap), and type-specific parameter structures.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb, resource, and return value, distinguishing from siblings like list_subscriptions and unsubscribe.

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

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

Provides when to use: creating a subscription. Mentions prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' Does not explicitly exclude alternative tools but contextually clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description explains that the row is deactivated, not deleted, and historical events stay available via recent_alerts. This adds valuable 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 clear sentences. First sentence states action and ownership. Second sentence explains behavioral consequence. No wasted words.

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

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

For a simple mutation tool with one parameter and no output schema, the description covers ownership, effect on data, and links to recent_alerts. Complete for the 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?

Schema coverage is 100% and the description does not add meaning beyond the schema's 'Subscription id (uuid) returned by subscribe.' Baseline 3 is appropriate as the parameter is sufficiently documented.

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 action (Cancel a subscription) and resource (subscription by id). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying 'by id' and ownership enforcement.

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

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

Provides explicit condition: 'Ownership is enforced — you can only cancel your own subscriptions.' This guides when to use the tool. Could be enhanced by mentioning alternatives or when not to use, but the ownership constraint is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing the return values (verdict types, citation, percent delta) and explaining that it replaces 4-6 sequential calls. This provides useful behavioral context beyond the annotations.

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

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

The description is a single, well-organized paragraph. It front-loads the core purpose with trigger phrases, explains the use case, specifies supported claims, and lists return values. 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?

For a simple tool with one parameter and strong annotations, the description covers all essential aspects: when to use, what claims are supported, and what the response includes. It lacks an output schema but describes the output adequately. Some minor details like time constraints or limitations could be added, but it is sufficient for effective 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?

The input schema has 100% coverage for the single 'claim' parameter, describing it as a natural-language factual claim. The description adds no additional parameter-level details beyond the schema. However, it does clarify the domain of supported claims (company-financial) in the usage context, which is helpful but not strictly parameter semantics.

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 explains that the tool performs natural-language claim verification against authoritative sources, listing trigger phrases like 'fact check' or 'verify the claim'. It specifies the supported domain (company-financial claims for public US companies). This makes the tool's purpose unmistakable and distinct from any sibling tool.

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 whenever the agent needs to check whether something a user said is factually correct.' It also gives examples of claim types it supports. While it does not list when not to use it, the context is sufficiently clear, and no sibling tool duplicates this functionality.

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