Indiana BMV

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds behavioral context: probes multiple models, returns per-model {score, confidence, signals, raw_response} + combined view, and explains cost implications for Anthropic ('you pay Anthropic directly'). 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?

Four sentences, each earning its place: function statement, default+key details, return structure, use cases. No redundancy, front-loaded with the core action.

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

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

Despite no output schema, the description explains the exact return structure per model and combined view. All four parameters are covered in schema and enhanced by description. The tool's role among 30+ siblings is clear. Completely adequate for an agent to invoke.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema: default model is Workers AI Llama-3.3-70b (free), clarifies _apiKey is BYO and directly charges user, and context helps disambiguate. This provides meaningful guidance beyond the schema descriptions.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for what they know about a business/brand/product/topic and score visibility'. It uniquely distinguishes itself from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on AI visibility scoring.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Mentions default model (free) and when to provide _apiKey for Anthropic. Does not explicitly mention when not to use, but the purpose is clear enough.

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, idempotent, and non-destructive behavior. The description adds valuable context: routing across 5,566 tools / 1,462 sources, filling arguments, and returning stable citation URIs. It doesn't contradict annotations, though it omits any failure/limitation details, so 4 is appropriate.

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 longer than average but every sentence earns its place: use-case prioritization, examples, sibling differentiation, and fallback hierarchy. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and structured clearly, though slightly verbose.

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

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

For a broad natural-language query tool with no output schema, the description covers the essential context: supported domains, routing behavior, citation format, tier/complexity strategy, and relationships to sibling tools. It is complete enough for an agent to select and invoke correctly in most situations.

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?

Parameter schema coverage is 100%, with aliases fully documented, so the schema carries the bulk of parameter meaning. The description reinforces that the question is natural language but adds no new parameter-specific semantics beyond that. Baseline 3 applies.

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

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

The description clearly identifies a specific action: routing natural-language questions to the appropriate data source tool and returning a structured answer with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and states it is the default entry point.

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

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

Provides explicit when-to-use guidance: prefer over web search for factual/current/historical queries, start here, and step up to alternatives only when needed. Names concrete alternatives and even gives examples of triggering phrasings and queries.

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

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

The description adds transparency about the beta testing behavior: candidate routing improvements are enabled live when under test, and currently no candidate is active. It also states it is a 'full working router' and 'experimental edge', which complements the readOnly, openWorld, and idempotent hints. 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 repetitive and verbose. It repeats the same information about being identical to ask_pipeworx, the candidate testing, and the current state multiple times. This could be condensed significantly without losing meaning.

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

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

The description provides sufficient context for the beta nature and usage, but does not explain what the underlying ask_pipeworx tool actually does (the 'universal router' concept is vague). Given the annotations and schema, the description is adequate but not fully complete for an agent unfamiliar with the sibling 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?

The schema already provides descriptions for all parameters (all aliases for 'question'), so coverage is 100%. The description does not add any new meaning to the parameters beyond stating they are the same arguments as ask_pipeworx, which is redundant given the schema. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, stating it is an identical universal router with the same tools, arguments, and response shape. However, it does not explicitly define what the router does beyond being a 'universal router', relying on the sibling context. It distinguishes itself from the stable ask_pipeworx 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?

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable version. It also mentions that results are compared against the stable router, giving clear guidance on the experimental nature and its current equivalence to ask_pipeworx.

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

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

Annotations already mark it read-only, idempotent, and open-world, but the description adds significant behavioral detail: it returns a structured {answer, evidence, confidence, source, fetched_at} shape, provides explicit refusal reasons, and clarifies that it only uses tool content. No contradiction with annotations.

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

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

The description is dense but well-structured: purpose, mechanism, return format, usage guidance, and cost trade-off in four sentences. No wasted words, and critical 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?

Given the tool's complexity is low (single question input), the description fully covers return values, refusal reasons, use cases, and cost implications. It is complete enough for an agent to select and invoke correctly without additional 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 all parameters documented as aliases for the single question field. The description adds no extra parameter semantics beyond stating it accepts a natural language question, which is sufficient. Baseline 3 applies.

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

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

The description clearly states this is a hallucination-resistant answer mode that extracts answers solely from tool results, distinguishing it from the sibling ask_pipeworx. The verb 'extracts' and resource 'answer' are specific, and it explicitly positions itself as the grounded alternative.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), also noting the extra LLM call cost. This is model usage guidance with a clear alternative.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description details fan-out logic, response structure, resolver contract, parent_event extraction, news fallback behavior, safety short-circuits, and resolution-rule parsing. 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 lengthy but well-structured with capitalized headers (e.g., 'RESPONSE SHAPES', 'RESOLVER CONTRACT'). It front-loads the core purpose and uses bullet-like formatting in the text. However, it could be more concise for quick scanning.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers input formats, fan-out logic, response fields, edge cases, safety, and resolution rules. Every aspect needed for correct usage is addressed.

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. The description adds value with concrete examples (slug, URL, question text) and explains the 'depth' and 'include_raw' parameters in context (quick vs thorough, summarized vs raw). This enhances understanding beyond the schema.

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

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

The description immediately states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and scope. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on general research for a single bet.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers when to exercise caution (low-confidence matches, closed markets, wide spreads) and resolution-rule risk, providing clear context for appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and return format (paired data + citation URIs). It does not cover rate limits or errors, but overall 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 a single, well-structured paragraph that front-loads key trigger phrases. Every sentence contributes value: usage guidance, data sources, sorting behavior, return format, and efficiency claim. No redundant or unnecessary text.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs) and data sources. It covers entity types, metrics, and sorting. Missing details on error handling or data freshness, but for a 2-param tool it is adequately complete.

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

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

Schema coverage is 100% with brief descriptions. The description adds meaning by mapping type values to specific output metrics (revenue, net income, etc. for company; FAERS counts for drug) and providing example inputs for values (tickers, drug names).

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists common trigger phrases ('compare X and Y', 'X vs Y', etc.) and clearly distinguishes itself from sequential lookups.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups' and details when to use each entity type (company vs drug) with specific metrics (10-K data, FAERS counts). It also explains sorting by primary metric for answering 'largest' queries.

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

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

The description richly discloses behavioral traits beyond the annotations: account requirements, paid tier for 'thorough' depth, parallel decomposition, gap recovery and contradiction scans, citation behavior (pipeworx:// URIs, hop field, only present when fetchable), semantic excerpting, latency expectations (15-60s, up to ~90s). The annotations already indicate read-only/open-world/idempotent, and the description adds significant useful context without contradicting them.

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

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

The description is lengthy but information-dense, covering many critical facets (account, alternatives, use cases, behavior, limitations, performance). It is front-loaded with the most important operational constraint (account requirement) and alternative, and each sentence earns its place. Loses one point for length and dense packaging that might be overwhelming, but no redundancy.

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

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

Given the tool's complexity (5,566 tools, parallel routing, facets, hops, citations, contradictions, gaps), the description is remarkably complete. It explains what returns, what happens in each depth, what the output contains (findings packet, verbatim evidence, gaps[], contradictions[], hop, citation_uri), and performance expectations. No output schema exists, so the description's explicit return-value details are essential and fully 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%, so the schema already documents both parameters (question and depth) with descriptions including enum meanings. The description adds behavioral nuance beyond the schema by explaining how depth values affect hops, gap recovery, contradictions scan, and paid requirement for thorough. This is more than what the schema provides, hence above baseline 3, though not a 5 since the schema already covers the basics well.

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

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

The description explicitly states what the tool does: grounded multi-source research across Pipeworx's structured data sources in one call, with decomposition and parallel routing. It clearly distinguishes itself from siblings (ask_pipeworx) by emphasizing it is NOT open-web search and covering broad/multi-part structured-data questions.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicit when-not-to-use: for single lookups use ask_pipeworx, for breaking/current-news prefer ask_pipeworx. Also names the alternative tool and explains why, giving clear context and exclusions.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that results are ready to call directly with no second schema lookup, and provides details on output (top-N tools with schemas and examples). 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 well-structured, front-loading purpose and usage. While comprehensive, it could be slightly more concise by removing redundant mentions of domains. It effectively uses two clear sentences.

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

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

For a discovery tool with 6 parameters and no output schema, the description provides enough context: it explains the output format (tool names, descriptions, schemas) and usage scenarios. It lacks details on error handling or edge cases, but is sufficient for typical use.

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 each parameter. The description adds that 'query' accepts multiple aliases and gives natural language examples. However, it does not explain the ranking logic for 'top-N' beyond the limit parameter.

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

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

The description clearly states the tool's purpose: finding tools by describing data or task. It lists specific domains and explains that it returns tool names, descriptions, and full input schemas. This distinguishes it from sibling tools, many of which are specialized for specific tasks.

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

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

The description explicitly advises when to use this tool: when browsing, searching, or needing to discover tools. It specifies 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: fans out across multiple sources, returns specific data fields (cik, filings with URIs, fundamentals sorted, patents with sunset warning, news fallback, LEI). It transparently notes potential soft-fail for patents.

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

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

The description is front-loaded with example queries and structured with a clear list of returns. It is thorough but slightly long; could be trimmed of redundant phrasing. However, it earns its length by providing comprehensive 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 complexity (multiple data sources, no output schema), the description covers the return format well, listing each field and source. It lacks explanation of error handling or pagination, but overall provides sufficient completeness for an agent to understand the tool's 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 descriptions for both parameters. The description adds crucial context beyond schema: that names are not supported and to use resolve_entity first, and clarifies value format (ticker or zero-padded CIK). This significantly aids 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 with specific verbs like 'tell me about', 'research', 'brief me on', and explicitly distinguishes it from chaining single-pack lookups and from resolve_entity. It names the resource (US public company) and scope (cross-source profile).

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

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

The description explicitly states when to use (holistic view of a public company) and when not to use (name only, directing to resolve_entity). It also advises to prefer this over chaining single-pack lookups, providing clear contextual 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?

Description matches destructiveHint=true with 'Delete' and adds pairing context. IdempotentHint=true is not contradicted but not elaborated. 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?

Two sentences, front-loaded with purpose, then usage guidelines. No wasted words.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description covers what, when, and how it pairs with other tools. Complete.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. Description adds no further semantics beyond the schema, so baseline is appropriate.

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

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

Description states 'Delete a previously stored memory by key' which is a specific verb and resource. It clearly distinguishes from siblings like 'remember' and 'recall', which are complementary operations.

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 provides when to use: when context is stale, task done, or clearing sensitive data. Also pairs with remember and recall, offering clear context against 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, idempotentHint, and destructiveHint false. Description adds context by explaining the process (fetches page, extracts title/description/key links, emits standard format). Does not contradict annotations.

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

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

Two concise sentences plus a bullet list of use cases. Front-loaded with purpose and output format. 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?

Tool has 2 parameters, no output schema, but description explains output is a single text blob ready for site-root/llms.txt. Annotations cover safety. Complete coverage for this complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning beyond schema for url and max_links; it simply lists what the tool does, not parameter-specific 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 generates a production-ready llms.txt file for any URL, with specific verb and resource. It distinguishes from sibling tools by specifying the exact output format and use case for AI crawlers.

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

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

Explicitly lists when to use: getting a client's site indexed, drafting for own project, or auditing competitor. No mentions of when not to use, but the positive guidance is strong and sufficient given tool's specificity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: 'Covers all 160 published locations in one file' and lists return fields (address, phone, hours, etc.), providing transparency about data source and output without contradicting annotations.

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

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

The description is four sentences with the main purpose front-loaded. Each sentence adds essential information: purpose, return fields, examples, and coverage. No redundant or irrelevant content.

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 6 optional parameters, no output schema, and no nested objects, the description fully explains what the tool does and what it returns. The mention of 'one file' and coverage of all locations provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds example queries and hints at parameter usage (e.g., 'plain words also work'), but does not significantly extend beyond the schema's already detailed parameter descriptions.

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

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

The description clearly states 'Find an Indiana BMV location' and enumerates specific location types and use cases. Example queries further solidify the purpose. No sibling tool overlaps, so differentiation is inherent.

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 example queries and implicitly defines when to use the tool (any BMV-related location search in Indiana). However, it does not mention when not to use it or list alternative tools, but given the narrow scope, this is a minor omission.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint. Description adds context about returning specific fields and defaults to active subscriptions, enriching 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 sentences, front-loaded with purpose, no wasted words. Every sentence provides value: what it does, what it returns, when to use.

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

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

Simple tool with one optional parameter and rich annotations. Description fully covers purpose, usage, and return fields, making it complete for agent selection and invocation.

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

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

Schema coverage is 100% with 'include_inactive' clearly described. Description does not add meaning beyond schema, but its purpose context complements parameter understanding. Baseline 3 is appropriate.

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

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

Description uses specific verb 'List' and resource 'subscriptions', clearly stating it returns the caller's active subscriptions and lists returned fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises using before adding more subscriptions or to find an id to cancel, providing clear context for when to use. Does not explicitly state when not to use, but sibling tool names imply alternatives.

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

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

The annotations (all false) provide no safety profile, so the description carries the full burden. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow for anonymous filing and later retrieval, and the accountability signal ('The team reads digests daily'). 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 purpose, followed by usage contexts, exclusions, workflow, and constraints. Every sentence adds distinct, non-redundant information—even the final 'The team reads digests daily and signal directly affects roadmap' clarifies impact. Though lengthy, it is appropriately sized for the tool's 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, but the description adequately explains return behavior via claim_token ('returns a claim_token; pass it back... to read whether it was fixed and what changed'). It also covers prerequisites, limits, and what to include/exclude. The tool's complexity is high but the description leaves no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining claim_token's forwarding workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and constraining message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). These are meaningful additions, but they are modest beyond the schema's already rich param descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all sibling tools (e.g., ask_pipeworx, discover_tools) by explicitly targeting Pipeworx tool issues and internal team communication.

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

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

Provides explicit when-to-use guidance: '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 includes a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This fully addresses when and when-not to use the tool.

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

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

Annotations already mark it as read-only and idempotent. The description adds valuable context: self-aggregating from CF analytics, no PII, and caching behavior (5min-1h), which goes beyond annotations.

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

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

Three concise sentences plus a bullet list. Every sentence adds value—no fluff, 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?

For a simple read-only tool with full annotations and schema, the description covers purpose, use cases, return content, privacy, and caching. No output schema needed; completeness is high.

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 schema description already explains the window parameter meaning. The description reinforces it but adds no new information beyond the schema.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) over configurable windows, distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical tool, aligning use case), and the window parameter guidance implies when each window is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing the actual behavior: monotonicity checks, partition-sum checks, semantic anchor filtering, partition filtering, fill check against live CLOB depth, and conditions for not trading. This adds significant 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?

The description is comprehensive but somewhat verbose, with multiple paragraphs and capitalized section headings. It could be more concise without losing essential information. However, it is well-structured and front-loads key information.

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

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

Given the tool's complexity (multiple modes, filters, fill check, response structure), the description is remarkably complete. It explains the response format (opportunities[], partition_check), the fill check logic, and even mentions an alternative tool for custom sizing. No output schema exists, so the description compensates fully.

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

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

The input schema has 100% description coverage for both parameters, but the description adds substantial value: it provides example values ('fed-decision-may-2026'), explains the difference between event and topic modes, and gives guidance on what to pass (e.g., 'event slug' vs 'seed question'). This enriches the semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket), the method, and distinguishes between the two modes (event and topic). The purpose is concrete and leaves no ambiguity.

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

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

The description explicitly tells the agent when to use each parameter: 'Call with NO args for a trending_scan... pass `event` for... or `topic` for...' It recommends `event` for specific markets and explains the advantage of `topic` for cross-event scanning. This provides clear usage guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: three model families with internal mechanics, caching (1h KV-level), diagnostics structure, and edge cases (fed bets, placeholder slugs). No contradictions with annotations.

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

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

Well-structured with sections, each sentence adds value. However, the description is lengthy and could be trimmed by omitting some detailed model mechanics (e.g., exact Kelly caps, sport-specific alphas) that might overload the 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 9 parameters, no output schema, and high complexity, the description thoroughly explains response format (by_segment, diagnostics), caching behavior, and edge cases. Agents have enough 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?

All 9 parameters are fully described in the input schema (100% coverage). The description adds contextual guidance on how knobs interact (e.g., 'Bump for very thin partitions') and tradeable-edge filters, going beyond schema descriptions.

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

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

Clearly states verb ('scan') and resource ('Polymarket markets'), and differentiates from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement. The phrase 'what should I bet on today' establishes the tool's unique role.

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

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

Provides clear context for when to use ('discover opportunities without paging') and describes configurable knobs for filtering. However, does not explicitly contrast with sibling tools (e.g., polymarket_edge_tracker) or state when not to use this tool.

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

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

Annotations declare readOnly, idempotent, and not destructive. The description adds rich behavioral context: it returns time-series (edge_pp_net across snapshots), trend classification (new/widening/stable/decaying), decay rate, expired opportunities with lifespan, and snapshot dates. It also discloses that snapshots are written on cache-miss and that decay is based on daily closes not intraday. This fully characterizes behavior beyond annotations.

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

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

The description is long but efficiently structured: purpose sentence, key question, response breakdown in bullet-like format (tracked[], expired[], snapshot_dates[]), and limits. Every sentence adds value; no redundancy. It is front-loaded with the core mission and ends with important caveats.

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

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

Despite no output schema, the description fully specifies the return structure (arrays with fields and their meanings). It explains edge_pp_net sign convention, first_seen, trend classification, decay_pp_per_day, expiration with lifespan_days, and snapshot dates. It also covers limitations (60-day TTL, non-intraday decay). For a tool with two optional parameters, 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?

Both parameters have schema descriptions (100% coverage). The description adds meaning by explaining 'days' as lookback (default 14, max 30) and 'window' as snapshot family (24hr|1wk|1mo). It clarifies that snapshots exist only for days when polymarket_edges ran on a cache-miss, which is crucial for interpreting the 'days' parameter. This enriches 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 states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series persistence rather than current 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?

The description explicitly advises when to use this tool over alternatives: 'a fresh wide edge and a 3-week-old wide edge are different trades' implies it should be used when edge age and trend matter. It also provides context on snapshot gaps and history TTL, helping agents decide if the data is appropriate. While it doesn't list specific 'when not to use' conditions, the contrast with raw edge data is clear.

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

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

The description discloses detailed behavioral traits beyond annotations: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk and thin leg identification. It explains how basket fills can strand you unhedged, which is critical 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 appropriately sized and well-structured. It starts with a one-line purpose, then uses clear section headers (REQUIRES, SINGLE-MARKET, BASKET, usage guidance). Every sentence adds value, and there is no redundancy.

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

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

Given no output schema, the description comprehensively covers return values for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It also explains verdict values and usage context, making it complete for an agent to understand all aspects of the tool.

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

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

With 100% schema coverage, baseline is 3, but the description adds significant meaning: it explains the side default logic for basket mode (auto from partition sum), interprets size_usd differently for single-market vs basket, and provides context for how parameters affect behavior beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role.

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

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

It explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it (partial fills converting arb into directional risk), providing 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?

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: it explains that compatibility_warning occurs for mismatched bet shapes or semantically unrelated events, and temporal_alignment affects spread validity. No contradictions with annotations.

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

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

The description is thorough but verbose, containing many details that could be condensed. It front-loads the core purpose and modes, but the extensive explanation of compatibility warnings and skipped types adds length. Adequately structured but not optimally concise.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety fields) and absence of output schema, the description is remarkably complete. It covers purpose, modes, response structure, compatibility warnings, temporal alignment, and pitfalls. Every important aspect is addressed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the pre-mapped topic list and the override behavior of explicit parameters. It also describes the response structure including safety fields, which aids in understanding parameter usage. A slight bonus for context, but not enough for 5.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by being the only tool that combines both venues. The verb 'spread' and resource 'cross-venue' are specific and unique.

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

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

The description explicitly explains two modes (topic shortcuts vs explicit tickers) and when to use each. It warns about compatibility warnings and states when spreads are meaningless (e.g., temporal misalignment). It also cautions that pre-mapped topics are not necessarily tradeable, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This is useful context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with core action. Every sentence earns its place without waste. Highly 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?

No output schema is provided, so description should describe return format. It mentions 'retrieve a value' or 'list all saved keys' but does not specify the data structure or format of the returned value or list. This is a minor completeness gap for a retrieval 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 clear parameter description. Description adds useful nuance: 'omit the key argument to list all keys,' which explains default behavior. This adds value beyond the schema's description of the parameter.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' Identifies verb (retrieve/list) and resource (saved values/keys), and 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?

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' and 'Pair with remember to save, forget to delete.' Provides clear context for when to use, though doesn't explicitly state when not to use or give alternatives beyond siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detail on return fields (source, citation_uri, raw event payload) and the effect of mark_read on subsequent calls, providing context beyond annotations.

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

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

Description is four sentences, front-loaded with purpose, and each sentence adds value. No unnecessary words 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 specifies what alerts carry (source, citation_uri, raw payload). Combined with full parameter coverage and annotations, it provides a complete picture for agent usage.

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

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

Schema covers all 5 parameters with descriptions. The description adds usage context for 'type' and 'since' filtering, and explains the behavior of 'mark_read', which enriches the semantic 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 begins with a clear verb ('Pull') and resource ('fired events from your subscription feed'), and distinguishes itself from siblings like 'list_subscriptions' by specifying it returns recent alerts from a persisted feed.

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 that polling works fine and provides an alternative endpoint for scripts/dashboards. Also explains when to use 'mark_read' and filtering. Lacks explicit comparison to sibling tools but still offers practical guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds details about fallback behavior (GDELT→GNews), USPTO soft-fail, and return structure (changes[] + total_changes + URIs). 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?

Single dense paragraph; all sentences add value. Could be improved with bullet points for sources or parameters, but remains efficient for its content.

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

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

No output schema, but description mentions return shape and error handling (soft-fail for USPTO). Covers annotations, parameter usage, and alternatives. Adequately 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 has 100% coverage with descriptions, but the description adds practical context (e.g., 'Use 30d or 1m for typical monitoring', 'zero-padded CIK'). This adds value beyond schema.

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

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

Description clearly states it provides a change feed for a company over a time window, with specific sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling entity_profile by specifying the difference between dynamic changes and static profile.

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

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

Explicitly provides example queries and suggests when to use entity_profile instead. Includes guidance on since parameter ('Use 30d or 1m for typical monitoring').

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 present (idempotentHint, readOnlyHint, destructiveHint) and description adds behavioral context about memory persistence (authenticated vs anonymous sessions) and scoping by identifier.

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, covering all key aspects in a few sentences without unnecessary words. Information is front-loaded and well-organized.

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

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

Given no output schema and full parameter coverage, the description adequately explains purpose, usage, behavior, and links to related tools. No gaps identified.

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

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

Schema coverage is 100% with good descriptions. Description provides a conceptual overview but doesn't add significant detail beyond the schema 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?

Description clearly uses specific verb 'save' and resource 'key-value pair', and lists example use cases. It distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides examples. Directs to pair with recall and forget for full lifecycle management.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context: sources (EDGAR, GLEIF, OpenFIGI, RxNorm), explicit `unresolved` field rather than omission, ISIN-to-LEI mapping, and graceful degradation when enrichment services are unavailable. 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?

Despite being long, every sentence carries information: quoted natural-language triggers, supported types, source details, fallback behavior, and a manual-lookup comparison. The use of 'SUPPORTED TYPES' and labeled parentheticals creates a scannable structure with no filler.

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

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

For a 2-param tool with no output schema, this description is unusually complete: it specifies accepted inputs by type, all returned identifier categories, failure representation (`unresolved`), source semantics, and degradation behavior. An agent can confidently select and invoke it without additional discovery.

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

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

Schema already covers both parameters at 100%, so baseline is moderate; the description adds extra meaning by mentioning ISIN as a valid company input and illuminating output semantics (e.g., CIK/ticker/company_name/LEI/FIGI or RxCUI/ingredient/brand). It doesn't need to compensate for missing schema docs, hence just 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 opens with concrete user-phrase examples and states a specific action: resolve a user-spoken name to canonical/official identifiers needed by other tools. It clearly distinguishes resolve_entity from sibling tools like entity_profile or validate_claim by positioning it as the preliminary ID-lookup step.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving a clear trigger condition. It also breaks down supported types and input formats (company vs drug), and mentions graceful fallback, so an agent knows when and how to invoke it.

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

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

Adds behavioral details beyond annotations: uses ai_visibility_check internally, returns ranked list with score, confidence, signal density, and treats first entity as 'subject'. Annotations already declare readOnly, idempotent, openWorld; no contradiction.

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

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

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

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

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

Covers purpose, workflow, output fields, and subject treatment. Lacks detailed error handling or limitations, but sufficient for a comparison tool with full schema 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%, so baseline is 3. Description adds semantic value: explains that first entity is treated as subject for narrative, and that entities are probed with ai_visibility_check.

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 compares AI visibility across multiple entities side-by-side, ranks them by score, and surfaces most/least recognized. It differentiates from sibling 'ai_visibility_check' which likely probes single entities.

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

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

Explicit use case given: competitive AI-marketing audits. Context implies not for single entity checks (sibling tool exists), but no explicit when-not or alternative mention.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds important behavioral context: partial failures degrade gracefully, first measurement on new version can take 5-30s, sources_failed lists timeouts. 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?

First sentence front-loads core purpose. Subsequent details cover usage, behavior, and ecosystem scope. A bit lengthy but each sentence adds value. Could be slightly tightened without losing information.

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

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

For a tool with 2 parameters and no output schema, the description covers return structure (summary block, per-advisory detail, links, alternative versions) and edge cases (partial failures, latency). Leaves little ambiguity for an 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% with descriptions for both parameters. Description adds value by mentioning scoped packages accepted for 'package' and default behavior for 'version'. This goes beyond the schema's literal 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?

Clear verb+resource combo: 'scan dependency' is specific. Description states it's a composite check for npm packages, distinguishing it from sibling tools like 'deep_research' or 'validate_claim'. The purpose is unmistakable.

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

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

Explicitly says when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides ecosystem limitation ('NPM ecosystem only in v1') and points to alternatives ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Disclosures beyond annotations: details on embeddings (BGE-base-en), chunking (500-char overlapping windows), and truncation behavior (200K chars, flagged). Annotations already declare readOnlyHint etc., and description adds significant 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?

Every sentence is valuable: purpose, usage guidance, technical details. Front-loaded with main action. No fluff.

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

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

Despite no output schema, description explains return value (top-N passages with offsets and scores), covers limits, and mentions pairing. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds no new parameter semantics beyond the schema, though it provides example queries. Adequate but not exceptional.

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 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes from siblings by mentioning it works inside a record and pairs with ask_pipeworx_grounded.

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 ('record is too big to cram into the prompt') and provides alternatives ('fetch with the gateway, ground over the relevant passages'). Gives clear context for 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?

Adds extensive behavioral details beyond annotations: OAuth requirement, delivery channel limits, phone verification, webhook signing, auto-disable on failures. IdempotentHint=true does not contradict description.

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

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

Well-organized with key info up front (purpose, return, requirement). Slightly long due to thorough examples, but each part serves a 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?

Covers all needed aspects: prerequisites, type-specific parameters, delivery options, return value, constraints. No output schema needed.

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

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

Schema coverage 100%, but description provides rich examples and clarifies required vs optional sub-fields for each type and delivery channel, adding significant value.

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?

States verb 'Create' and resource 'subscription' clearly. Distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation and live-data event stream.

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

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

Provides explicit context about required Pipeworx OAuth account and supported subscription types with examples. Lacks explicit when-not-to-use or alternatives, but the sibling tool set makes it 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?

Description adds behavioral context beyond annotations: it returns example questions with tool+argument shapes, explains response structure, and mentions the live catalog. Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false; description is consistent and enriches understanding.

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 slightly lengthy but front-loaded with key purpose and user-targeted phrasing. Structured into variations of user questions, then explanation of returns and usage. Efficient but could be trimmed slightly.

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

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

Complete for a simple tool with one optional parameter and no output schema. Covers what it does, when to use, how to invoke, and what kind of response to expect. No missing information.

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

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

Input schema has 100% coverage with a clear description of the topic parameter and its possible values. Description adds usage context (e.g., 'Omit for a cross-category spread') that enhances but does not significantly surpass schema information.

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

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

Description clearly states it is an onboarding entry point that suggests example questions, returning category-bucketed examples with tool and argument shapes. It distinguishes from siblings by advising to use this FIRST when unaware of Pipeworx's capabilities.

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

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

Explicitly states when to use (when you don't know what Pipeworx can do, or to learn meta-tools) and how to call: with no arguments for full spread or with a topic to focus. Provides clear alternative context.

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

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

Annotations indicate destructiveHint=false and readOnlyHint=false. The description adds value by explaining that the row is deactivated (not deleted) and that historical events remain, which clarifies the non-destructive nature. It also mentions ownership enforcement, which is not captured in 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 short sentences that convey all necessary information without extraneous words. Information is front-loaded with the core action.

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

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

Given the tool's simplicity (single parameter, no output schema) and sibling tools, the description is fully complete. It covers the action, ownership constraint, and side effects, leaving no gaps for the agent to infer.

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

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

The input schema has 100% description coverage for the single parameter 'id', which already explains it as 'Subscription id (uuid) returned by subscribe.' The description does not add any additional semantic meaning beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation 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 states ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation not deletion), guiding appropriate use. However, it does not explicitly mention when not to use this tool or provide direct alternatives beyond implying historical events are available via 'recent_alerts'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds substantial behavioral detail beyond this: the two routing paths (SEC EDGAR vs. grounded), the exact verdict values, the critical semantics of could_not_verify (not evidence, carries verification_error) and unsupported, and the pipeworx:// citation. This gives the agent a clear model of what the tool does and how to interpret results, with no contradiction to 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 longer than average but each segment serves a purpose: trigger phrases, purpose, usage, pipeline routing, return values, and a caller warning. It is front-loaded with the most important information. It is slightly verbose with some redundancy (e.g., listing many trigger phrases), but overall well-structured and 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?

For a complex tool with no output schema, the description covers the necessary aspects: the verdict set with semantics, the two pipeline behaviors, the error case (could_not_verify) with its structured error, and the fact that it collapses multiple sequential calls. The combination of annotations, schema, and description gives the agent a full picture of how to invoke and interpret the tool.

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

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

Schema description coverage is 100%, and both parameters (claim, tolerance_pct) already have rich descriptions in the schema, including defaults, ranges, and usage examples. The tool description itself does not add parameter-level details, but since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, with explicit trigger phrases ('fact check', 'verify the claim that...') and a specific resource. It also distinguishes between two verification pipelines (structured SEC EDGAR/XBRL for company-financial claims vs. grounded pipeline for other claims), setting it apart from sibling tools like ask_pipeworx 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 gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that it replaces 4–6 sequential calls, indicating when to prefer this composite tool. However, it does not explicitly name alternative tools or discuss when not to use it, so a small gap remains.

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