Data Seattle

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

The description fully aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) and adds behavioral details: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also clarifies cost implications for Anthropic and that the default model is free. No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose, then provides key details (default model, optional key, return structure). Every sentence is necessary; no fluff or redundancy.

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

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

Given the tool's complexity (4 parameters, no output schema), the description covers all necessary aspects: input (entity, models, apiKey, context), behavior (probing, scoring), and output (per-model fields + combined). The lack of output schema is compensated by the clear return structure in the description.

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 meaningful context beyond the schema. It explains the default model, the purpose of `_apiKey` (BYO key, direct billing), and the `context` parameter ('helps disambiguate common names'). This adds significant value for correct parameter usage.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe), resource (LLMs), and output (visibility score). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on probing models rather than scanning competitor presence.

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

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

The description provides clear context: 'Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic (BYO key — you pay Anthropic directly for those calls).' It states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use it or list alternatives, but the context is sufficient for typical use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant context: routes to 5,245 tools across 1,369 sources, fills arguments automatically, returns structured answers with citation URIs, and notes it's a single fast call on all tiers. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with the most important guidance (prefer over web search, examples). It is well-structured with clear usage directives and alternative tool references. Some redundancy (e.g., listing many sources) could be trimmed, but it remains 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?

Given the large number of sibling tools (30+) and the tool's role as default entry point, the description fully covers when to use, what to expect (structured answer with citation URIs), and how it compares to alternatives. No output schema exists, but the description adequately explains the return format.

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

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

Schema coverage is 100% with all 6 parameters clearly described as aliases for the question. The description adds example questions and clarifies the expected input format, providing extra value beyond the schema.

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

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

The description clearly states the tool answers factual questions using structured data from many authoritative sources, listing specific domains (SEC filings, FDA data, stocks, etc.) and providing examples. It distinguishes itself from web search and sibling tools effectively.

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 tells when to use this tool (default for most factual questions) and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-source broad queries). Includes example queries and instruction to start here.

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

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

The description discloses that it is a full working router with experimental edge behavior, and explains fallback: 'Falls back to nothing — this IS a full working router, just the experimental edge.' This adds context beyond annotations which already indicate readOnly, openWorld, idempotent, and non-destructive traits.

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 and front-loaded: first sentence defines the tool's identity and relation to ask_pipeworx, then covers current state, usage, and fallback. No unnecessary words; every sentence adds value.

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

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

Given the tool's complexity as a beta router with identical functionality to a stable counterpart, the description provides sufficient context: what it is, current status, usage instructions, and relationship to the stable version. No output schema exists, but the description is complete for its purpose.

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

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

Schema coverage is 100%, with all parameters being aliases for 'question'. The description mentions 'same arguments' but does not add additional meaning beyond what the schema already provides. The high coverage baseline applies, so a 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 tool as the beta version of ask_pipeworx, specifying it is an 'identical universal router' with the same tools, arguments, and response shape. It differentiates from the stable version by mentioning candidate routing improvements.

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

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

The description explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the purpose of comparing results against the stable router and notes that currently no candidate is active, so it matches ask_pipeworx exactly. This provides clear guidance on usage and 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 provide readOnlyHint, idempotentHint, etc. The description adds value by detailing the refusal reasons (not_in_source, no_tool_match, etc.) and the extraction process. 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 core purpose and usage. It is somewhat verbose but every sentence adds value (return format, refusal reasons, cost, use cases). Could be trimmed slightly but still efficient.

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

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

Given the complexity (6 parameters, no output schema), the description fully explains the return structure (answer, evidence, confidence, etc.) and failure modes, making it complete for an agent to understand behavior and expected output.

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

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

Schema description coverage is 100%, so baseline is 3. The description merely restates that 'question' accepts aliases, which is already in the schema. No additional semantic enrichment beyond what the schema provides.

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 a hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'extracts' and the resource 'answer from tool result', and distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call cost.

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 when to use: for answers that will be quoted, cited, or acted on, and where invention is unacceptable (financial, legal, medical, public statements). Also says to prefer 'ask_pipeworx' for casual lookups, providing clear context and 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 goes far beyond the annotations, detailing the fan-out process, resolver contract, parent event extraction, news fallback logic, safety short-circuits for low-confidence and closed markets, and resolution-rule risk. This rich behavioral context helps the agent understand the tool's internal behavior and edge cases, fully compensating for any lack of annotation detail.

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

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

The description is very long and dense, with multiple sections. While well-structured and front-loaded with the core purpose, it could be more concise. Some information (e.g., fan-out examples) is detailed but adds length. For a complex tool, this verbosity is somewhat justified, but it could be trimmed without losing 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 the tool's complexity (3 parameters, no output schema, many behavioral nuances), the description covers all necessary aspects: inputs, process, outputs, edge cases, safety, resolution risk, and how to interpret results. It even explains response shapes and resolver contracts. The description is thorough enough for an agent to use the tool correctly and safely.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the 'market' parameter accepts slug, URL, or question text; the 'depth' parameter defaults to 'thorough'; and the 'include_raw' parameter's effect on response size. These clarifications go beyond the schema's brief descriptions, justifying a 4.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). The specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool ('Use for ...'). It provides guidance on interpreting results (inspect market_match_confidence, check cancellation_rule) and warns about low-confidence matches, closed markets, wide spreads, and resolution-rule risk. However, it does not explicitly mention when not to use it or alternative tools for simpler queries, so it loses a point.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. The description adds substantial behavioral context: explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/ClinicalTrials for drugs), handles off-calendar fiscal years, mentions results sorted by primary metric, and includes pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with common query patterns and is information-dense. Every sentence adds value, covering usage, data sources, return format, and efficiency claim. It could be slightly streamlined (e.g., removing some examples), but overall it's well-structured and not overly verbose 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?

No output schema exists, so the description must explain return format. It does so clearly: 'paired data + pipeworx:// citation URIs per entity.' It covers both entity types, mentions sorting behavior, and implies comparison results. For a tool replacing many sequential lookups, this is rich context.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning: for 'type' it specifies what data each enum value pulls; for 'values' it provides concrete examples (tickers for company, drug names for drug) and enforces min/max items. This goes beyond schema to clarify expected input formats.

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

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

The description begins with concrete user query examples, then states it performs side-by-side comparison of 2–5 companies or drugs. It distinguishes from siblings by explicitly preferring this tool over sequential single-entity lookups, noting it replaces 8–15 calls. The purpose is unmistakably clear.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear guidance on when to use this tool. Example queries like 'which is bigger / better / larger' and 'head to head' further indicate appropriate use cases. No explicit exclusion is needed given the strong preference and clarity.

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

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

The description adds extensive behavioral context beyond annotations: account requirement, non-open-web nature, internal decomposition and parallel routing, exact return fields (verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions), second-hop iteration behavior for different depths, time expectations (15-90s), and semantic excerpting. 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 long but well-structured with clear sections (account requirement, core functionality, best-for, alternatives, second-hop details, output details, performance). It front-loads critical info (account required, alternative). Every sentence adds meaningful detail, though slight trimming could improve conciseness.

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

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

Given the tool's complexity (sibling tools, annotations cover safety, no output schema), the description covers all essential context: prerequisites (account), behavior (decomposition, parallel, hops), output format (explicit fields), edge cases (current news leads to gaps), performance expectations, and differences between depth levels. It is thoroughly 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 provides 100% coverage for 2 parameters. The description adds significant value: for 'depth', it explains what each enum value means in terms of number of facets, hops, and added features (gap recovery, contradictions). For 'question', it clarifies that natural language is expected and broad/multi-part is fine. This goes beyond simple 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 identifies the tool as performing 'grounded multi-source research across Pipeworx's 1369 STRUCTURED data sources' using decomposition and parallel execution. It distinguishes itself from sibling tools like ask_pipeworx by contrasting use cases (broad multi-part queries vs. single lookup).

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

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

The description explicitly states when to use the tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also prerequisites (account required) and 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, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: returns top-N most relevant tools with full input schemas and curated examples, and each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations, though annotations cover safety and idempotency well.

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 three sentences, front-loaded with the primary verb. Every sentence adds value: purpose, when to use, what returns. No waste or redundancy.

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

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

Given no output schema, the description fully explains the return value: top-N relevant tools with names, descriptions, input schemas with examples, ready to call. It also covers usage guidance and examples. All relevant context is provided.

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

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

Schema coverage is 100%, with each parameter described. The description adds examples and explains that multiple aliases (task, q, description, search) are accepted for the query parameter, enhancing usability. While schema handles basics, description provides context and examples, earning above baseline.

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

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

The description uses specific verbs (browse, search, look up, discover) and clearly states the tool's purpose: 'find tools by describing the data or task.' It distinguishes from siblings by being the only tool discovery tool, listing many data domains and explicitly advising to call it 'FIRST' when many tools are available.

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

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

The description explicitly tells when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists specific use cases (SEC filings, financials, etc.) and implies when not to use (when you already know the tool). This provides clear 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?

Discloses parallel fan-out across multiple sources, specific return fields, a known sunset for patents with soft-fail behavior, and fallback mechanisms, adding rich behavioral 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?

Packed with useful details and front-loaded with examples; slightly long but 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?

Very thorough for a complex tool without an output schema, listing all return items, sources, and caveats, making it actionable for an AI agent.

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

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

Schema coverage is 100%, but the description adds context: only 'company' supported for type, and clarifies ticker vs CIK for value, enhancing beyond schema.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies in one parallel call, with explicit query examples and differentiation from chaining individual 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 advises using this tool for holistic views over chaining single-pack lookups, and directs using resolve_entity for names, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds minor context about cleaning sensitive data but doesn't elaborate on irreversibility or error conditions.

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

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

Two sentences, no fluff, purpose first then usage guidance. Extremely concise and well-structured.

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

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

Given the tool's simplicity (1 param, no output schema, annotations present), the description covers purpose, usage context, and pairing with siblings 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 has 100% coverage with a single parameter 'key' described as 'Memory key to delete'. Description does not add extra semantics 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 (Delete), resource (memory), and method (by key). It distinguishes from siblings 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 when-to-use scenarios (stale context, task done, clear sensitive data) and suggests pairing with remember and recall. No explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the internal steps (fetches page, extracts title/description/links, emits markdown) and the output location (site-root/llms.txt). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the main action. While it includes valuable details (use cases, output format), it could be slightly more concise. Overall, every sentence earns its place.

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

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

Given the tool has only two parameters, no output schema, and comprehensive annotations, the description fully covers purpose, process, output format, and use cases. No significant gaps remain for correct invocation.

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

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

Both parameters are documented in the schema with descriptions. The tool description reinforces the url purpose and adds default and max values for max_links (default 25, max 50), which enhances understanding beyond the schema.

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

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

The description clearly states the tool's function: generate a production-ready llms.txt file for any URL. It specifies the output format (standard llms.txt markdown) and lists concrete use cases (getting a client's site indexed, drafting for own project, auditing competitor). This distinguishes it from siblings like ai_visibility_check or deep_research.

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

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

The description provides usage context via 'Useful for:' but does not explicitly state when not to use the tool or compare it to alternatives. However, since no sibling tool performs the same function, the implicit guidance is sufficient for decision-making.

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

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

Annotations already provide readonly, idempotent, and non-destructive hints. Description adds specific return fields (id, type, etc.), which enriches behavioral understanding without contradiction.

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

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

Two efficient sentences, no wasted words. Front-loaded with action and return fields.

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

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

For a simple list operation with well-annotated structure, the description sufficiently covers purpose, return fields, and usage. No output schema, but return fields are explicitly listed.

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 includes a description for 'include_inactive'. Description does not add additional parameter semantics beyond what schema provides, hence a baseline score of 3.

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

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

Description clearly states the verb 'List' and the resource 'the caller's active subscriptions'. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by specifying retrieval and listing of existing subscriptions.

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

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

Explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. No explicit exclusions, but context is clear.

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

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

Annotations set readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: 'Free; doesn't count against your tool-call quota' and 'Rate-limited to 5 per identifier per day.' 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 focused paragraph, front-loaded with the purpose, then usage guidelines, then constraints. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's simplicity (no output schema, few parameters), the description covers purpose, usage, exclusions, rate limits, and quota impact comprehensively. 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 the schema already documents parameters well. The description adds value by explaining the enum values in context (e.g., 'bug = something broke or returned wrong data') and providing guidance on the message field ('Be specific... 1-2 sentences typical, 2000 chars max').

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise), making it easy to distinguish from any sibling tools, none of which serve a similar feedback function.

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

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

Explicitly states when to use: '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).' Also provides a critical negative instruction: 'don't paste the end-user's prompt.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), structure (pack, tool, count), and caching (5min-1h). This exceeds 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?

Description is concise (three sentences plus bullet list) and well-structured. Every sentence adds value—use cases, data provenance, caching behavior. No redundancy or fluff.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description is complete. It covers data origin, privacy, caching, and practical use cases. No gaps for an agent to invoke correctly.

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

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

Only one optional parameter 'window' with enums. Schema coverage is 100% (description in schema clarifies each window). Description adds minimal extra context ('shorter windows surface what's hot'). Baseline 3 is appropriate as 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?

Description clearly states the tool returns top tools, packs, and call volume over recent windows. The verb 'returns' and specific resource ('trending data on Pipeworx') make the purpose unambiguous. It also lists three concrete use cases, distinguishing it from sibling tools like discover_tools.

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

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

Description explicitly provides three use cases (discovering hot data, confirming canonical choice, aligning use case) and mentions caching behavior. It lacks explicit when-not-to-use or alternatives, but the use cases sufficiently guide appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: internal monotonicity checks, partition sum checks, semantic anchor with Jaccard similarity, partition filter for placeholders, fill check against live order book depth, and output structure. No contradictions.

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

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

The description is relatively long but well-structured. It fronts the main purpose, then details each mode, then covers secondary behaviors like fill check. Every sentence adds value, though some details like the fill check and custom sizing could be slightly condensed. Still, complexity justifies 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?

Despite no output schema, the description thoroughly covers return values (opportunities array, partition_check with fields) and behavior. It explains the fill check, semantic anchor, partition filter, and when signals are false. For a complex arbitrage tool, this is complete.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant meaning: for event, it explains walking child markets and checks; for topic, it explains searching related events and flattening markets. It also mentions accepted formats (full Polymarket URLs for event).

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: no args (trending scan), event (specific market), and topic (cross-event scan). This is specific and differentiates from all sibling tools, none of which focus on arbitrage.

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

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

The description explicitly tells when to use each mode: no args for a trending scan, event for a specific market (recommended), and topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp <= 0) and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description goes beyond this by detailing the three response segments, edge calculations (edge_pp_net, kelly_fraction), liquidity and spread filters, caching behavior, and diagnostic fields. No contradictions with annotations; the description adds significant behavioral context.

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

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

The description is verbose but efficiently packed with information. It front-loads the core purpose and then dives into segments, edge metrics, and knobs. Every sentence adds value. Minor improvement could be using bullet points or sections, but the structure is logical and clear for an AI agent.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It covers output structure (by_segment, fed_candidates, diagnostics), explains why segments may be empty (filter skips, stale data), and details caching (Cached 1h at KV level). Agents have all necessary context to use the tool effectively.

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% (all 9 parameters have descriptions). The description adds extra context for several parameters, such as slippage_pp (explaining zero fees but bid/ask impact), min_liquidity (walking the book), and min_partition_leg_kelly (why min_kelly doesn't filter partition arbs). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific resource (Polymarket markets) and action (scan and return opportunities). The segmentation into model-driven, structural arbitrage, and concentrated longshots distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies when to use (daily bet discovery) but does not explicitly state when not to use or name alternatives. However, the extensive detail on model families and edge metrics helps agents understand its domain.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. Description adds extensive behavioral detail: response structure (tracked, expired, snapshot_dates), decay computation on absolute value, signed interpretation, daily closes not intraday, 60-day TTL, snapshot start condition. Goes well beyond annotations.

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

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

Description is dense and informative, but somewhat long. Every sentence adds value. Minor inefficiency: parenthetical about negative sign could be in parameter description. Overall well-structured and front-loaded with purpose.

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

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

No output schema exists, so description fully explains return values: tracked array with time-series, first_seen, trend, decay; expired array with lifespan; snapshot_dates. Covers caveats (TTL, daily nature, snapshot gaps). Complete for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions including defaults and ranges. Description restates defaults ('days default 14, max 30'; 'window default 1wk') but adds no new semantics beyond schema. Baseline 3 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?

Describes specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' Clearly answers 'how long has this edge existed and is it shrinking?' Distinguishes from sibling 'polymarket_edges' by focusing on persistence and decay rather than raw snapshots.

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

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

Explains when to use: to differentiate between fresh and old edges. Provides concrete example (fresh vs 3-week-old edge). Lists limits (60-day TTL, snapshot gaps). Does not explicitly state when not to use or compare directly to all siblings, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds context beyond annotations: describes walking the ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, verdict), and highlights risks (thin_legs, forced_directional_risk). No contradiction.

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

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

Description is long but well-structured with clear sections for single-market and basket modes, plus usage warnings. Front-loaded with key info. Could be slightly more compact but every sentence adds value.

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

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

Despite no output schema, description lists all returned fields (top_of_book, vwap_fill_price, verdict, etc.) and covers both modes, parameter nuances, risks, and use cases. Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds rich meaning: explains size_usd in basket mode as 'settlement notional', default side behavior (auto from partition sum), and constraints (clamp 10–1,000,000). Goes well beyond schema.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live order-book depth, distinguishing single-market and basket modes with specific verbs like 'walks the ladder' and 'returns...'. This is highly specific and differentiates from siblings like polymarket_arbitrage.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains consequences of not using it (theoretical overround not capturable, partial fills convert arb to directional position). No ambiguity.

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 rich behavioral context beyond annotations: compatibility warnings, temporal alignment checks, and skipped leg counters. Consistent with readOnlyHint.

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?

Long but well-structured paragraph with bold labels. Front-loads purpose. Could be slightly more concise but earns its length with detailed safety fields.

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, describes response structure including spread, compatibility_warning, temporal_alignment, and skipped counters. Fully covers all inputs and warnings.

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?

Schemas have 100% coverage; description adds context on mode selection, override behavior, and lists all topic shortcuts with examples.

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

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

Clearly states the tool computes spreads between Kalshi and Polymarket for the same question. Distinguishes from siblings focused on single-venue 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?

Explains two modes (topic shortcuts vs explicit tickers) and provides explicit warnings about when spreads are not meaningful due to compatibility or temporal issues.

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, idempotentHint=true, destructiveHint=false. Description adds context about scoping to identifier and pairing with remember/forget, enriching beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the primary action, no unnecessary words. Efficient and well-structured.

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

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

Given one optional parameter, rich annotations, and no output schema, the description covers purpose, usage, scoping, and pairing with siblings. Complete for a read tool.

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

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

Schema description coverage is 100% and already explains omitting key lists all. Description restates this but adds no new meaning beyond what the schema provides.

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 'retrieve a value previously saved via remember, or list all saved keys', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'forget'.

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

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

Describes when to use: 'look up context the agent stored earlier' and scoping to identifier. Lacks explicit 'when not to use' or alternatives beyond mentioning siblings with different verbs.

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, destructiveHint=false. The description adds important behavioral details: setting mark_read:true flags events as read (a non-destructive side effect), and mentions that the feed is persisted and accessible via a GET endpoint. 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 well-structured sentences, each adding value. Front-loaded with purpose, then details on return fields and parameters, then usage guidance. No unnecessary words.

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

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

Despite no output schema, the description sufficiently explains return fields (source, citation_uri, raw payload) and provides context on polling and alternative access. For a read-only tool with 5 optional parameters, this is 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 coverage is 100%, and the description adds meaning to each parameter: type filter, limit max, since ISO timestamp, mark_read flag behavior (flags events read in same call), unread_only filter. This goes beyond the schema's basic 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 states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes itself from siblings like list_subscriptions and recall by focusing on fired alerts and providing details on return fields (source, citation_uri, raw payload) and filtering options.

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 this tool (retrieving fired events from subscription feed) and notes that 'Polls work fine' and an alternative GET endpoint exists. It doesn't explicitly state when not to use it, but the guidance is clear and practical.

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, and destructiveHint false. The description adds significant behavioral context: fan-out to multiple APIs, GDELT/GNews fallback, PatentsView sunset, and return structure. No contradictions.

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

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

Description is well-structured with examples and parentheticals. Every sentence adds value. Front-loaded with purpose and use cases, then detailed behavior. 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 no output schema, the description explains return structure (changes[], total_changes, citation URIs) and handles edge cases like patent API sunset. It is thorough and covers all essential behavioral aspects.

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 decent descriptions. The description adds concrete examples for 'since' (ISO, relative) and 'value' (ticker, CIK), improving usability. Baseline 3, elevated by additional guidance.

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

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

The description clearly states the tool provides a change feed for a company (SEC filings, news, patents) in a given time window. It distinguishes from sibling 'entity_profile' by specifying use cases. Purpose is specific and well-defined.

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 example queries and explicitly says when to use 'entity_profile' instead. It explains fallback behavior for news and patent limitations. However, it doesn't exhaustively list when not to use this tool or other 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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are enhanced by the description which adds behavioral details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 (5 sentences) and front-loaded with the core purpose. Every sentence adds value: main action, when to use, scope, persistence details, and sibling references. No wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description is complete. It covers purpose, usage, behavioral traits, and parameter conventions adequately for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context by providing conventions for key (e.g., 'subject_property') and value types, which adds meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and the resource 'data' with clear use cases (resolved ticker, address, preference). It distinguishes itself from siblings like recall and forget by mentioning them 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?

The description explicitly tells when to use the tool: 'when you discover something worth carrying forward.' It also mentions when not to use alternatives by pairing with recall and forget, providing clear context for choosing this tool over siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds that it cascades through several lookup endpoints internally, providing behavioral insight beyond annotations.

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

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

Description is well-structured, front-loaded with query examples, and each sentence adds value. Slightly verbose but not wasteful.

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

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

Given only two simple parameters and no output schema, the description fully explains what the tool returns for each type, including specific identifiers and citation URIs. Comprehensive for a lookup tool.

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

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

Schema coverage is 100%, but description adds examples of acceptable values (e.g., ticker, CIK, name for company; brand/generic for drug), enhancing understanding beyond schema alone.

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

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

Description clearly states it resolves a user-spoken name to a canonical/official identifier, with specific examples for each type. It distinguishes itself by noting it should be used first when a name needs an ID, though sibling differentiation is implicit.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and mentions it replaces 2-3 manual lookups. Doesn't explicitly state when not to use, but context with siblings provides 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density – valuable context beyond annotations.

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

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

Two sentences, front-loaded with core purpose. Every sentence adds value: first defines action, second explains process and use case. 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 moderate complexity (comparing multiple entities, ranking), the combination of rich annotations, full schema, and clear description fully covers purpose, usage, behavior, and expected output.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds narrative context (e.g., 'First entry treated as subject') but does not significantly enhance semantics beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb, resource, and scope. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides clear usage context ('competitive AI-marketing audits') and an example question. It implies when to use this over single-entity probes, though explicit when-not-to-use is missing.

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

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

The annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds significant behavioral context beyond annotations: it explains partial failures ('sources_failed will list it if it times out'), timing expectations ('bundlephobia's first measurement on a new version can take 5-30s'), and the composition of the response (summary block, per-advisory detail, links, alternative versions). 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 well-structured, starting with a concise summary of the composite check and usage notes. It front-loads the main purpose and usage. However, the list of returned fields (is_latest, license, etc.) is somewhat verbose and could be delegated to an output schema if one existed. Overall, the description earns its space but could be slightly trimmed.

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 external services, partial failures, rate/timing considerations) and the lack of an output schema, the description covers all essential aspects: it describes the return values, explains graceful degradation, and notes the potential delay for new versions. It is complete for an agent to understand what the tool does and what to expect.

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

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

Input schema coverage is 100%, providing baseline 3. The description adds meaning beyond schema: it explains that the package parameter accepts scoped packages like '@types/node', and that the version parameter defaults to the latest version when omitted. This enhances understanding, though the schema already provides clear descriptions.

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

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

The description clearly states the tool performs a composite check across deps.dev and bundlephobia for npm packages. It uses the verb 'scan' and specifies the resource ('npm package'), making the purpose unambiguous. The description distinguishes the tool from siblings by noting that other ecosystems are handled by a different tool.

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

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

The description explicitly states when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies the ecosystem limitation ('NPM ecosystem only in v1') and directs users to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This provides clear when-to-use and when-not-to-use 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?

Adds value beyond annotations by disclosing the embedding model (BGE-base-en), window size (500-char overlapping), token cap (200K chars with truncation and flagging), and similarity metric (cosine). 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?

Pithy and well-structured. First sentence states core action. Subsequent sentences add context, use cases, and technical details. Every sentence contributes meaningfully.

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

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

Despite lacking an output schema, the description explains return format (passages with offsets and similarity scores). For a tool with 3 parameters and comprehensive annotations, this is fully sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add per-parameter details beyond schema, but provides useful context for the 'query' parameter with example queries. No extra semantics for 'text' or 'limit'.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and specifies output (passages with offsets and scores). Distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing strategy.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Mentions pairing with ask_pipeworx_grounded for grounding. While no explicit when-not-to-use, the guidance is clear and actionable.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds value by specifying the return format (dataset names, descriptions, resource ids) and the intended follow-up tool. This goes beyond annotations without contradiction.

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

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

The description is two sentences: first states the action and resource, second states the return type and usage. Every sentence provides unique information, no fluff, and the key information is front-loaded.

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

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

With no output schema, the description adequately explains return values (names, descriptions, resource ids). It also mentions the optional API key indirectly via schema. It could mention pagination behavior or offset parameter, but the offset parameter itself hints at that. Overall, it's sufficient for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new parameter details beyond the schema, but it provides context for how parameters like 'query' and 'limit' are used in the search. The examples in schema also help, but the description itself is not essential for parameter understanding.

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

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

The description clearly states the verb 'Search', the resource 'Seattle open-data catalogue (data.seattle.gov)', and what is returned. It distinguishes itself from the sibling 'seattle_query' by noting the output is resource ids for use with that tool.

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

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

The description provides clear context by stating it returns Socrata resource ids to use with 'seattle_query', implying a workflow. However, it does not explicitly mention when to avoid this tool or provide alternatives for similar tasks like browsing recent datasets (seattle_recent).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description complements this by explaining the tool runs raw SoQL queries, which is consistent. It adds context about the data source and query syntax but doesn't detail response format or error behavior, which is acceptable given the annotations.

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

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

The description is extremely concise, consisting of two sentences that convey the tool's purpose, functionality, and guidance on alternatives. No redundant information, every sentence adds value.

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

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

Given the tool's complexity (raw SoQL with 8 params) and no output schema, the description covers the core functionality, links to sibling tools for resource discovery, and mentions all SoQL operations. It could be slightly improved by mentioning the response format (JSON) or error handling, but is largely complete for an AI agent.

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

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

All 8 parameters have descriptions in the schema (100% coverage). The description adds value by explaining that parameters like select, where, etc., correspond to SoQL clauses, and clarifies the resource_id format and _apiKey optionality. This goes beyond the schema by providing operational context.

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

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

The description clearly states the tool runs a raw SoQL query against Seattle open-data resources, specifying the Socrata ID format. It distinguishes from sibling tools by mentioning seattle_datasets and seattle_recent for finding resource IDs, providing clear context for when to use each.

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

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

The description advises using seattle_datasets or seattle_recent to find resource IDs, implying seattle_query is for querying once you have the ID. It lacks explicit exclusions or when-not-to-use scenarios but provides sufficient context for the primary use case.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: returns latest rows newest-first, mentions keyless endpoint, and explains optional _apiKey for rate limits. No contradictions.

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

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

Two concise sentences with a clear list of dataset names and usage note. Every sentence adds value, and the key information (purpose, preferred use, alternative) is 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?

Given no output schema, the description could mention the output format or fields returned. However, it is sufficient for the tool's simplicity and aligns with sibling tools like seattle_query. The description is complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with good descriptions for all four parameters. The description reinforces the 'where' parameter usage and lists dataset names, adding practical context beyond the schema. However, it doesn't add entirely new information beyond what the schema provides.

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

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

The description clearly states the tool retrieves recent records from Seattle open datasets using friendly names, specifies the supported datasets (crime, fire911, business, code_complaints), and notes it returns newest-first. This distinguishes it from siblings like seattle_query.

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

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

Explicitly says to prefer this tool over web search for common queries like 'recent crime in Seattle', and directs users to seattle_query for anything beyond simple filtering. Provides clear when-to-use and when-not-to-use 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 provide idempotentHint=true and openWorldHint=true. The description adds critical behaviors: OAuth requirement, SMS phone verification, 10/day SMS cap, and webhook auto-disable after 10 consecutive failures. These details are beyond what annotations convey and accurately disclose side effects and constraints.

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

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

The description is a single dense paragraph that effectively conveys all necessary information without redundancy. However, it could be improved by breaking into bullet points or sections for easier scanning. The front-loading of the main action and return value is good.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all relevant aspects: types, parameter structures, delivery channels, prerequisites, constraints, and error conditions. The agent has sufficient information to use the tool correctly. The return value is briefly mentioned but adequately.

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

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

Schema coverage is 100%, yet the description significantly enriches parameter meaning. For 'type', it explains each enum value's purpose. For 'params', it gives concrete examples per type. For 'delivery', it details field-specific constraints (phone format, webhook signing, auto-disable). This exceeds schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination that 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?

The description provides explicit prerequisites ('Requires a Pipeworx OAuth account') and lists all supported subscription types with examples. It also explains delivery options and constraints like SMS verification and daily cap. However, it does not explicitly contrast with alternatives like 'recent_alerts' for pulling from the feed.

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 true and destructiveHint false. The description adds valuable context by explaining the output format (category-bucketed examples with exact tool+argument shapes) and its role as an onboarding entry point, going beyond what annotations provide.

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

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

The description is detailed but well-structured, starting with common user queries and then explaining the output and usage. It front-loads the most important information and every sentence adds value, though it could be slightly more concise.

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

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

Given the single optional parameter and no output schema, the description fully explains the tool's behavior: what it returns (category-bucketed example questions with tool+argument shapes) and when to use it. It is complete for an onboarding 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 has 100% coverage for the single optional parameter, with description listing focus areas. The description reinforces this by providing examples (e.g., 'pass topic like finance, pharma, betting') and explaining the effect of omitting the parameter, adding marginal value over the schema alone.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions for onboarding users to understand Pipeworx capabilities. It distinguishes from sibling tools like ask_pipeworx and entity_profile by explicitly positioning itself as the first call for new connections.

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

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

The description explicitly says to use this tool FIRST when unsure of Pipeworx's capabilities, and provides guidance on omitting arguments for a full spread or passing a topic for focus. It also mentions learning how to call meta-tools, offering clear context for when to use this tool versus alternatives.

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

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

Annotations are already present, but the description adds valuable context: ownership enforcement, deactivation vs deletion, and that historical events remain available via recent_alerts. 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, each essential: purpose, ownership, and deactivation nuance. No wasted words, efficient and front-loaded.

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

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

For a simple tool with one required parameter, no output schema, and good annotations, the description fully covers purpose, side effects, and sibling relation to recent_alerts. Complete enough.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats that the subscription is identified by id but does not add new parameter-specific details 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 verb 'cancel' and the resource 'subscription by id'. It distinguishes from sibling tools by specifying ownership enforcement and the deactivation (not deletion) behavior.

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 ownership is enforced, so the tool is only for your own subscriptions. It does not mention alternatives or when not to use it, but the context is clear and sufficient.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains the internal routing logic, the exact percent-delta math for financial claims, the verdict outcomes, and the citation format. No contradiction with annotations.

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

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

The description is detailed but somewhat lengthy. It front-loads with examples and purpose, then dives into routing logic. Every sentence adds value, but some rephrasing could reduce redundancy. Still, it is well-organized 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 complexity (two processing paths, multiple verdict categories, citation requirements), the description covers all necessary aspects. Although there is no output schema, the description clearly lists the return structure: verdict, actual value with citation, and reasoning. It is sufficiently complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: it provides concrete examples for the 'claim' parameter and explains the 'tolerance_pct' parameter's purpose, default behavior, and special use case (hallucination detection with 1-2%). This goes well 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 clearly identifies the tool as for natural-language claim verification against authoritative sources. It provides example user phrases and distinguishes between company-financial claims (handled via SEC EDGAR fast path) and other claims (routed to grounded pipeline). It also notes that it replaces multiple sequential calls, emphasizing its unified purpose.

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

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

The description explicitly states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It details the two processing paths but does not explicitly state when not to use it. However, the clarity of usage context and alternatives implied by sibling tools is sufficient.

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