Seo Backlinks

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

The annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: default model is free, '_apiKey' for Anthropic requires the user's own key with direct payment, and it returns per-model data. No contradiction with annotations.

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

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

The description is very concise with just three sentences, front-loading the core purpose. Every sentence adds essential information: what it does, default model/key handling, and use cases. 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 tool with 4 parameters and no nested objects, the description fully explains the output format (per-model score, confidence, signals, raw_response + combined view) and when to use it. It provides enough information for an agent to understand the tool's behavior and output, even without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds extra meaning: explains the default model, that '_apiKey' is passed through to Anthropic, and that 'context' helps disambiguate. 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 it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probing, differentiating it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' which serve different purposes.

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

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

The description explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it doesn't state when not to use it or list alternatives, the context is clear and sufficient for an agent to decide 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 (readOnly, idempotent, etc.) already indicate safe read behavior. Description adds context: routes to 4,774 tools, returns structured answers with stable citation URIs, and is a single fast call. No contradictions, but could mention handling of unsupported queries.

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?

While lengthy, the description is well-structured with a strong front-load ('PREFER OVER WEB SEARCH') and covers all key aspects. Every sentence adds value, but 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?

For a complex tool with many aliases and no output schema, the description fully explains the return format (structured answer with citations) and covers usage scenarios. It addresses the tool's role among siblings and provides ample examples.

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 aliases described. Description only adds 'natural language' hint to the question parameter. Baseline 3 is appropriate as schema already does the heavy lifting.

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 handles factual questions about current/historical data from authoritative sources, with a extensive list of domains. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by being the default entry point.

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 recommends over web search and provides when-to-use ('what is', 'look up', etc.) and when-to-step-up (ask_pipeworx_grounded for high-confidence single answer, deep_research for broad multi-part). Also states 'START HERE' as default entry point.

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 confirm read-only, idempotent, non-destructive behavior. The description adds crucial behavioral details: it uses only tool result content for extraction, provides explicit refusals with specific reasons, and mentions the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense yet clear, with every sentence adding value. It is front-loaded with the core value proposition and structured logically: behavior, output, usage guidance. No wasted words.

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

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

Given the tool's complexity (multiple parameter aliases, comparison to sibling, no output schema), the description fully covers the required context: output format, failure modes, cost trade-off, and usage scenarios. Sibling list and annotations complement well.

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 (question and aliases). The description does not add new parameter semantics beyond the schema, but the schema already documents them. Baseline 3 is appropriate as no extra parameter info is needed.

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 for high-stakes reads. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded extraction and explicit refusal mechanisms. The return structure is specified, leaving no ambiguity about what the tool does.

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

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

The description explicitly instructs to use when answers will be quoted or acted upon, and to prefer 'ask_pipeworx' for casual lookups due to an extra LLM call cost. This provides clear when-to-use and when-not-to-use guidance, including specific domains like financial, legal, medical.

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 covers behaviors beyond annotations: low-confidence resolution handling, closed market status, illiquid wide-spread markets, resolution-rule risk parsing, and news fallback logic. This adds significant value for safe and correct agent invocation.

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

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

The description is very long (600+ words) but well-structured with capitalized sections. However, it contains redundant details and could be more concise without losing critical information.

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

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

Given the tool's complexity (multiple fan-outs, response shapes, safety checks, resolution rules) and lack of output schema, the description thoroughly explains return values, edge cases, and conditional behaviors, making it highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates input types but does not add new semantic details beyond the schema's examples and descriptions. No extra guidance on depth or include_raw specifics.

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

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

The description states it researches a Polymarket bet by pulling Pipeworx data, with specific input types (slug, URL, question text) and output (evidence packet + comparison). It is clear and specific, but does not explicitly distinguish from sibling tools like polymarket_edges or validate_claim.

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 (e.g., 'should I bet on X', 'what does the data say about Y') and includes fan-out examples by category. However, it does not mention when to avoid this tool or suggest alternatives, missing a complete usage guide.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: handling off-calendar fiscal years, data sources, sorting by primary metric, and returning 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 front-loaded with examples. Every sentence adds value; it is efficient in conveying tool behavior and usage. Could be slightly shortened but overall well-structured.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return data, edge cases (fiscal year handling), and ordering. It provides complete context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds valuable context: enum meanings (company vs drug), value formatting (tickers/CIKs vs drug names), and data pulled per type. Exceeds baseline by providing usage 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 states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and metrics. It distinguishes from sibling tools by explicitly preferring over sequential 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 tells when to use (comparing entities) and provides example queries. It advises to prefer over sequential single-pack lookups, but does not explicitly state when not to use. Clear context but no 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 (readOnlyHint, idempotentHint, destructiveHint) are consistent with description. Description adds substantial behavioral details: returns a findings packet with 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. Also mentions expected time (15-60s), parallel decomposition, and account/plan requirements.

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 bolded key terms and clear sections (account requirement, alternative, what it does, example use cases). It is fairly long but justified given the complexity. Could be slightly more concise, but every sentence adds value.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the input, process, output, prerequisites, limitations, and alternatives. It covers all necessary context for an agent to decide when and how 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 covers 100% of parameters with descriptions. Description enhances understanding by explaining that depth controls the number of facets (quick=3, standard=5, thorough=8) and that the question is decomposed into facets. This adds context beyond the schema's enum and string descriptions.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' in one call. It distinguishes itself from siblings like 'ask_pipeworx' and 'ask_pipeworx_grounded' by specifying that it is not open-web search and decomposes questions into facets. Examples of use cases are provided, e.g., 'compare X and Y's regulatory + financial exposure'.

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 when-to-use and when-not-to-use guidelines are given: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also states account requirements and that depth:'thorough' needs a paid plan, and advises using 'ask_pipeworx' if not signed in.

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 and idempotentHint, so the description adds value by detailing the output: returns top-N relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. This goes beyond annotations and clarifies behavior without contradiction.

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

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

The description is concise with four sentences, front-loaded with purpose, followed by domains, output details, and usage guidance. Every sentence earns its place; no 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?

Without an output schema, the description explains what is returned (names, descriptions, schemas, examples). It mentions the limit parameter but does not detail pagination or sorting. Overall, it is complete enough for a tool-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 description coverage is 100%, so baseline is 3. The description adds little beyond the schema: it mentions aliases for query (already in schema) and provides usage examples. The description's main value is about output, not parameters.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the domains covered and differentiates from siblings by emphasizing it is for browsing tools before calling other tools. The verb 'discover' and resource 'tools' are explicit.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use. It does not explicitly list when not to use, but the guidance is strong enough to distinguish from sibling tools that answer specific queries.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already signal safety. Description adds value by detailing the fan-out across multiple sources, return fields, and fallback behavior (e.g., patent soft-fail). Doesn't mention rate limits or performance, but sufficient given 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 verbose but front-loaded with example queries. Every sentence adds value: examples, source list, return structure, caveats. Could be slightly more concise, but structure is logical and scannable.

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

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

Given no output schema, description adequately explains return components (CIK, filings, fundamentals, patents, news, LEI) and caveats (patent sunset, fallback). Missing only minor operational details like pagination or error handling, but sufficient for agent understanding.

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 reinforces parameter usage with examples (e.g., 'AAPL' or '0000320193'), clarifies restrictions (only 'company' type, names not supported), and explains when to use resolve_entity. Adds meaning beyond schema enum and descriptions.

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

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

Description explicitly defines the tool's purpose with example queries like 'Tell me about X' and 'company profile for Microsoft', specifies it returns a holistic cross-source profile of US public companies, and distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing to resolve_entity for names.

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

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

Clear when-to-use guidance: 'ALWAYS PREFER' for holistic views, with explicit alternatives (resolve_entity for names). Also states what not to do: 'names not supported' and provides a fallback. No ambiguous usage scenarios.

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

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

Annotations already indicate destructiveHint=true. Description adds 'delete' context, but does not elaborate on side effects. No contradiction, but limited added behavioral 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?

Three concise sentences, front-loaded with the core action, followed by usage guidance and pairing suggestion. No wasted words.

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

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

Simple one-parameter tool with annotations covering idempotency and destructiveness. Description adds usage context and pairing, but could mention return or error behavior.

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

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

Schema coverage is 100%, baseline 3. The description mentions 'by key' but adds no new meaning beyond the schema's parameter description 'Memory key to delete'.

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 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from siblings 'remember' and 'recall'.

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

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

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related 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?

The description discloses key behaviors: fetches the page, extracts specific elements, and emits standard markdown format. Annotations already indicate read-only and idempotent behavior; the description adds useful detail on what the tool does without contradicting annotations. It could mention rate limits or error handling, but the coverage is good.

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 no wasted words. It front-loads the main purpose and immediately adds value with use cases. 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 low complexity (2 params, no output schema, rich annotations), the description fully covers what the tool does, its output format, and its practical applications. It leaves no obvious gaps for an AI agent to misunderstand.

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?

Both parameters are fully documented in the input schema (100% coverage). The description does not add additional meaning beyond what the schema provides for 'url' and 'max_links'. The baseline for full schema coverage is 3, as the description does not compensate further.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') and explicitly states the purpose: helping AI crawlers index a site. It also lists concrete use cases (client's site, own project, auditing competitor), making the tool's purpose clear and distinct from sibling tools like 'ai_visibility_check'.

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

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

The description provides clear usage context: 'Useful for' three scenarios. It implies when to use the tool but does not explicitly state when not to use it or list alternatives. Given the unique purpose and sibling tools, the guidance is adequate but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing return fields (id, type, params, etc.) and mentioning the include_inactive parameter, which is 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, no fluff. The first sentence delivers the core purpose and return fields, the second adds usage guidance. Efficient and well-structured.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains what it does, what it returns, 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% with one parameter (include_inactive). The description mentions 'active subscriptions' but doesn't add new meaning beyond the schema. 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' with a specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

The description provides context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It could explicitly mention when not to use it, but it's clear and helpful.

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

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

The description discloses rate limits, free status, and that feedback doesn't count against quota. It explains that the team reads digests daily and signals affect the roadmap. Annotations are all false, and the description provides substantial behavioral context beyond the annotations, with 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, front-loaded with purpose and usage, then additional constraints. Every sentence adds unique 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 feedback tool, the description covers purpose, usage, constraints, and behavior. No output schema is needed. It is complete given the tool's low complexity and the richness of schema 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying when to use each enum value, reinforcing the 2000-char limit, and emphasizing specificity. It does not repeat schema details but enriches them with usage 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 explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the feedback types (bug, feature/data_gap, praise) and distinguishes itself from sibling tools, none of which serve a feedback 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 provides clear usage guidance: when to use for bugs, features/data gaps, or praise. It also advises against pasting end-user prompts and notes rate limits (5 per identifier per day). No explicit when-not-to-use, but the context is sufficient and aligns with the tool's singular purpose.

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

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

Annotations already mark the tool as read-only, idempotent, and safe. The description adds valuable behavioral details: data source ('CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'). This enriches the agent's understanding 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 well-structured with the main purpose front-loaded. Each sentence adds distinct value (use cases, data source, caching). It is slightly verbose but not wasteful. A minor improvement could be merging some sentences, but overall excellent.

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 explains the return fields (top tools, top packs, total call volume) despite no output schema. It covers the input parameter, behavior, and data freshness. It lacks explicit error cases or rate limits, but given the annotations and simplicity, it is nearly 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 one parameter having an enum. The description explains the effect of each window choice ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), adding significant operational meaning beyond the enum labels.

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 'What other AI agents are calling on Pipeworx right now', clearly stating the verb (calling, trending) and resource (tools/packs on Pipeworx). It differentiates from siblings like discover_tools by focusing on real-time popularity rather than tool discovery.

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

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

Explicitly lists three use cases (1,2,3) that guide when to use this tool versus alternatives. Also provides context for choosing window durations, e.g., 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This is exemplary guidance.

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

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

Beyond annotations (readOnlyHint, non-destructive), the description adds rich behavioral detail: walking child markets, checking monotonicity, computing partition checks, Jaccard similarity filter, placeholder slug filtering, and fill check against live order book. It explicitly warns when not to trade ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade').

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

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

The description is comprehensive but somewhat dense. It front-loads the purpose and mode summary, then details each mode. Some technical jargon (e.g., 'semantic anchor', 'partition filter') might be heavy but is explained. Overall, it is well-structured and every part 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 complexity, the description is remarkably complete. It covers all three modes, parameter usage, algorithmic details, response structure, edge cases (fill check, placeholder filters), and links to a sibling tool. No output schema exists, but the description provides enough structure for the agent.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning: it explains event slug format with examples, topic as a seed question, and details how each mode behaves. This goes well beyond the minimal schema descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event mode, topic mode) and their use cases, effectively differentiating from sibling tools.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also mentions an alternative tool (polymarket_fill_risk) for custom sizing. However, it does not explicitly state when not to use this tool or compare directly to siblings 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 indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: caching strategy, model family descriptions, Kelly sizing, slippage assumptions, and diagnostics for empty segments.

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

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

The description is verbose but well-structured with clear sections (segments, knobs, response). It front-loads purpose. Some technical details could be trimmed, but overall it balances completeness with 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?

Given 9 parameters, no output schema, and high complexity, the description fully explains the response structure (by_segment, fed_candidates, diagnostics) and parameter effects, making it complete 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 coverage is 100%, and each parameter's description adds meaningful context beyond the schema, such as explaining min_kelly, min_edge_pp being net of slippage, and tradeable-edge filters.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on discovery and model-driven insights.

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

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

Provides explicit context for when to use (discovery without paging hundreds of markets) and describes tradeable-edge knobs for filtering. However, it does not contrast with sibling tools like polymarket_edge_tracker or specify when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by detailing dependencies on polymarket_edges snapshots, the TTL bound, and that data is based on daily closes. 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, starting with purpose, then arguments, then response format. While dense, every sentence provides essential information. It could be slightly more concise but remains effective.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, snapshot triggers). It provides a complete understanding of what the tool returns and its constraints.

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

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

Both parameters are documented in the input schema with descriptions, and the tool description repeats defaults and bounds without adding significant new semantic meaning beyond what schema provides. Since schema coverage is 100%, the description does not compensate for any gaps.

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 edge persistence and decay telemetry built from daily snapshots, answering how long edges have existed. It is specific about its purpose but does not explicitly contrast with sibling tools like polymarket_edges, leaving some ambiguity about when to use this versus related tools.

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

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

The description provides usage context by explaining the distinction between fresh and old edges, implying when to use it for historical analysis. However, it lacks explicit guidance on when not to use it or direct comparisons to alternatives, which limits its usefulness for an AI agent deciding between tools.

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

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

Annotations already declare safe read-only, idempotent behavior. Description adds critical context: walks the ladder, returns fill details and verdict, and warns about forced directional risk in baskets. No contradiction with annotations. Clearly explains 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?

Well-structured with sections and bullet-like formatting. Dense but every sentence adds value. Slightly long but justified given the complexity of two modes and multiple output fields. 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?

Despite no output schema, the description thoroughly documents return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict, per-leg detail, thin_legs). Covers key behavioral aspects and risks. Could be slightly more explicit about the JSON structure, but overall complete for this 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%, baseline 3. Description adds significant meaning: explains the mutual exclusivity of market and event, default side behavior for baskets (auto from partition sum), and size_usd interpretation (spend vs target proceeds vs settlement notional). Goes well beyond restating 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 it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinguishes between single-market and basket modes, each with specific outputs. References sibling tools and explains when to use this tool before acting on those signals.

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

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

Explicitly says to use this tool before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. Explains the consequences of not using it (partial fills leading to unhedged directional risk). Provides clear context for when to choose single-market vs basket mode.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: it details the output structure (leg-by-leg prices, top_spreads_pp), explains safety fields (compatibility_warning, temporal_alignment), and describes skipped cross-type/subtype counters. 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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds unique value, and key information is front-loaded. Despite length, it remains focused and avoids redundancy.

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

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

Given the tool's complexity (cross-venue spread with multiple edge cases), the description covers all essential aspects: modes, output structure, safety fields, temporal alignment, and cross-type/subtype skipping. No output schema is provided, but the response fields are explained adequately.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra value by listing the topic shortcuts, providing example values for explicit tickers, and explaining how explicit parameters override topic-mapped ones, thus going 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and provides concrete examples, setting it apart 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 explains when to use the tool (e.g., to compare prices across venues) and when not (e.g., when compatibility_warning fires or temporal alignment is false). It also warns that pre-mapped topics often yield non-tradeable spreads, 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 indicate safety; description adds scoping to identifier and behavior of omitting key to list all keys. No contradictions.

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

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

Three sentences, no fluff, front-loaded with the main action. 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, and scoping well. No output schema, but for a simple retrieval tool, the description is sufficient without 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 covers the single parameter fully; description adds context about omitting key for listing, and scoping, enhancing understanding beyond the schema.

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

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

Clearly states the verb (retrieve/list) and resource (saved values/keys). Distinguishes from siblings 'remember' and 'forget' by explicitly pairing 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?

Provides clear context for use (retrieving stored context) and mentions scoping, but lacks explicit when-not-to-use or alternative tools beyond 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 indicate read-only, idempotent, and non-destructive behavior. The description adds significant value by explaining that mark_read:true flags events as read, affecting subsequent calls, and clarifies the source ('the most recent alerts the evaluator has written to your persisted feed'). 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 structured with the purpose upfront and is fairly concise at about four sentences. It could be slightly tightened (e.g., removing the redundant 'Persisted feed' clarification), but overall it is efficient and well-organized.

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

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

Given no output schema, the description adequately explains return fields, filtering, and mark_read behavior. It also mentions polling and an alternative access method. For a tool with 5 optional parameters, this is comprehensive and leaves no critical 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 descriptions for all 5 parameters. The description enriches these by providing an example for the type parameter ('e.g. "sec_8k"'), explaining the effect of mark_read, and reinforcing the ISO timestamp format for since. This adds practical meaning beyond the schema.

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

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

The description begins with 'Pull fired events from your subscription feed,' using a specific verb and clearly identifying the resource. It further distinguishes the tool by detailing the returned fields (source, citation_uri, raw payload) and filtering options, setting it apart from sibling tools like list_subscriptions or recent_changes.

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: it explains when to use polling ('Polls work fine'), offers an alternative for scripts and dashboards (the GET endpoint), and details how parameters like type, since, and mark_read affect behavior. This gives 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral detail: it fans out to SEC EDGAR, GDELT/GNews (with fallback behavior), and USPTO (with sunset info). It also describes the return structure (changes[], total_changes, citation URIs), which goes well 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 front-loaded with multiple query examples, which is helpful for intent recognition, but could be slightly condensed. Nonetheless, every sentence adds value, and the structure is clear with the purpose stated early. It earns a 4 for being well-organized and informative without significant waste.

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

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

Given the tool has 3 simple parameters, no output schema, and rich annotations, the description is remarkably complete. It covers the tool's purpose, usage patterns, multi-source fan-out behavior, fallback logic, parameter semantics, return format, and differentiation from a sibling tool. 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 coverage is 100% with descriptions for all 3 parameters. The description adds further meaning: explains the type parameter is limited to 'company', gives examples for since (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), and offers a default suggestion ('Use '30d' or '1m' for typical monitoring'). This enriches the agent's 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 starts with numerous concrete query examples ('What's new with X', 'latest on Y'), then explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes from the sibling tool entity_profile by specifying when to use the alternative.

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

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

The description gives explicit usage context via example queries and directly says 'Use entity_profile instead when you want the static profile... regardless of window.' This provides clear when-to-use and when-not-to-use guidance with a named 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?

Description adds context beyond annotations: scoped by identifier, persistence duration (24h for anonymous, persistent for authenticated). Annotations already indicate non-read-only, idempotent, non-destructive; 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?

Very concise, front-loaded with purpose, no wasted words. Each 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?

Complete for a simple key-value store with no output schema: explains scope, persistence, and related tools (recall, forget).

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

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

Schema already provides full parameter descriptions (key, value). Description adds no new parameter-specific details beyond the broader context of scoping and persistence.

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 saves data for reuse, with specific examples (resolved ticker, target address, user preference). Distinguishes itself from siblings 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 states when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget for lifecycle management.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description adds valuable context about internal cascading through multiple lookup endpoints and that it replaces 2-3 manual lookups, which is 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 front-loaded with examples and efficient. It contains about 4 sentences, all earning their place. Slightly longer than minimal but very 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?

For a simple resolver with no output schema, the description fully explains return values per type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug), making it 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%, but the description enriches both parameters with examples (ticker, CIK for company; brand/generic for drug) and what each returns, adding practical meaning beyond the schema's brief descriptions.

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

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

The description uses concrete examples and clearly states it resolves user-spoken names to canonical identifiers. It distinguishes itself as the tool to use first when needing an ID, which differentiates 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 says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternatives, but the context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint (all safe). The description adds meaningful behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. This goes well 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 clear sentences plus a brief note, front-loading the core action. It could be slightly more concise by omitting the parenthetical example, but it remains efficient and well-structured.

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

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

No output schema exists, but the description explains return values (ranked list with score, confidence, signal density). Input parameters are well-covered in the schema. For a complex tool, this is fairly complete, though output structure could be more precise.

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

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

Schema description coverage is 100%, so parameters are well-defined in schema. The description does not add additional parameter-level information beyond overall context. Baseline 3 applies as schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare', the resource 'AI visibility', and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (potentially broader).

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

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

The description provides context with 'Useful for competitive AI-marketing audits' and an example question. However, it does not explicitly state when NOT to use (e.g., for single-entity checks) or mention alternatives like ai_visibility_check, though the sibling list exists.

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?

Describes graceful degradation on partial failures, mentions possible 5-30s delay for new versions, and lists return contents. Annotations already indicate read-only, idempotent, non-destructive behavior, and description adds further context 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 thorough but somewhat lengthy. However, it is well-structured with clear sections and front-loads the main purpose. Every sentence adds value, though some 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 (multiple data sources, partial failures), the description adequately covers what to expect. Though no output schema, the return structure is described. It leaves no obvious gaps 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?

Adds useful context beyond schema: scoped packages accepted, default version behavior. Schema coverage is 100%, so baseline is 3 but description elevates it with practical details.

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

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

The description clearly states the tool performs a composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools like deps.dev:version by specifying the scope.

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

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

Explicitly says to use when evaluating package safety, popularity, or size, and notes that for non-npm ecosystems, alternative tools should be used. Provides concrete query examples.

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 details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. No contradiction with readOnlyHint, 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?

Concise yet comprehensive. Front-loaded with purpose, then use case, then technical 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?

No output schema, but description explains return format (passages with offsets and scores) and embedding details. Complete for 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 100%, but description adds value with examples of natural-language queries and context about 'text' being fetched record. Baseline 3, plus extra examples and rationale.

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 semantic search inside fetched records with specific examples (SEC 10-K, article). Distinguishes from sibling ask_pipeworx_grounded by explaining pairing. Verb+resource+scope is specific.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions saving context. Provides alternative pairing with ask_pipeworx_grounded.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it uses DataForSEO and provides counts, but doesn't add significant behavioral traits beyond annotations. No contradictions.

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

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

The description is two sentences plus a code example, no extra fluff. All content is relevant 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 partially explains return values (counts) but doesn't fully describe output structure. Since no output schema exists, more detail would be helpful. Annotations are rich, but the description could be more complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with an example call showing usage of target and limit, and describes _apiKey encoding, which clarifies the format beyond schema.

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

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

The description clearly states the tool returns anchor-text distribution with backlink and referring-domain counts, and includes an example. It doesn't explicitly differentiate from sibling tools like seo_backlinks_list or seo_referring_domains, but the focus on anchors is distinct.

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 with the question 'What anchor text do links to this site use' and an example. However, it does not specify when not to use it compared to similar tools, nor does it mention prerequisites or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral context by specifying 'monthly history' and the specific metrics (backlinks, new/lost domains, rank). This goes beyond annotations, though it does not mention output format or auth details (already in schema). 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 two sentences plus a concise code example. It is front-loaded with the core purpose and uses efficient phrasing. Every sentence earns its place 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?

Without an output schema, the description adequately summarizes the return data (monthly history, new/lost referring domains, rank) and frames the use case. It covers the key aspects for an agent to select and invoke the tool, though exact response structure is not detailed.

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 for each parameter, including defaults and constraints. The description adds an example call showing typical usage, which is helpful but does not provide new semantic meaning beyond the schema. 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 returns backlink growth over time for a domain, including monthly history of backlinks, new/lost referring domains, and rank. It distinguishes from sibling tools like seo_backlinks_list and seo_backlinks_summary by focusing on temporal trends. The example with 'nike.com' reinforces the purpose.

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

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

The description implies usage for tracking backlink trends over time with the question 'Is this domain gaining or losing links', but does not explicitly state when to use this tool versus siblings like seo_backlinks_summary for a snapshot or seo_backlinks_list for raw data. No alternatives or exclusions are 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 already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds value by specifying that data comes from DataForSEO and listing the returned fields (source domain, anchor text, etc.). This contextualizes the annotations and gives the agent a clear picture of the tool's behavior 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 two sentences plus a concise code example. It front-loads the purpose and packs all essential information without extraneous words. Every sentence earns its place.

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

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

There is no output schema, so the description compensates by listing the returned fields (source domain, anchor text, dofollow flag, dates). It also mentions the data source (DataForSEO) and provides an example. While it could mention default/max limit (which is in the schema), the description is largely complete for the agent to understand inputs 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 description coverage is 100%, so the description does not need to add much. It reinforces the target parameter with an example and explains the _apiKey format. This is helpful but does not go beyond what the schema already provides, earning a baseline score 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 that the tool returns a list of backlinks pointing at a domain, with specific fields like source domain, anchor text, dofollow flag, and dates. It distinguishes from sibling tools by specifying 'the actual list of linking pages', which contrasts with aggregated or filtered versions like seo_backlinks_summary or seo_backlinks_anchors.

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 includes an example and the phrase 'Who links to this site', implying a use case. However, it does not explicitly state when to choose this tool over siblings (e.g., when a raw list is needed vs. summary stats). No when-not-to-use 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 already cover read-only, idempotent, and non-destructive behavior. The description adds value by specifying the data source (DataForSEO) and providing an example call, but does not go beyond what annotations convey or introduce new behavioral details.

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

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

Two sentences plus an example, front-loaded with the main purpose, no extraneous text. Every sentence contributes meaning.

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 summary tool with 4 parameters, good annotations, and no output schema, the description covers the return fields, usage example, and purpose. No gaps 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?

Schema coverage is 100% with good parameter descriptions. The description adds an example and clarifies the target format (e.g., domain without protocol), which provides additional context beyond the schema.

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

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

The description clearly states the tool returns a backlink profile summary including specific metrics (total backlinks, referring domains, domain rank, etc.) and positions it as a 'how strong is this domain's link profile' overview, distinguishing it from sibling tools like seo_backlinks_anchors or seo_backlinks_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?

The description implies use for an overall strength assessment, and given sibling tools for specifics, it's clear when to use this summary. However, there is no explicit statement of when not to use or direct comparison to alternatives.

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

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

Annotations already mark the tool as safe (readOnlyHint, idempotentHint), reducing the burden. The description adds that results include rank, backlink count, and spam score via DataForSEO, providing 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 two sentences plus an example, front-loading the core purpose and example. Every element adds value, with no wasted words.

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

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

With no output schema, the description mentions returned fields (rank, backlink count, spam score), compensating somewhat. It lacks pagination details or error handling, but annotations and schema cover safety and parameters adequately.

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

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

Schema coverage is 100%, so the description does not need to compensate for missing parameter docs. The example demonstrates target, limit, and _apiKey usage, but does not explain backlinks_status_type or add semantics beyond the schema.

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

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

The description clearly states that the tool returns referring domains for a target, including rank, backlink count, and spam score, which distinguishes it from sibling tools like seo_backlinks_list that deal with individual backlinks. The example further clarifies usage.

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

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

The description implies usage for answering 'Which sites link to this domain,' providing context but no explicit guidance on when to use versus alternative tools (e.g., seo_backlinks_list). It lacks exclusions or prerequisites, but the context is clear enough for basic 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?

The description adds significant detail beyond annotations, including the need for OAuth, delivery channel limits (10/day SMS cap), webhook auto-disable after 10 failures, and webhook HMAC signing. 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 somewhat verbose but well-structured with bullet points and examples. It front-loads the main purpose and includes necessary details, though 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 (3 parameters, nested objects, no output schema), the description thoroughly covers purpose, all parameter types, examples, side effects, limitations, and required account setup. Return value is implied.

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 further enriches parameter meaning with type-specific examples (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailed delivery object constraints (phone verification, webhook signing).

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 sibling tools 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?

The description provides clear context, including the requirement for a Pipeworx OAuth account and that anonymous/BYO users cannot persist subscriptions. It lists supported types and delivery channels but does not explicitly state when not to use this tool or mention 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 declare readOnlyHint, openWorldHint, idempotentHint = true, destructiveHint = false. Description adds that it returns 'category-bucketed example questions with tool+argument shapes' and draws from a live catalog. No contradictions. Could add more about if results are static or dynamic, but sufficient.

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

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

Description is front-loaded with common user queries, making it easy to grasp. Somewhat verbose but every sentence adds value. Could trim redundant phrasing but overall well-structured.

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

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

Given the tool's role as an onboarding entry point, description is thorough: explains return format, argument behavior, and even points to meta-tools. No output schema, but the description adequately describes what to expect. Completes the context for an agent deciding to use this tool first.

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

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

Only one optional parameter with schema coverage 100%. Description adds concrete examples of topic values (finance, pharma, etc.) and explains behavior when omitted (full spread), which adds meaning beyond the schema. Slightly more detail on what topic values are allowed would be nice, but the schema description already covers it.

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 is the onboarding entry point, returns example questions organized by category, and uses specific verbs like 'returns category-bucketed example questions.' It distinguishes from sibling tools like ask_pipeworx and discover_tools by positioning itself as the first step. No ambiguity.

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.' Provides guidance on when to call with no arguments versus with a topic. Could be improved by explicitly mentioning when not to use it (e.g., if already familiar with capabilities).

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 context beyond annotations: row is deactivated not deleted, ownership enforced. 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?

Three sentences covering key points without waste. Could be slightly tighter but not overlong.

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 one-param tool with annotations, description covers purpose, ownership, and behavioral outcome adequately.

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

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

Schema coverage 100% and schema description explains the id parameter. Description reinforces but doesn't add new meaning.

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

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

Clearly states verb (Cancel) and resource (subscription by id). Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement, guiding when to use. Does not explicitly name alternatives but implies limitations.

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, idempotent, read-only, open-world behavior. The description adds detail on the return format (verdict, structured form, actual value with citation, percent delta) and notes it replaces multiple sequential calls, providing transparency on efficiency and output structure without contradicting annotations.

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

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

The description is front-loaded with query examples and usage context. It is informative but slightly verbose; however, every sentence contributes value. It could be trimmed slightly, but overall it is well-structured and efficient.

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

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

Given the tool's complexity (claim verification with structured output and no output schema), the description covers everything needed: purpose, usage scenarios, supported domains, return values, and performance benefit. No gaps are evident.

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

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

The single parameter 'claim' has 100% schema description coverage, including an example. The description adds context about natural-language claims but does not significantly enhance what the schema already provides. Per guidance, baseline 3 is appropriate when schema coverage is high.

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 defines the tool as a natural-language claim verification against authoritative sources, with clear examples of queries like 'Is it true that...' and 'fact check'. It distinguishes itself from sibling tools like deep_research by specifying it replaces 4–6 sequential calls and focuses on company-financial claims for public US companies.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies supported domains (company-financial claims via SEC EDGAR + XBRL). It does not explicitly list exclusions or alternative tools, but the context makes it clear that this tool is for factual verification, not general research.

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