Seo Ai Visibility

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

Annotations already declare read-only, idempotent, open world. Description adds value by detailing cost model (BYO key for Anthropic, free default), return structure (per-model fields + combined view), and probing behavior. No contradictions.

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

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

Three sentences, front-loaded with purpose. No redundant words. Each sentence adds distinct information: action, options, output, and use cases.

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

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

Despite no output schema, description fully explains return format (per-model fields + combined view). Use cases and parameter purposes are covered. With 4 documented params, 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. Description adds context: default model, _apiKey purpose, and context disambiguation. It connects parameters to usage scenarios, providing added value over 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 action: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the verb (probe, score), resource (LLMs), and output format. This distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on individual entity visibility.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also describes when to pass _apiKey (to probe Anthropic) and default model usage. Lacks explicit when-not-to-use or alternatives among siblings, but the context is clear.

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

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

Annotations already declare read-only, non-destructive, open-world, idempotent properties. The description adds useful context beyond annotations: it routes to 5,407 tools, fills arguments, returns structured answers with citation URIs, works on every tier, and is a fast single call. It does not contradict annotations. A small gap is the lack of detail about the response structure or potential failure modes, but the annotated safety profile reduces the need.

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 dense and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). Each sentence adds value: coverage list, routing, trigger phrases, examples, and escalation paths. It could be slightly more structured with bullets, but it remains scannable and efficient for its complexity.

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

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

Given the high complexity (a meta-router over 5,407 tools) and no output schema, the description provides a solid overview: what it does, when to use it, examples, and alternatives. It lacks detailed output structure or error handling, but enough is provided for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: every parameter is an alias for 'question' and is fully described in the schema. The description adds usage context (what kinds of questions to ask) but no additional parameter-level semantics beyond what the schema already provides. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,407 tools across 1403 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses specific verbs (routes, fills, returns) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and gives clear when-to-use alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions. This is exemplary usage guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: that it is the experimental edge, that candidate routing improvements are enabled live during tests, that currently no candidate is active so it behaves exactly like ask_pipeworx, and that it is a full working router with no fallback. This goes beyond the annotations and informs the user of potential variability and the purpose of using it.

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

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

The description is four sentences, each with a distinct role: defining the beta nature, stating the current state, giving usage guidance, and confirming it is a full router. It is efficiently front-loaded with the core identity and contains no fluff. Slightly verbose but every sentence carries necessary information.

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

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

For a router tool with a simple question input, the description is complete. It explains the relationship to ask_pipeworx, the experimental behavior, the current inactive state, and the fact that it works as a full router. With good annotations and a fully documented schema, there is no missing critical information.

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

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

The schema already provides 100% coverage, describing all parameters as aliases for 'question.' The description does not add anything about parameter semantics beyond stating it has the same arguments as ask_pipeworx. Since the schema already documents each parameter fully, the description adds minimal value here, so baseline 3 applies.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It distinguishes itself from the sibling ask_pipeworx by being the experimental edge, and from ask_pipeworx_grounded by implication. The verb 'ask' is implicit through the reference to ask_pipeworx, giving the tool a clear purpose.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current inactive state and the comparison against the stable router, which clarifies when to choose this tool over the stable ask_pipeworx. It does not explicitly mention ask_pipeworx_grounded or other alternatives, but the core 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?

Beyond annotations (readOnlyHint=true, etc.), the description discloses significant behavioral traits: it costs one extra LLM call, returns explicit refusal reasons like 'not_in_source' and 'data_truncated', and guarantees evidence verbatim quotes. No contradiction with annotations; adds substantial 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?

The description is dense but well-structured: definition, routing, extraction mechanism, return shape, refusal behavior, use cases, and cost trade-off. Every sentence contributes, though it is longer than strictly necessary. The front-loading of the core purpose 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?

For a tool with 30 siblings and no output schema, the description is exceptionally complete: it explains the return payload, refusal reasons, the extra LLM call cost, and the exact scenarios where this mode should be invoked. Nothing is left ambiguous.

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 all parameters are aliases for the same question concept. The description does not add parameter-specific meaning beyond confirming natural language question input, but the schema already fully documents them. 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 this is a 'hallucination-resistant answer mode' distinct from its sibling ask_pipeworx, with a specific verb (answer) and explicit scope (extracts answers only from tool results). It distinguishes itself from ask_pipeworx by name and by adding grounding/evidence.

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 ('Use whenever an answer will be quoted, cited, or acted on...'), specific high-stakes domains (financial verdicts, legal claims, medical lookups), and when-not-to-use ('prefer ask_pipeworx for casual lookups'). This is textbook usage guidance.

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

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

The description far exceeds annotation hints by detailing response shapes (best_bid/best_ask/spread_pp), resolver contract (market_match_confidence, alternatives, suggestions), parent_event extractor, news fallback fields, safety short-circuits, closed market handling, wide-spread tradeability warnings, and resolution-rule risk. 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 comprehensive but extremely verbose (multiple paragraphs with extensive examples and edge cases). While front-loaded with the main function, the length may overwhelm an AI agent. Some redundancy exists in listing classifiers and fan-out examples. A more streamlined version could improve clarity.

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

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

The description fully covers the tool's complexity: classifiers, fan-out specifics, response shapes, resolver contract with confidence levels, parent_event extraction, news fields with fallback, safety mechanisms, closed/wide-spread markets, and resolution-rule risk. No output schema exists, but the description compensates with detailed response shape information.

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

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

Schema coverage is 100% with parameter descriptions. The description adds valuable context beyond schema: explains market parameter accepts slug/URL/question, depth defaults to thorough, and include_raw offers summarized vs full payloads. This enhances understanding without redundancy.

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 researches a Polymarket bet by pulling relevant Pipeworx data. It specifies the verb 'research' and the resource 'Polymarket bet', and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by detailing its unique fan-out and data-pack 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?

The description provides explicit usage examples like 'should I bet on X' and 'what does the data say about Y', and includes classifiers, fan-out examples, and special case behaviors. However, it lacks explicit 'when not to use' guidance, though the context sufficiently differentiates from siblings.

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

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

Description discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), metrics returned (revenue, net income, etc.), handling of off-calendar fiscal years, and sorting behavior. Annotations already indicate readOnly, openWorld, and idempotent, and description adds substantial context beyond annotations.

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

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

Description is well-structured with trigger examples first, then functional explanation. Every sentence adds value; no fluff. It is concise yet highly 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?

Description covers all aspects: when to use, how it works, data sources, return format (paired data + citation URIs). Despite lacking output schema, the description sufficiently explains what to expect. Annotations provide safety profile.

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

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

Schema coverage is 100%, but description adds significant value by explaining what each enum value ('company' vs 'drug') does and gives examples for 'values' parameter (tickers/CIKs for company, names for drug). It clarifies entity-specific constraints like max 5 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 the tool performs side-by-side comparisons of 2–5 companies or drugs. It provides trigger phrases ('compare X and Y', 'vs', 'head to head') and distinguishes itself from sequential single-pack lookups.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It mentions when-not-to-use (sequential lookups) and provides context for when to use (comparison queries).

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

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

The description goes well beyond annotations, disclosing account requirements, pricing for 'thorough' depth, the parallel decomposition behavior, return packet structure (verbatim evidence, confidence, source, fetched_at), gaps[] behavior, no invention guarantee, second-hop iteration, contradictions[], semantic excerpting, and latency expectations. Annotations are consistent; 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 lengthy but every sentence adds distinct value, covering purpose, usage, behavior, and edge cases. It is front-loaded with the account requirement and main differentiators. It could be trimmed slightly, but for a complex tool, the detail is justified.

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

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

With no output schema, the description compensates fully by detailing the findings packet, citations, gaps[], contradictions[], hop field, and return behaviors. It also covers failure modes (empty gaps[] for non-catalog topics) and latency, making it contextually complete for agent decision-making.

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

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

Schema coverage is 100%, with detailed descriptions for both question and depth parameters. The description adds some context (e.g., paid plan for thorough, time expectations) but mostly restates what the schema already documents. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states that deep_research performs grounded multi-source research across 1,403 structured data sources, decomposing questions into facets and routing to 5,407 tools in parallel. It explicitly distinguishes from ask_pipeworx, making it immediately clear what the tool does and how it differs from 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?

Usage guidance is explicit: use ask_pipeworx for single lookups, for breaking or colloquial current-news topics, or when not signed in; use deep_research for broad/multi-part questions over structured data. This clearly defines when to use the tool versus alternatives, including specific exclusions.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds that results come with full input schemas and are 'ready to call directly, no second schema lookup needed,' aligning with annotations. More detail on result ordering or caching would improve transparency.

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, front-loaded with purpose, and every sentence adds value. No redundancy or fluff; efficient communication in 4-5 sentences.

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

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

No output schema, but description explains the return format (top-N with names, descriptions, schemas). Adequately covers usage and expectations for a discovery tool with 6 parameters, though lacks details on error handling or pagination.

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 all parameters are described. The description does not add meaning beyond listing aliases briefly, but the high schema coverage justifies baseline 3.

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

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

The description uses specific verbs 'Find tools' and lists concrete domains (SEC filings, FDA drugs, etc.), clearly distinguishing this tool from siblings like 'search_within' or 'deep_research' which operate on data rather than tool discovery.

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

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

Explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and contextual guidance, though it does not name specific alternatives.

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

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

The description provides detailed behavioral traits beyond annotations, including data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific fields returned, and limitations (patent soft-fail due to API sunset). Annotations already declare readOnlyHint, openWorldHint, etc., 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?

The description is front-loaded with example queries, but it is somewhat long due to listing all return fields. Given the tool complexity and lack of output schema, the length is justified, but could be slightly more concise.

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

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

With no output schema, the description fully explains return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. It also covers limitations and fallbacks. For a 2-param tool, 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%, so baseline is 3. The description adds meaning by explaining the 'type' parameter only accepts 'company' and expects ticker or zero-padded CIK for 'value', including examples and noting that names are not supported. 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 provides a full cross-source profile of a US public company, with example queries like 'tell me about X' or 'company profile for Microsoft'. It distinguishes itself by recommending over chaining individual lookups, and specifies that names are not supported, so use resolve_entity first.

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

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

The description explicitly says when to use this tool: for holistic company profiles, and when not to: if you only have a name, use resolve_entity first. It also contrasts with chaining single-pack lookups, making 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 destructiveHint=true and idempotentHint=true. The description aligns and adds context about the operation being on previously stored memory, but does not elaborate on irreversibility or side effects beyond what annotations convey.

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

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

Two succinct sentences with no wasted words; the action and usage are front-loaded.

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

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

For a simple delete operation with one parameter, the description covers purpose, usage, and required information. No output schema is needed, and annotations adequately cover safety.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' is clear. The tool description does not provide additional details about the key format or examples beyond the schema.

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

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

The description explicitly states the action ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall'.

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, setting a safe behavioral baseline. The description adds valuable detail: it fetches the page, extracts title/description/key links, and emits standard markdown. 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 with no wasted words. The main purpose is stated first, followed by the process and then use cases. Every sentence earns its place.

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

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

Despite no output schema, the description states the output is a single text blob. It covers purpose, inputs, output format, and use cases. Could mention error handling or idempotency, but annotations cover safety.

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

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

Schema coverage is 100% with both parameters described. The description adds the default value for max_links (25) beyond the schema's max constraint, and clarifies that the tool fetches the page, adding context to the url parameter.

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 generates a production-ready llms.txt file for any URL. It specifies the verb 'Generate' and the resource 'llms.txt file', and distinguishes itself from siblings by focusing on the specific llms.txt standard format.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing a competitor. It does not explicitly state when not to use or compare to alternatives, but the context is clear enough for an AI agent to select appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds detail about the default behavior (active subscriptions only) and return format, complementing the 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?

Two concise sentences: first states purpose and return fields, second gives usage context. No wasted words.

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

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

For a simple read-only list tool with one optional parameter, the description is sufficient. It lists all return fields and describes the default filter. No output schema is needed, and no gaps are critical.

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

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

The one parameter (include_inactive) is fully described in the schema (100% coverage). The description implies its effect via 'active' vs. including inactive, but adds no substantial new information beyond the schema.

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

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

The description clearly states the tool lists active subscriptions, specifies the returned fields (id, type, params, etc.), and differentiates from sibling tools 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?

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide when to call this tool versus subscribe/unsubscribe.

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

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

The description fully discloses behavioral traits beyond annotations: it is rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also explains how the feedback is used (team reads daily, affects roadmap). No contradictions 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?

The description is a single paragraph of five sentences, each adding value. It front-loads the purpose and provides usage guidelines, behavioral notes, and constraints. While efficient, it could be slightly more terse, but overall it is well-structured and easy to parse.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is complete. It covers purpose, usage, behavior, rate limits, and content instructions. No additional information is needed for an agent to correctly select and invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds valuable context: for the 'message' parameter, it advises to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts. This enhances understanding beyond the structured schema.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, missing features, or praise to the Pipeworx team. It specifies the verb 'Tell' and the resource 'Pipeworx team,' and the categories (bug, feature, etc.) are distinct from sibling tools, which are primarily for querying or discovering information.

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 cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives formatting instructions and notes rate limits, making the usage context very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: self-aggregating signal, derived from CF analytics-engine, no PII, cached 5min-1h. 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 concise (3 sentences) with clear structure: what it returns, then use cases. Every sentence adds value with no redundancy.

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

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

For a tool with no output schema, the description could be more explicit about the return format (e.g., 'returns a JSON object with arrays of tools and packs'). However, the description is sufficient for an AI agent to understand the general output, and the tool is simple enough that this is a minor gap.

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

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

Schema coverage is 100% and the description explains the window parameter beyond the schema enum: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds significant meaning.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' for a given time window, using a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'). It distinguishes from siblings by focusing on trending data rather than listing all tools (e.g., discover_tools).

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, seeing alignment), which helps the agent decide when to use this tool. However, it does not explicitly mention when NOT to use it or suggest alternatives, though the context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds crucial behavioral details: fill check against live CLOB depth, semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs), and warning not to trade when realizable_edge_pp ≤ 0.

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, but it is relatively long. Every sentence adds value, but some agents might prefer a more concise overview.

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?

All aspects are covered: modes, parameters, technical checks (monotonicity, partition sum, fill check, semantic anchor, partition filter), and response structure. No output schema, but the description explains the response fields and references sibling tool for custom sizing.

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

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

Schema covers 100% of parameters. The description adds semantics: event slug format (including full URLs accepted), topic as a seed question, and recommendation to use event for specific markets.

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 three modes (trending_scan, event, topic) with specific use cases and examples.

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

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

Explicit guidance is given for when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Examples of arguments are provided, though it 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?

The description fully discloses behavioral traits: read-only (consistent with annotations), caching (1h), model families, diagnostic outputs, and why Fed bets are excluded. No contradictions with annotations.

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

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

The description is well-structured with segments and front-loaded purpose, but it is overly verbose with detailed model formulations and diagnostics. It could be more concise while retaining essential guidance.

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

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

Given 9 parameters and no output schema, the description is highly complete: it explains all three segments, knobs, diagnostics, caching, and exclusions. The agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds value by explaining interactions (e.g., min_partition_leg_kelly vs min_kelly) and providing usage tips, but some details (e.g., exact formulas) could be omitted.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific purpose ('what should I bet on today'). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage opportunities.

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

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

The description explicitly states the tool is built for discovering opportunities without paging hundreds of markets, and provides guidance on knob usage (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already provide safety hints (readOnly, idempotent, etc.). The description adds behavioral context: decay numbers from daily closes, not intraday; snapshots written on cache-miss causing gaps. 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 front-loaded with the key insight and is well-structured with ARGS, RESPONSE, and LIMITS sections. It is dense but every sentence adds value. Slightly verbose but not excessively so.

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 the response structure (tracked, expired, snapshot_dates with field meanings). It covers response fields like trend, decay_pp_per_day, and median lifespan. Complete for its complexity.

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

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

Schema coverage is 100%, and the description adds value beyond the schema: explains days (lookback, default 14, clamp 2-30), window (default '1wk', meaning snapshot family). The description makes the parameters' semantics fully clear.

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: providing edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes from siblings like polymarket_edges by focusing on time-series analysis.

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

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

The description includes context on when to use (comparing fresh vs. old edges) and limitations (60-day TTL, snapshot gaps). While it doesn't explicitly state alternatives, the sibling polymarket_edges implies a distinction. The usage guidance is clear but could be more explicit about when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, indicating no side effects. The description adds important behavioral details: it walks the ladder, returns slippage, verdicts (clean|degraded|cannot_fill), and forced_directional_risk. It warns that partial basket fills convert arb into unhedged directional position. No contradiction with annotations. Slightly more detail on output structure could push to 5, but current content is strong.

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 with headings (SINGLE-MARKET, BASKET) and clear sections. Every sentence provides necessary information—no redundancy. It is front-loaded with the core purpose. Could be slightly more concise, but the complexity of the tool justifies the length.

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

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

Given the tool's complexity (two modes, 4 params, no output schema), the description is thorough. It covers both modes completely, explains return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc.), and addresses risks and edge cases (thin_legs, forced_directional_risk). Without an output schema, the description fully compensates by detailing what the tool returns.

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

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

Schema description coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the two modes (single-market vs basket), how `size_usd` is interpreted differently (max spend vs target proceeds vs settlement notional), and the default `side` logic for baskets. This clarifies the semantic differences between parameters, going beyond the schema's basic type/description.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' in both single-market and basket modes. It distinguishes itself from sibling tools like `polymarket_arbitrage` and `polymarket_edges` by being a pre-trade risk check. The verb 'check' and specific resource 'order-book depth' make the purpose precise.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround on thin books, and warns about partial basket fills. This provides clear when-to-use and when-not-to-use guidance with sibling tool 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?

The description adds significant behavioral context beyond the annotations: it details safety fields (compatibility_warning, temporal_alignment), explains skipped cross types, and notes when spreads are meaningless. It does not contradict any annotations.

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

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

The description is structured and front-loaded with purpose, but is somewhat lengthy. However, every sentence provides useful information, so it earns its length without being excessively verbose.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response fields, safety warnings, and edge cases. It fully compensates for the missing output schema and provides all necessary information for correct 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?

Although schema coverage is 100%, the description adds substantial meaning by explaining the two modes, that topic auto-fetches events, and how explicit parameters override the topic side. It also provides examples, aiding the agent in correct parameter selection.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on 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?

The description explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics are not tradeable. It provides context on when to use it and how to interpret results, but does not explicitly mention when not to use it 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating no side effects. The description adds critical behavioral details: scoping to user identifier (IP, key hash, or account ID) and the dual-mode operation (retrieve by key or list all keys). 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 four sentences long, each providing essential information. It starts with the primary action ('Retrieve a value...'), then gives use cases, scoping, and pairing with sibling tools. No redundant or irrelevant information.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the core behavior, scoping, and relationship to sibling tools. It implicitly handles the two main use cases (retrieve by key, list all keys). The description is sufficient for an agent to invoke the tool correctly.

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

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

The input schema has 100% coverage for the single 'key' parameter. The description adds meaning beyond the schema: it explains that omitting the key lists all saved keys, and that the key is a string for looking up stored values. This provides clear usage guidance for the parameter.

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: retrieve a value saved via 'remember' or list all saved keys if no key is provided. It distinguishes itself from sibling tools 'remember' (save) and 'forget' (delete) by explicitly pairing with them. The verb 'retrieve' and resource 'memory' are specific.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier' (e.g., target ticker, address, research notes). It mentions pairing with 'remember' and 'forget' but does not explicitly state when not to use it or provide alternatives beyond those siblings. The context is clear for typical use cases.

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, idempotent=true, and destructiveHint=false, establishing a safe, non-mutating profile. The description adds valuable behavioral context: the mark_read parameter for updating read status, the return structure (carries source, citation_uri, payload), and the persistence of the feed across calls. It 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 concise (3 sentences), front-loaded with the main action, and every sentence adds value. The first sentence states the purpose, the second details return fields and filtering, and the third explains polling behavior and an alternative access method. No wasted words.

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

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

Given the lack of output schema, the description sufficiently explains the return structure (source, citation_uri, raw payload). All five parameters are covered in the description or schema. The tool is simple (read-only, filtered list retrieval), and the description covers usage context, behavior, and return format 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%, so the schema documents all parameters. The description enriches understanding: it explains mark_read's effect on subsequent calls, gives a concrete filter type example ('sec_8k'), and clarifies that 'since' expects an ISO timestamp. This adds meaningful context beyond the schema definitions.

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 a specific verb and resource ('Pull fired events from your subscription feed'), clearly stating the tool's purpose. It differentiates itself from siblings like 'list_subscriptions' and 'subscribe' by focusing on retrieving alert events. The purpose is unmistakable.

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

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

The description explains when to use the tool ('Polls work fine') and provides an alternative access method (direct feed URL). It also specifies filtering options. However, it does not explicitly mention when not to use it or compare with other tools (e.g., 'search_within' or 'recent_changes'), so it's slightly less than perfect.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false; description adds behavior details: soft-fails for USPTO, fallback to GNews, structured return with groups and count, and citation URIs. No contradiction with annotations.

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

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

Description is dense but front-loaded with example queries. Every sentence adds value, though it could be slightly more structured for readability. Still efficient and informative.

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

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

Given complexity (3 data sources, fallback logic, relative date support, no output schema), description covers return structure (grouped changes, total count, URIs), error handling (soft-fail), and alternative tool. Complete and self-contained.

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%. Description adds meaningful examples: 'since' accepts ISO or relative with typical values ('30d', '1m'), 'type' restricted to 'company', 'value' can be ticker or CIK. Enhances schema with practical usage guidance.

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

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

Description uses specific verbs and resources: 'change feed for a company', fans out to SEC EDGAR, GDELT/GNews, USPTO. Explicitly distinguishes from sibling 'entity_profile' which provides static profile.

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

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

Provides explicit example queries (e.g., 'What's new with X', 'latest on Y'), gives contextual guidance on when to use alternative ('Use entity_profile instead when you want the static profile'), and mentions fallback behavior for news sources.

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 note idempotence, non-destructiveness. Description adds beyond: storage mechanism (key-value), scoping by identifier, persistence differences (auth vs anonymous). Describes pairing with recall/forget for full lifecycle. Minor omission: doesn't mention overwrite behavior, but still adds value.

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 concise (4 sentences) and front-loaded with purpose. Every sentence adds value without redundancy. Efficient structure for quick understanding.

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 2-parameter tool with no output schema, the description covers purpose, usage, pairing, and persistence. Lacks mention of return value or error handling, but given simplicity and annotations, it's nearly complete.

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

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

Schema coverage is 100% with clear parameter descriptions. Description reinforces meaning by providing context (e.g., examples in schema) but doesn't add significant new semantics beyond the schema. Baseline 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 identifies the verb (save/remember) and resource (data for reuse). It distinguishes from siblings like recall and forget by explicitly mentioning pairing, making the tool's purpose unambiguous.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward'. Mentions context of persistence and scoping, and directs to recall/forget for related operations, offering clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description complements this by revealing that each call 'cascades through several lookup endpoints internally' and that it replaces 2-3 manual lookups. It also mentions the citation URIs returned, adding behavioral detail 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 tightly written with no wasted words. It begins with relatable examples, then defines the core use, then lists supported types in structured bullet-like format. Every sentence adds value, and the length is appropriate for the complexity.

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

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

Given the tool has only 2 simple parameters, no output schema, and thorough annotations, the description provides a near-complete picture. It explains inputs, outputs per type, and usage context. Minor omission: no mention of error handling or disambiguation when input is ambiguous (e.g., multiple companies with same name).

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 substantial meaning: for the 'value' parameter, it explains accepted formats (ticker, CIK, or name for company; brand or generic for drug) and indicates the return structure (e.g., ticker + 10-digit CIK + company_name + citation URI). This goes well 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 opens with concrete examples ('What's the ticker for...') and clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It lists supported entity types (company, drug) and distinguishes itself from sibling tools like entity_profile by focusing on ID resolution.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID.' It explains that other tools require the returned IDs, making the usage context clear. However, it does not explicitly state when NOT to use this tool (e.g., for information lookup beyond identifiers) or list alternative tools for that purpose.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized, which is beyond what annotations provide.

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

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

Three sentences with zero waste. Front-loaded with the core purpose, then expands on usage and output. Each sentence earns its place.

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

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

Given no output schema, the description adequately explains the return value (ranked list with score, confidence, signal density). All 4 parameters are covered, and the required parameter (entities) is explained with constraints (2-8). Complete for the tool's complexity.

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

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

Schema coverage is 100% with baseline descriptions. The description adds meaning by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors, and that context disambiguates common names. This adds value beyond the schema.

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

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

The description uses a specific verb ('Compare AI visibility') and resource ('multiple entities side-by-side'), and clearly distinguishes from the sibling ai_visibility_check (single entity) by stating it probes multiple entities and ranks them.

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

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

Provides a clear use case ('competitive AI-marketing audits') and an example question. Does not explicitly state when not to use or list alternatives, but the context of comparing multiple entities inherently implies when to use over single-entity tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: partial failures, bundlephobia first measurement can take 5-30s, sources_failed list on timeout. 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?

Six sentences packed with information, no fluff. Front-loaded with the core purpose. Every sentence earns its place.

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

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

Despite no output schema, description thoroughly details return values (summary block fields, per-advisory, links, alternative versions), limitations, and failure modes. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so schema already documents both parameters. Description adds nuance: defaults to latest version when omitted, accepts scoped packages. Adds value but schema does heavy lifting.

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

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

Description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia, and answers questions like 'is X safe/popular/small'. Distinguishes from siblings by specifying NPM ecosystem and mentioning other ecosystems are covered by deps.dev directly.

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

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

Explicitly says when to use: 'whenever an agent asks ...' and notes NPM only in v1, with alternatives listed (deps.dev:version for other ecosystems). Provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these: it uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', mentions the character cap and truncation behavior, and explains that every passage carries an offset for verification. 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 a single paragraph but is well-organized: first sentence states the core function, second gives usage guidance, third provides technical details. Every sentence adds value. It could be slightly more concise (e.g., 'Pairs with ask_pipeworx_grounded' sentence is a bit long), but overall it is efficient and front-loaded. 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?

The tool has no output schema, but the description explains the return format (top-N passages with character offsets and similarity scores), which is sufficient for an agent to understand what to expect. Given the tool's complexity (embeddings, windowing, truncation) and the rich annotations, the description covers all key aspects: usage context, input constraints, and output structure. It pairs well with sibling tools, especially 'ask_pipeworx_grounded', providing a complete picture.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds useful context: provides example queries for the 'query' parameter (e.g., 'supply-chain risk', 'fiscal year 2024 revenue'), mentions the default and range for 'limit' (1-20, default 5), and reiterates the max length for 'text'. While this adds some value beyond the schema, it does not significantly deepen understanding beyond what the schema already provides. Baseline 3, plus 1 for the 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 function: semantic search inside a fetched record. It specifies the inputs (text and natural-language query) and outputs (top-N passages with character offsets and similarity scores). It also distinguishes from the sibling tool 'ask_pipeworx_grounded' by explaining how they pair together.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Also gives a constraint: 'cap is 200K chars (longer inputs are truncated and flagged)', which helps an agent decide if the tool is appropriate.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by stating the tool returns 'answer plus any cited sources/links,' which is not covered by annotations. No contradictions 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 a single sentence with an inline example, immediately conveying the core purpose. It is concise, front-loaded, and contains no extraneous information. Every part earns its place.

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

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

The tool has no output schema, so the description should clarify the return format. It only vaguely states 'returns its answer plus any cited sources/links,' without specifying whether the output is JSON or text. Error handling or rate limits are not mentioned. The description is minimally adequate.

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

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

Schema description coverage is 100%, with each parameter described. The description includes an example call showing parameters in context, which adds practical meaning beyond the schema. This justifies a score above the baseline of 3.

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

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

The description clearly states the tool queries an LLM with a prompt and returns the answer and cited sources for AI-visibility analysis. It specifies the verb 'runs' and the resource 'prompt through an LLM,' effectively distinguishing it from sibling tools like 'ai_visibility_check' which may serve a different purpose.

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

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

The description mentions the tool is 'for AI-visibility (GEO) analysis' and provides an example, but it does not explicitly state when to use this tool over siblings such as 'scan_competitor_ai_presence' or 'search_within.' No when-not-to-use guidance is provided.

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

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

Adds significant behavioral details beyond annotations: requires OAuth, returns subscription ID, phone verification for SMS, 10/day SMS cap, webhook auto-disable after 10 failures, and webhook signing secret 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?

Well-structured and front-loaded with the primary purpose. While dense, every sentence provides value; minor room for brevity due to extensive examples.

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

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

Covers all aspects: return value, prerequisites, type-specific parameters, delivery options with constraints, and edge cases (phone verification, caps, auto-disable). No output schema exists, but description adequately explains what is returned.

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?

Enriches schema with concrete examples for each subscription type (e.g., sec_8k items mapping to officer changes) and detailed delivery parameter behavior (webhook signing, auto-disable). Schema coverage is 100% and description adds meaning beyond the schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription ID. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context on prerequisites (requires Pipeworx OAuth account, not available for anonymous or BYO users), supported types, and delivery channels. However, it does not explicitly contrast with alternatives like when to use subscribe vs list_subscriptions.

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, destructiveHint=false. The description adds value by explaining the return format (category-bucketed example questions with tool+argument shape) and that the tool is an onboarding entry point. 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 moderately long but well-structured, front-loading the core purpose and usage. Every sentence adds value, though it could be slightly more concise. The use of em-dashes and parentheses helps readability.

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

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

Given no output schema, the description provides a thorough picture of what the tool returns (category-bucketed example questions with tool shapes drawn from live catalog). It covers all key aspects: purpose, invocation, output, and when to use. No gaps.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing valid topic values (finance, pharma, etc.) and explaining the behavior difference between providing a topic or omitting it. This goes beyond the schema's minimal description.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by explicitly recommending its use first when the agent doesn't know what Pipeworx can do.

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

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

The description gives explicit when-to-use advice: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also covers invocation details: 'Call with no arguments for the full spread, or pass topic to focus'.

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

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

Annotations provide non-readOnly, idempotent, non-destructive hints. Description adds valuable context: the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. 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?

Three sentences, each essential: action, ownership constraint, effect on data. 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 single parameter, no output schema, and annotations, the description covers ownership, side effects, and data retention. Complete for this straightforward mutation.

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 (100% coverage) describes 'id' as subscription uuid from subscribe. Description reinforces this by stating 'by id' and linking to subscribe, adding marginal value beyond schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' (opposite) and 'list_subscriptions' (listing).

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing a clear when-to-use condition. Does not explicitly mention alternatives but implies that if not your subscription, another tool might be needed.

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=true, openWorldHint=true, idempotentHint=true. The description adds behavioral context: explains the two processing paths, return values (verdict, value with citation, reasoning), and efficiency benefit (replaces 4-6 calls). No contradictions.

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

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

The description is relatively long but each sentence adds value: use cases, path breakdown, return details, and efficiency claim. It is front-loaded with trigger phrases. Could be slightly more concise but not unnecessarily 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 no output schema, the description adequately covers input types, processing paths, and return structure. It does not specify citation format or multi-claim handling, but overall it is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining the default behavior of tolerance_pct and when to set it, and provides examples for the claim parameter, 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 provides a clear verb ('verify') and resource ('factual claim against authoritative sources'), with example triggers like 'Is it true that…'. It distinguishes between company-financial and other claims, making the purpose specific and well-differentiated 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 states when to use ('whenever the agent needs to check whether something a user said is factually correct'). It explains the two processing paths but does not explicitly mention when not to use or provide alternatives among siblings, though the context is clear.

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