Shopify

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds behavioral context beyond annotations: it explains the default model costing, the BYO key requirement for Anthropic (with direct billing), and the return structure (per-model score, confidence, signals, raw_response). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the main action and then adds essential details (default model, key usage, return values). Every sentence adds value—no fluff or repetition.

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

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

Given the tool's complexity (multiple models, optional key, output structure) and the absence of an output schema, the description adequately explains return values (per-model object plus combined view). It also covers use cases and key nuances, making it complete for an AI agent to understand 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 description coverage is 100%, and each parameter is already well-described in the schema (e.g., 'entity', 'models', '_apiKey', 'context'). The tool description reiterates the default model and key usage but adds minimal 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 the tool's function: probing LLMs for knowledge about an entity and scoring visibility. It lists specific use cases (AI-marketing audits, brand checks) and differentiates from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring.

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

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

The description provides clear context for when to use the tool (e.g., marketing audits, competitive monitoring) and mentions the default free model and optional BYO key for Anthropic. However, it does not explicitly exclude alternatives or state when not to use it, so it 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: the tool routes to many tools, fills arguments, returns structured answers with stable citation URIs. No contradiction found.

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

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

The description is somewhat lengthy but well-structured with examples and clear guidance. It is front-loaded with the key preference statement. Could be trimmed slightly, but the investment improves completeness.

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

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

Given the complexity (many tools and sources), the description adequately covers the tool's scope and provides multiple example queries. Lacks output schema details, but the mention of structured answers with citation URIs is sufficient.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reiterates the 'question' parameter but does not add new semantics beyond what the schema already provides. 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 routes natural language questions to a vast ecosystem of 3,775 tools across 895 verified sources, providing structured answers with citations. It distinguishes itself from web search with a strong preference directive.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for factual questions about specific domains (SEC, FDA, stocks, etc.) and provides concrete examples. This gives clear when-to-use guidance and implies when alternatives (web search) are less preferred.

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 several behavioral traits beyond annotations: it is hallucination-resistant, extracts answer only from tool result, costs one extra LLM call, and returns explicit refusal reasons. Annotations already indicate readOnlyHint and idempotentHint, which align with the description. No contradiction.

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

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

The description is somewhat long (4-5 sentences) but every sentence adds value. It is front-loaded with the core purpose and includes important details about return format and usage. Could be slightly more concise, but not overly verbose.

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

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

Given the complexity (6 parameters, 1 required, no output schema), the description is very complete. It explains the return format (answer, evidence, confidence, source, fetched_at) and lists possible refusal reasons. The process flow is clearly described.

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

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

Schema description coverage is 100%, with detailed alias descriptions for the question parameter. The description adds minimal extra semantics beyond schema, stating 'Same routing as ask_pipeworx' implying the parameter works similarly. 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's purpose as a 'Hallucination-resistant answer mode for high-stakes reads.' It explains the process: picks the right tool, fills arguments, fetches data, and extracts the answer ONLY from the tool result. This distinguishes it from the sibling ask_pipeworx.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also advises to 'prefer ask_pipeworx for casual lookups,' providing clear guidance on alternatives.

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

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

The annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description goes far beyond by detailing behavioral traits such as fan-out to data sources, resolver confidence levels, parent event extraction, GDELT fallback handling, safety mechanisms (low-confidence short-circuit, closed market detection), and cancellation rule parsing. It fully discloses the tool's behavior and edge cases.

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

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

The description is very long and densely packed with information, covering classifiers, fan-out examples, response shapes, resolver contract, parent events, etc. While well-structured, it could be more concise by moving some details to a separate reference section. However, front-loading the core purpose and usage is effective.

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

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

Despite having no output schema, the description thoroughly documents input parameters, behavior, and output fields (market, analysis, evidence, resolver details, parent event, news fields). It covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. Given the tool's complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond schema by explaining the market parameter accepts slugs, URLs, or question text; clarifying depth levels ('quick = 2-3 evidence sources, thorough = full fan-out'); and detailing include_raw's impact on response size and content. It also provides usage examples.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via data pull), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on individual bet research with examples like 'should I bet on X'.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes guidance on when results may be unreliable (low-confidence matches, closed markets) and examples for different market types. However, it does not explicitly list alternative tools or conditions when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context: for 'company', it pulls specific financial metrics from EDGAR/XBRL with correct fiscal year handling; for 'drug', it pulls FAERS data, FDA approvals, and trial counts. It also mentions results sorted by primary metric and returns paired data with citation URIs.

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

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

The description is lengthy but well-structured, starting with example queries and key instructions. It front-loads the primary purpose and usage preference. While every sentence adds value, slight trimming could improve conciseness.

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

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

Given the tool's complexity (two entity types with distinct data sources, sorting, citation URIs), the description covers all essential aspects. It specifies what data is returned for each type, how sorting works, and mentions output format. No output schema exists, so description carries full burden and meets 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 both parameters described. The description enriches meaning: explains that 'type' selects the data source (company vs drug) and that 'values' require tickers/CIKs for companies and drug names for drugs, with min/max constraints. It also clarifies behavior like sorting and output format, adding value beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with example queries like 'compare X and Y' or 'rank these companies'. It distinguishes itself from sibling tools like entity_profile by offering parallel comparison instead of 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?

It explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear guidance on when to use this tool. It also implies alternatives for single entity lookups, such as entity_profile or resolve_entity, without needing to name them.

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 rich details: parallel decomposition, verbatim evidence with confidence/source, explicit gaps for unanswerable facets, and expected 15-60s response time. 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?

Description is well-structured with front-loaded purpose, followed by mechanism, usage, and requirements. Somewhat long but every sentence contributes value; 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?

Comprehensive for a complex tool. Covers purpose, method, output structure (findings packet with gaps), limitations, requirements, and expected latency. No output schema, but description sufficiently covers return 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. Description adds meaning by explaining depth options (quick=3, standard=5, thorough=8) and stating that broad questions are acceptable, enhancing the schema.

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

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

The description clearly states the tool performs grounded multi-source research in one call, with specific verb 'research' and resource 'multi-source' across 895 sources. It distinguishes itself from sibling tools like ask_pipeworx, which is for single 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?

Explicit usage guidance: 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups.' Prerequisites (Pipeworx account) and depth limitations (paid plan for 'thorough') are stated clearly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains behavior beyond annotations 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 moderately long but well-structured: a one-liner purpose, domain list, return format, and usage advice. Each sentence serves a purpose. Could be slightly tighter but remains clear and informative.

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

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

No output schema, but the description adequately explains what is returned (top-N tools with names, descriptions, schemas). For a discovery tool, this covers the essential output. Minor omissions like pagination or error handling are acceptable at this level.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-specific meaning beyond what the schema already provides (e.g., aliases and limit defaults). No extra semantics to raise the score.

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 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists many specific domains (SEC filings, FDA drugs, etc.) and the context of tool discovery. Distinguishes from sibling tools by being the entry point for exploring the toolset.

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

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

Explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implicitly when not to use (for single answers).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds behavioral context: fans across multiple sources, USPTO sunset soft-fail, and return structure (filings with URIs, fundamentals sorted). 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 front-loaded with example queries and key guidance, but it is somewhat lengthy with a bullet-like list of return fields. It could be tightened without losing essential information. Still, it is 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 the tool's complexity (multiple data sources, no output schema), the description covers what is returned (CIK, filings, fundamentals, patents, news, LEI), limitations (USPTO sunset, names not supported), and recommended usage. Missing details about pagination or error handling, but overall sufficient.

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

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

Schema coverage is 100% (both type and value described). The description adds context by explaining that type is limited to 'company' and value must be ticker or CIK, not names. This adds some value beyond the schema but does not significantly enhance parameter understanding.

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

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

The description starts with clear example queries like 'Tell me about X' and 'company profile for Microsoft', specifies the verb 'profile' and resource 'US public company', and distinguishes itself from siblings by stating it is a holistic cross-source profile and that names are not supported.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view' and instructs to use resolve_entity first if only a name is available. Provides clear input format (ticker or CIK) and what not to use (names).

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 destructiveness and idempotency. Description adds context about clearing sensitive data and pairing with other tools, which is helpful but not essential beyond annotations.

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

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

Three sentences: action, usage, sibling relation. Every sentence serves a clear purpose. Front-loaded with the main action. No redundant words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and tool relationships completely. 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% and already describes the 'key' parameter as 'Memory key to delete'. Description only mentions 'by key' without adding format or constraints, so no added value beyond baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', identifying both the verb and resource. It distinguishes from siblings 'remember' and 'recall', making its purpose unambiguous.

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

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

Provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data...'. However, it does not mention when not to use, missing 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?

Beyond annotations (readOnly, idempotent, non-destructive), description discloses fetching page, extracting key info, and emitting standard format. 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?

Two sentences plus bullet list, no wasted words, front-loaded with purpose and outcome.

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 tool purpose, output format, and use cases adequately. No output schema needed. Could mention error handling or site accessibility but not required for completeness.

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

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

Both parameters are fully described in the schema (100% coverage). Description restates default for max_links but adds no extra meaning beyond schema.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with specific output format and purpose for AI crawlers. It is distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

Explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). Does not state when not to use, but provides clear positive guidance.

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

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

Annotations already cover non-destructive, read-only nature. Description adds return fields but limited additional behavioral insight.

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

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

Two efficient sentences, front-loaded with verb and resource, no waste.

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

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

With strong annotations, description provides return fields and usage context, sufficient for a read operation.

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% with clear parameter description; description does not add 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?

Clear verb 'list' and resource 'subscriptions' with distinction from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says to use for reviewing before adding or finding id to cancel, providing clear context.

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

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

Discloses rate limits (5 per identifier per day) and that it's free and doesn't count toward quota, which is critical behavioral info not in annotations. No contradiction with annotations (all false).

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 and well-structured: starts with action, then usage scenarios, then behavioral details. Every sentence earns its place 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?

Complete for a feedback tool with 3 params and no output schema. Covers purpose, usage, rate limits, quota impact, and content guidelines. No gaps.

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

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

Schema descriptions cover 100% of parameters, so the description adds minimal extra value. It reinforces the 'don't paste prompt' rule for the message field but does not significantly augment schema meaning.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, features, data gaps, or praise. It uses specific verbs and identifies the resource (Pipeworx team), and distinguishes it from sibling tools that are data retrieval or action-oriented.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and what to include (tool/pack context) and what not to include (end-user prompt). This helps the agent decide correctly.

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

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

Annotations already mark as readOnly, idempotent, non-destructive. Description adds valuable context: self-aggregating from analytics engine, no PII, cached 5min-1h. No contradictions.

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

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

Concise paragraph with front-loaded main action and bulleted use cases. Every sentence adds value—no redundancy or filler.

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

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

For a simple read-only tool with no output schema, the description explains return content (top tools, packs, volume), data source, caching, and privacy. Covers all necessary context.

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

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

Schema coverage is 100%. Description adds extra meaning by explaining window trade-offs (hot vs steady-state demand) and ties to use cases, enriching beyond schema enum values.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. Specifies it shows what other AI agents are calling on Pipeworx, distinguishing it from discovery or entity lookup tools in siblings.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, aligning use case with demand. Does not specify when not to use, but the positive guidance 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 readOnly, openWorld, idempotent. The description adds extensive behavioral details: monotonicity/partition checks, semantic anchor (Jaccard similarity), partition filter (placeholder detection), fill check against CLOB depth, and conditions for not trading. No contradictions with annotations.

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

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

The description is dense and structured with sections for modes, semantic anchor, partition filter, fill check. Every sentence adds value, though some detail could be condensed. It uses bold for emphasis and starts with the key requirement. Slightly verbose but 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?

Despite no output schema, the description fully documents return values (opportunities array with fields, partition_check object) and error/skip conditions (skipped_low_similarity, placeholders_filtered). It also references a sibling tool for custom sizing. For a tool with two optional parameters, this is 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%, but the description adds significant meaning: it explains what each parameter triggers (single-event vs cross-event), provides concrete examples (slugs, seed questions), and describes the behavior (walks child markets, searches related events). This goes beyond the schema's 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event vs topic) with clear verb-resource combinations, making the purpose unambiguous and distinct from sibling tools.

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

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

Explicitly requires one of 'event' or 'topic' and provides guidance on when to use each mode (e.g., 'event recommended for a specific market', 'topic for cross-event scanning'). It also explains limitations of single-event mode and what cross-event catches. Lacks direct differentiation from sibling tools like polymarket_edges, but the usage context is clear.

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

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

The description extensively discloses behavioral traits beyond annotations: it explains the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching at KV level keyed on all knobs, diagnostic fields (e.g., '#_diagnostics'), and specific calculations (e.g., edge_pp_net, kelly_fraction). It also notes Fed bets are excluded from ranking. This far exceeds the minimal read-only, idempotent hints in annotations, providing deep transparency about how the tool behaves and what it returns.

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

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

The description is front-loaded with the core purpose and use case, then organized into subsections for model families. While verbose, every sentence adds substantive information (e.g., model details, output structure, caching). It could be slightly more concise by removing some formula details (e.g., 'lognormal barrier from 90d FRED log-returns'), but overall it's well-structured and informative for an agent.

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

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

Given no output schema and 9 parameters, the description is remarkably complete. It details the output structure (by_segment with three categories, fed_candidates/fed_note, _diagnostics), explains how to interpret each field, and provides guidance on parameter usage. The diagnostic section ('#_diagnostics{...filter_skips}') ensures agents understand why segments might be empty. This level of completeness compensates fully for the lack of 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 coverage is 100%, so baseline is 3. The description adds value by grouping parameters into 'Tradeable-edge knobs' (min_liquidity, max_spread_pp, min_partition_leg_kelly) and explaining their effects on output filtering (e.g., 'drop opportunities where edge isn't realizable'). It also provides context for parameters like 'window' (volume window) and 'slippage_pp' (assumed execution slippage, with guidance on adjustment). This extra context justifies a 4.

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

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

The description clearly states the tool 'scan[s] top Polymarket markets and return[s] opportunities where Pipeworx data disagrees with market price,' with a specific verb ('scan and return'), resource ('top Polymarket markets'), and outcome ('opportunities where Pipeworx data disagrees'). It distinguishes itself from siblings like 'polymarket_arbitrage' and 'polymarket_kalshi_spread' by focusing on model-driven edge rather than arbitrage or spreads. The built-for phrase ('what should I bet on today') further clarifies its niche.

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

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

The description provides a primary use case ('what should I bet on today') and notes that agents discover opportunities without paging hundreds of markets, implying when to use it. However, it lacks explicit guidance on when NOT to use this tool vs alternatives (e.g., 'polymarket_arbitrage') and does not mention prerequisites or contexts where it would be inappropriate. The guidance is implicit and relies on the tool's name and sibling list for differentiation.

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 non-destructive. The description adds behavioral details: data from daily snapshots, response structure (tracked, expired, snapshot_dates), computation of decay/trend, and limits (60-day TTL). 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 structured: purpose, parameter details, response format, limits. Each sentence adds value, though some density could be reduced. Good front-loading of purpose.

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

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

No output schema exists, so description fully explains return fields (tracked with time-series, trend, decay; expired with lifespan_days; snapshot_dates). Also covers history depth and computation details. Complete given tool 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?

Input schema has 100% coverage with descriptions for both parameters. The description adds defaults (days=14, window='1wk'), valid ranges (max 30 for days), and conceptual context (snapshot family). This adds meaning beyond schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It uses a specific verb (answers) and resource (edge persistence), and distinguishes from sibling tools like polymarket_edges by focusing on historical decay.

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 context by contrasting fresh vs. old edges, but does not explicitly state when not to use or name alternatives. It provides clear context for when this tool is valuable.

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

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

The description adds significant behavioral details beyond annotations, such as walking the ladder, returning slippage_pp, verdict, thin_legs, and forced_directional_risk. It explains the risk of unhedged directional positions, which is critical for safe tool use.

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

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

The description is well-structured with clear sections for each mode, front-loaded purpose, and efficient use of text. It is slightly longer but every sentence adds necessary detail.

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

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

Given the complexity (two modes, no output schema), the description fully explains the return fields, risks, and use cases. The agent can correctly decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of size_usd in each mode (max spend vs. settlement notional) and clarifying side defaults. This goes 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 checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes single-market from basket modes. It is specific and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear context. It also warns about risks from partial fills but does not explicitly list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details beyond annotations: temporal alignment checks, compatibility warnings (non-equivalent bet shapes, semantically unrelated events), and skipped cross-type/subtype counters. 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides necessary detail, though could be slightly more concise. Given complexity, it's appropriate.

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 having no output schema, the description explains response structure (leg-by-leg prices, spread top_spreads_pp, safety fields). It also covers temporal alignment, compatibility scenarios, and real-world rarity of tradeable spreads. Comprehensive for a complex tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the exact topic values, explaining that topic auto-fetches matching events, and how explicit overrides work. This enriches the schema information.

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

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

The description explicitly states it calculates 'cross-venue spread between Kalshi and Polymarket for the same resolving question', using specific verbs like 'auto-fetch' and 'explicit pairings'. It distinguishes from siblings like 'polymarket_arbitrage' by focusing on a specific cross-venue comparison.

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

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

Clearly describes TWO MODES: topic shortcuts for 10 pre-mapped macros and explicit event ticker/slug for custom pairings. Includes warnings that most pre-mapped topics return compatibility_warning, helping agents decide when to use and what to expect.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping by identifier and pairing context, which goes beyond annotations.

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

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

Three sentences, front-loaded with purpose, no redundant words. 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?

Simple tool with one optional parameter and no output schema; description covers behavior, scoping, and relationships completely.

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

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

Schema coverage is 100% with clear parameter description. The tool description adds the detail about omitting key to list all, but mostly reiterates schema info.

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 retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from siblings like 'remember' and 'forget'.

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

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

Describes when to use (look up context stored earlier) and mentions pairing with remember and forget. Lacks explicit when-not-to-use, but context is clear.

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

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

Detailed disclosure of mark_read side-effect and return fields, but contradicts annotation readOnlyHint=true. The description states mark_read modifies read status (a write), conflicting with the read-only hint, making the overall behavioral picture inconsistent.

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?

Four concise sentences, front-loaded with main purpose, each adding essential information without redundancy. Efficiently covers purpose, return fields, filtering, state management, and alternative access.

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 (source, citation_uri, raw event payload), parameter behaviors, polling usage, and an alternative endpoint. Complete for a list/feed tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds meaningful context beyond the schema by explaining mark_read's effect on subsequent calls and the purpose of 'since' and 'type' 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 'Pull fired events from your subscription feed', specifying the verb (pull) and resource (fired events). It distinguishes from sibling tools like 'list_subscriptions' by focusing on events rather than subscription metadata.

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: can filter by type and/or ISO timestamp, use mark_read to manage read state, and mentions polling suitability. Also offers an alternative HTTP endpoint for scripts, but doesn't explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making safe usage clear. The description adds substantial behavioral details: fanning out to SEC, GDELT/GNews (with fallback), USPTO soft-fail, and return structure (changes grouped by source, total_changes, pipeworx URIs). No contradictions with annotations.

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

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

The description is well-structured and front-loaded with purpose examples. Each sentence adds meaningful information (sources, parameter details, return format). It is moderately long but every part earns its place. A slight reduction in technical jargon could improve conciseness, but it remains 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 (multiple data sources, fallback, parameter options) and the presence of comprehensive annotations, the description covers all key aspects: purpose, parameters, behavior, return structure, and alternative tool. It could mention error handling or rate limits explicitly, but the fallback description covers rate-limit cases. Overall, it is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by explaining `since` accepts ISO date or relative shorthand with examples, and clarifies that `value` can be ticker or CIK. It also provides typical monitoring suggestions for `since`. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a 'change feed for a company in the last N days/weeks/months' with specific query examples like 'What's new with X'. It distinguishes itself from the sibling 'entity_profile' by directing users to that tool for static profiles. The verb (get changes) and resource (company) 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 provides explicit when-to-use examples and contrasts with entity_profile. It also gives parameter usage guidance ('Use "30d" or "1m" for typical monitoring'). However, it does not discuss when to use other relevant siblings like deep_research or compare_entities, but the provided guidance is sufficient for the primary use case.

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

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

Discloses persistence behavior (authenticated users persistent, anonymous 24hr), scoping by identifier, and key-value storage. Annotations already indicate idempotentHint=true and destructiveHint=false, and description adds valuable 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?

Three sentences front-load purpose, then usage, then behavioral details. No extraneous words or repetition.

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

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

With two simple parameters, full schema coverage, and clear annotations, the description is complete. It covers purpose, usage, and storage behavior 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 already provides 100% coverage with examples in parameter descriptions. The tool description adds minimal new info about parameter usage, so baseline 3 is appropriate.

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides specific examples like tickers, addresses, preferences. It distinguishes itself from sibling tools 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and gives concrete scenarios. Also pairs with 'recall' and 'forget'.

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

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

Annotations already provide safety and idempotency hints. The description adds significant value by detailing internal cascading through multiple endpoints and specifying return fields (ticker, CIK, RxCUI, citation URIs) beyond what annotations cover.

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 structured with bullet points for entity types. It is appropriately detailed; each sentence serves a purpose. Slightly verbose but 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?

Despite no output schema, the description fully explains return values for both entity types, including citation URIs. It covers behavior and output comprehensively, making the tool fully understandable.

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 reinforces parameter meanings with concrete examples (e.g., 'ticker (AAPL), CIK (0000320193)'). This adds useful context beyond the schema's enum and brief descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). It is well differentiated from sibling tools like 'compare_entities' and 'entity_profile' by emphasizing 'use FIRST when you have a name but need an ID.'

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

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

Explicit guidance to use this tool first when an ID is needed, with supported types listed. While it doesn't explicitly say when not to use, the 'first' priority and clear input requirements make usage context clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds that it probes with ai_visibility_check, ranks by score, and returns score, confidence, signal density. No contradictions.

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

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

Three sentences: purpose, mechanism, use case. No fluff, front-loaded with core action.

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 4 parameters (1 required) and no output schema, the description explains what is returned (ranked list with score, confidence, signal density) and the process (probes with ai_visibility_check), fully covering usage.

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

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

Schema coverage is 100%, but description adds value by stating that the first entity is treated as the 'subject' for narrative and that omitting models defaults to workers-ai, providing meaning beyond schema.

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

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

The description states a specific verb 'Compare AI visibility' and resource 'multiple entities', and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides clear context for competitive AI-marketing audits and implies when to use this vs the single-entity ai_visibility_check, but does not explicitly state when not to use or list 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?

Discloses graceful degradation on partial failures and potential delay (5-30s for first measurement) for bundlephobia. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and description adds valuable behavioral 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?

Description is front-loaded with the main purpose and well-structured. While somewhat long, every sentence provides necessary detail. Minor room for trimming but overall efficient.

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

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

Complex tool with multiple data sources and return structure; description covers summary block, per-advisory detail, links, alternative versions, ecosystem limitation, and partial failure behavior. No output schema, so description sufficiently explains return format.

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

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

Schema description coverage is 100% and already explains package (scoped packages accepted) and version (defaults to latest). Description does not add additional parameter semantics beyond what schema provides, so baseline 3 is appropriate.

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

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

Description clearly states it's a composite check for npm packages, covering safety, popularity, size, and cost. It distinguishes from siblings by specifying the exact use case and data sources.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small' and notes ecosystem limitation (NPM only v1), with fallback guidance for other ecosystems. This provides clear when-to-use and when-not-to-use context.

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

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

Annotations already provide readOnly, idempotent, openWorld hints. Description adds behavioral traits: saves context, returns passages with offsets for verification, technical details on embeddings (BGE-base-en, cosine, 500-char windows, 200K char cap with truncation flag). No contradiction.

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

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

Description is 4 sentences, front-loads core action, then expands on details. No fluff; each sentence adds value. Could be slightly more concise but 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 3 params and no output schema, description is highly complete: explains tool purpose, how it works, limitations, output format (passages with offsets and scores), and pairing with other tools.

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

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

Schema coverage 100% gives baseline 3. Description adds meaning: explains text as document text, query with examples, limit with default. Also explains purpose of offsets and model 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?

Description clearly states semantic search inside a fetched record, with specific use cases (SEC 10-K, article, long tool result). Distinguishes from sibling ask_pipeworx_grounded by explaining pairing.

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

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

Explicitly states when to use: when record is too big for prompt. Suggests pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's minimal addition is acceptable. However, it adds no context about what happens on missing orders, authentication failures, or rate limits, which would be beneficial beyond the annotations.

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

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

The description is a single, concise sentence that is front-loaded with all essential information. There is no waste; every word contributes to understanding the tool's core function.

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

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

For a simple read-retrieval tool with complete input schema and an existing output schema, the description adequately covers the essential purpose. It could hint at response details but is sufficient given the supporting schemas.

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

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

Schema coverage is 100% with each parameter described clearly. The description adds no extra parameter meaning beyond what is already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the action (Get), resource (single order), identifier (by ID), and source (from a Shopify store). It is specific and unambiguous, but does not explicitly differentiate from sibling tools like shopify_list_orders, though the mention of 'single' implicitly does so.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, no when-not-to-use indications, and no mention of alternative tools. It only implies usage when an order ID is known, but lacks any decision framework.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context (e.g., authentication, rate limits, or error behavior). It neither contradicts nor significantly supplements 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?

A single, clear sentence that is front-loaded and contains no unnecessary words.

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

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

Given the existence of an output schema and the simple nature of the tool (single product retrieval by ID), the description is adequate. It could mention error handling (e.g., product not found) but is otherwise sufficient.

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

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

The input schema has 100% coverage, describing all three parameters. The description does not add extra meaning beyond the schema's parameter 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 verb 'Get', the resource 'single product by ID', and the source 'from a Shopify store'. It distinguishes well from sibling tools like shopify_list_products or shopify_get_order.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. Usage is implied for fetching a single product by ID, but alternatives (e.g., listing products) are not discussed.

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, so the basic behavioral profile is clear. The description adds no extra behavioral context (e.g., rate limits, pagination details), but does not contradict annotations.

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

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

The description is a single, efficient sentence with no wasted words. It is appropriately front-loaded and 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?

The tool is simple and has an output schema, so the description need not detail return values. However, it omits useful context like default/max limit (though in schema), and lacks any usage notes. It is minimally adequate but not enriched beyond structured fields.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add any meaning beyond what is in the schema, meeting the baseline expectation.

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

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

The description clearly states the tool lists customers from a Shopify store, which is a specific verb+resource combination. It distinguishes from sibling tools like shopify_list_products and shopify_list_orders.

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

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

No guidance is provided on when to use this tool versus alternatives, such as when to list customers versus orders or products. There is no mention of prerequisites or contexts that would make this tool preferable.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds no additional behavioral context (e.g., pagination, rate limits, ordering).

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

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

Single concise sentence that is front-loaded with core purpose. No unnecessary words.

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

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

Output schema exists, so return value details are not needed. However, description lacks context on ordering, pagination, or default sort behavior, which would help agent decide suitability.

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

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

Schema has 100% coverage; all parameters are described. Description mentions optional status filter but adds no meaning beyond schema defaults.

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

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

Description states 'List orders from a Shopify store' with specific verb and resource, and optional status filter. Clearly distinguishes from sibling tools like shopify_get_order and shopify_list_products.

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

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

No guidance on when to use this tool versus alternatives. Does not mention when to use shopify_get_order for a single order or when filtering is insufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which provide safety and idempotency info. The description adds the pagination limit (up to 50 by default), which is 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?

Two sentences, front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

Given the existence of an output schema and rich annotations, the description is fairly complete. It covers the main purpose and default limit, though it could mention pagination cursor or rate limits.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds minimal extra meaning (default limit), but the baseline is 3 due to high coverage.

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

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

The description uses the specific verb 'List' and resource 'products' from a Shopify store. It clearly distinguishes from sibling tools like shopify_get_product (single product) and shopify_list_orders/customers (different resources).

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

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

No guidance on when to use this tool vs alternatives. It omits context such as when to use list vs get, or how pagination works beyond the default limit.

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

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

Annotations indicate non-read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: OAuth requirement, type-specific parameters, delivery channel limits (SMS 10/day cap), webhook auto-disable after 10 failures, and that webhook secret is returned only once. No contradictions with annotations.

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

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

The description is a single paragraph that is front-loaded with the main purpose, then covers details. It is efficient with no fluff, but could benefit from more structured formatting (e.g., bullet points) for clarity. 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 3 parameters, full schema coverage, no output schema, and moderate complexity, the description thoroughly covers creation: supported types, parameters, delivery options, constraints, and prerequisites. No gaps identified.

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

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

Schema coverage is 100% with descriptions, but the tool description adds valuable examples and explanations for each parameter (e.g., 'sec_8k' items codes, 'fred_series' series_id, delivery channel details). This enriches understanding beyond the schema alone.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides clear context on when to use (to create subscriptions), prerequisites (Pipeworx OAuth account), and details on supported types and delivery channels. It does not explicitly state when not to use or mention alternatives, but the sibling tools imply differentiation.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it returns example questions drawn from a live catalog and can be called without arguments or with a topic.

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

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

The description is a single paragraph that front-loads common user queries and then explains the tool's output and usage. It is reasonably concise with no wasted sentences, though it could be slightly more compact.

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 one optional parameter, no output schema, and clear annotations, the description provides complete context: what it returns, when to use it, how to use the parameter, and that examples come from a live catalog. 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%, so baseline is 3. The description adds meaning by explaining the effect of omitting the topic argument vs. passing specific values like 'finance' or 'pharma', and lists example topics.

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 category-bucketed example questions and serves as the onboarding entry point. However, it does not explicitly differentiate from sibling tool 'discover_tools', which may have similar functionality.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. This sets clear context for usage, though it does not specify when not to use it or mention 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?

Adds behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability. Aligns with idempotentHint and destructiveHint, providing valuable context.

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

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

Three concise sentences: core action, ownership constraint, and behavioral side effect. Front-loaded with essential information, 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 low complexity (1 param, simple action), the description fully covers purpose, ownership, and side effects. References sibling 'recent_alerts' for integration clarity.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3. Description adds no extra meaning beyond what the schema's description already provides ('Subscription id (uuid) returned by subscribe').

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 specifies verb 'Cancel' and resource 'subscription by id', clearly stating the action. It distinguishes from siblings like 'subscribe' (opposite) and 'list_subscriptions' by mentioning deactivation and referencing 'recent_alerts'.

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

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

Provides clear context: ownership enforcement and deactivation behavior. Implicitly guides usage as the counterpart to 'subscribe', but lacks explicit when-not or alternative tool recommendations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the data source (SEC EDGAR + XBRL), the return verdict types, and the structured output format, which goes 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 detailed but front-loaded with example queries and purpose. While it could be slightly shorter, it remains well-structured and informative without redundancy.

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

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

Given only one parameter and no output schema, the description fully explains input, process, output, and limitations. It covers scope, return format, and use case, making it complete for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100% (claim parameter described). The description adds natural-language examples and usage context, enhancing the schema's explanation without repeating 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?

The description uses specific verbs ('verify', 'fact check') and clearly states the resource ('natural-language claim verification against authoritative sources'). It distinguishes from siblings by mentioning it replaces multiple sequential calls, and explicitly limits scope to company-financial claims via SEC EDGAR + XBRL.

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.' It provides context but does not explicitly exclude use cases or mention alternatives beyond the scope limitation. However, the scope is clearly defined, and the sibling list implies appropriate use.

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