Data Pa

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 context: default model (Workers AI, free), optional Anthropic probing (BYO key, paid directly), and return format (per-model {score, confidence, signals, raw_response} + combined view). This 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?

The description is a single paragraph of four sentences, front-loaded with the primary action. Every sentence adds value: main functionality, default model, optional API key detail, return structure, and use cases. No wasted words.

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

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

Given the tool's complexity (multiple models, optional API key, scoring), the description covers essentials: probing multiple models, scoring, pricing distinction, and return format. It does not detail scoring methodology but provides enough for an agent to use correctly. The parameter examples (e.g., 'Pipeworx', 'OpenInvoice') add context. Sibling tools are diverse, but this tool is distinct.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds meaning by explaining the default model, the role of `_apiKey`, and the purpose of `context` for disambiguation. It also outlines the return structure, compensating for the lack of an output 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 action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes from sibling tools like 'ask_pipeworx' which are for asking questions, not 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?

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use optional parameters (e.g., `_apiKey` for Anthropic). However, it does not explicitly state when not to use this tool or suggest alternatives, though the sibling list implies other tools for different tasks.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context: it routes across 5,798 tools and 1,517 sources, fills arguments, and returns structured answers with stable citation URIs — behavior an agent cannot infer from annotations alone.

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 purposeful: the leading directive is front-loaded, followed by domains, examples, and sibling routing. Some redundancy exists in the long example list, but each section earns its place by narrowing the agent's decision.

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?

This is a broad router tool with no output schema, and the description compensates well by stating what it returns (structured answer with pipeworx:// citation URIs) and when to escalate to siblings. It could add notes on limitations or auth/subscription needs, but it is substantially complete for 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 description coverage is 100%, so the schema already documents all six parameters as aliases for 'question'. The description reinforces that input is a natural-language question but adds no new semantic detail beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb ('routes', 'returns') and a broad but well-defined resource: authoritative structured data from verified sources, and it explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. The extensive examples and domain list make its scope 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?

It gives explicit 'PREFER OVER WEB SEARCH' and 'START HERE' guidance, lists trigger phrases and example queries, and names alternatives with conditions: ask_pipeworx_grounded for a hallucination-resistant single answer, deep_research for broad/multi-part questions. This is strong routing guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that this is an experimental live edge with candidate routing improvements under test, that results are compared against the stable router, and that it 'falls back to nothing' while still being fully functional. This is valuable behavioral context that annotations alone would not provide.

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

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

The description is moderately detailed and mostly front-loaded with the beta identity and current equivalence to the stable tool. It includes some repetition between 'currently matches ask_pipeworx exactly' and 'use it exactly like ask_pipeworx,' but every sentence contributes meaningful routing or state 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 rich schema and annotations, the description covers the essential invocation context: what the tool is, how it differs, what is currently active, and how to use it. Since there is no output schema, mentioning 'same response shape' as ask_pipeworx is somewhat indirect, but the sibling tool provides the needed reference.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question.' The description only says the tool takes 'the same arguments' as ask_pipeworx and adds no new semantic detail about parameters, so the 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 identifies this as the beta version of ask_pipeworx and defines it as an 'identical universal router' with the same tools, arguments, and response shape. It distinguishes the tool from the stable sibling by emphasizing 'candidate routing improvements' and the 'experimental edge,' though the core user-facing action is somewhat implicit.

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

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

The description explicitly tells the agent to 'use it exactly like ask_pipeworx when you want the newest routing' and notes that no candidate is active, so behavior currently matches the stable router. It does not explicitly enumerate when not to use it, but the comparison to the stable router supplies clear selection 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the exact success return shape, the refusal return shape, the list of refusal reasons, and the constraint that answers use only tool-result content. It also reveals the extra-cost tradeoff. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return contract, refusal semantics, usage cases, and cost/alternative. It is front-loaded with the most important phrase, 'Hallucination-resistant answer mode for high-stakes reads,' and the return shape is concise despite the detail.

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

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

With no output schema, the description supplies the complete return contract and failure modes, which is essential for an agent to interpret tool results correctly. It also explains the routing behavior, the guarded answer policy, and the relationship to ask_pipeworx, making the tool self-sufficient for invocation and result handling.

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

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

Schema description coverage is 100%, so the schema already documents the question parameter and all six aliases. The description does not add meaningful parameter-level detail beyond what the schema provides; it mainly refers to the overall 'ask' workflow. Baseline 3 is appropriate because the schema carries the load.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode: it routes through the same tool-selection machinery as ask_pipeworx, fetches data, and extracts answers only from the tool result. The verb 'ask' plus the 'grounded' mode and explicit behavior distinguish it from siblings, especially ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: high-stakes reads where answers will be quoted, cited, or acted on, and where the agent must not invent facts (financial, legal, medical, public statements). It also explicitly says to prefer ask_pipeworx for casual lookups and flags the extra LLM-call cost, giving clear selection criteria versus the sibling.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral details: low-confidence match short-circuit, closed market handling, wide-spread liquidity warnings, resolution-rule risk parsing, and parent event extractor—far beyond what annotations provide.

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

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

The description is long but well-structured with capitalized section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded summary. Could be more concise, but the structure aids readability.

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

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

Given the tool's complexity and absence of output schema, the description covers all crucial aspects: resolution confidence, parent event extraction, news fallback behavior, safety mechanisms, and cancellation rules. 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 all three parameters described. The description adds context for the market parameter (slug, URL, question text) and examples, but doesn't significantly extend depth or include_raw beyond schema. Baseline 3, plus minor value gives 4.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data, with specific input examples (slug, URL, question text) and output goals. It distinguishes itself from sibling tools by focusing on Polymarket bet research, which no other sibling does.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides classifiers and fan-out examples but does not explicitly mention when not to use it or alternative tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal-year handling, sorting by primary metric, and citation URIs, though it omits failure modes or rate limits.

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

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

The description is well-structured with trigger phrases first, then purpose, then details. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting. It lacks explicit mention of pagination or consistency guarantees, but is sufficient for a comparison tool.

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

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

Schema coverage is 100%, but the description adds significant value: explains type with data sources (company pulls financials, drug pulls adverse events), details values format (tickers/CIKs vs drug names), and confirms min/max bounds.

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

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

The description clearly states it compares 2–5 companies or drugs side-by-side, lists trigger phrases, and distinguishes from sequential single-entity lookups by saying 'replaces 8–15 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 when-to-use guidance ('ALWAYS PREFER over sequential single-pack lookups') and gives example queries, but does not explicitly state when not to use it (e.g., for single entities).

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral detail about return fields (resource_id, name, etc.) and a follow-up action (pass resource_id to query/metadata), which goes 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 concise sentences: first defines purpose, second details return values and usage hint. No fluff, 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?

The description fully covers the tool's functionality given rich annotations and complete schema. It explains the return data and next step, leaving no gaps for a search tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minimal extra meaning (e.g., 'keyword' for query) but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's action ('Search'), the resource ('Pennsylvania Open Data catalog of open datasets'), and the method ('by keyword'). It distinguishes itself from sibling tools by specifying a unique data source.

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 implicitly indicates when to use (when searching PA open data) but does not explicitly exclude other scenarios or mention alternative tools. It provides 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds substantial behavior: parallel decomposition, findings packet content with citations, explicit gaps[] rather than invented answers, contradictions[], semantic excerpting, expected latency, and depth-dependent follow-up hops.

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 information-dense, and the most critical operational facts (account requirement, alternative tool, non-open-web scope, expected time) appear early. It rambles somewhat with parenthetical examples, but each section contributes meaningful selection or behavioral detail for a complex tool.

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?

This is a complex tool with no output schema, yet the description covers authentication, fallback routing, input shape, output packet structure, citation resolvability, failure handling via gaps[], contradiction detection, latency expectations, and depth semantics. An agent has everything needed to invoke and interpret results.

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 well. The description adds value by explaining what each depth mode actually does operationally (quick=single hop, standard=gap recovery + contradictions, thorough=iterative lead-chasing) and by clarifying that broad multi-part questions are valid input.

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

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

The description states a specific verb and resource: grounded multi-source research across 1,517 structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell exactly what this tool is for.

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 gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and clearly instructs to use ask_pipeworx when not signed in or for a single lookup. This provides both positive and negative selection criteria against sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds that it returns ready-to-call schemas and is a discovery step, providing useful behavioral context beyond annotations.

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

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

Description is front-loaded with purpose, then use cases, then output summary. Dense but efficient; no wasted words. Could be slightly shorter but 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, but description fully explains what is returned (top-N tools with names, descriptions, schemas). Complete for a discovery tool.

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

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

Schema coverage is 100%, baseline 3. Description gives example queries but doesn't add significant meaning beyond what schema already provides.

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

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

The description clearly states the verb 'Find tools' and lists specific tasks (SEC filings, FDA drugs, etc.). It differentiates from siblings by stating to use this first when you have many tools, contrasting with direct query tools like 'query' 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?

Explicitly says to use when browsing or discovering tools and to call it first for overview. Lacks explicit 'when not to use' but the context 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?

Beyond the readOnly/idempotent annotations, the description discloses the parallel fan-out behavior, that sources_used/sources_failed indicate which sources actually returned data, that an empty section means real no-data rather than a bug, and that private companies return resolved:false with an explicit notes line. This is rich, useful 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 front-loaded with examples and the core promise, but it quickly becomes a dense run-on paragraph with corrupted-looking fragments in the return-field list. It would benefit from a structured list and significant trimming to make the valuable content easier to parse.

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

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

For a complex tool with no output schema, the description covers the essential invocation context: supported input shapes, name resolution, private-company failure semantics, return-field highlights, source-status reporting, and limit details like 'up to 5' filings. The garbled return list prevents a perfect score, but an agent still has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters; the baseline is 3. The description adds concrete examples ('AAPL', '0000320193', 'Moderna'), clarifies that type accepts 'company' and 'ticker' interchangeably, and explains SEC EDGAR name resolution, which is meaningful added 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 is explicit: it produces a 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete trigger examples like 'Tell me about X' and 'brief me on Tesla.' It also distinguishes itself from single-source lookups, so an agent can tell when this tool is the right one.

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 clearly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is an explicit when-to-use rule. It would be a 5 if it named specific sibling alternatives and gave a crisp contrast like 'use X for a single filing lookup.'

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so description's 'delete' aligns. Adds context about clearing sensitive data but not additional behavioral traits beyond annotations.

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

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

Two concise, front-loaded sentences. No redundant information. Every word adds value.

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

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

Complete for a single-parameter destructive tool. Covers purpose, usage, and sibling relationships. No gaps given annotations.

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

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

Only one parameter 'key' with schema description. Description does not add beyond schema, but schema coverage is 100%, so baseline 3 applies.

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

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

Clearly states deletion action on a memory by key, with specific verb and resource. Distinguishes from siblings 'remember' and 'recall' by explicitly pairing with them.

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

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

Explicitly states when to use: stale context, completed task, clearing sensitive data. No explicit when-not scenarios, but usage context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds operational steps (fetch, extract, emit) and output format, but lacks details on error handling or limits beyond schema.

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

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

Two sentences plus a use-case list, no redundancy. Every sentence adds value.

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

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

Despite no output schema, description explains output format and usage context adequately for a straightforward tool. Covers purpose, process, and practical applications.

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 semantic nuance beyond what schema provides for url and max_links, e.g., no clarification on URL validation or link selection criteria.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence which focus on analysis rather than file generation.

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 (client indexing, personal projects, competitor auditing) but does not mention when not to use or name alternative tools for related tasks.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds the return fields and usage context, which is valuable but not essential beyond annotations.

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

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

Two concise sentences with no waste. Front-loaded with action and resource, immediately followed by return fields and 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?

For a simple list tool without an output schema, the description lists all return fields and provides usage context, making it complete for the agent.

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

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

Schema coverage is 100% and the description does not add additional meaning to the parameter. The schema already describes 'include_inactive' as a boolean, which is sufficient.

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 'List' and the resource 'subscriptions of the caller', with specific return fields. It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on review.

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

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

Explicit guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't explicitly mention when not to use it, the context is clear given the sibling tools.

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

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

Annotations already provide readOnly, idempotent, and destructive hints. Description adds no further behavioral context (e.g., rate limits, auth). Bar is lower due to annotations, but no additional value.

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

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

Single sentence with example, front-loaded and 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?

Given one parameter and no output schema, description lists what the response contains (columns, types, row count, category, last-updated). Fully adequate.

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

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

Schema coverage is 100% with description for resource_id. Description essentially repeats the schema info. 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?

Clear verb (Get), specific resource (dataset schema+metadata), and example resource_id. Distinguishes from sibling tools like 'datasets' and 'query'.

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

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

Mentions using by resource_id with example, but no explicit when-to-use or alternative guidance. Usage is implied but not explicit.

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 important behavioral traits beyond annotations: rate-limiting ('Rate-limited to 5 per identifier per day'), free usage ('Free; doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later'), and the fact that the team reads digests daily with signal affecting roadmap. Annotations only provided hints about readOnly, openWorld, idempotent, and destructive; the description adds rich 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 dense paragraph that front-loads the primary verb and resource. It's verbose but every sentence earns its place—covering usage scenarios, exclusions, claim_token workflow, and rate limits. It could be slightly more structured with line breaks but remains readable and efficient.

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

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

Given the tool's complexity (4 params, nested context object, claim_token lifecycle, multiple feedback types), the description covers all essential aspects: what to do, what not to do, how the token works, rate limits, cost, and roadmap impact. No output schema exists, but the description adequately explains what happens when filing without an account and how to check status later. The sibling-tool context is also addressed by the explicit exclusion of other MCP servers.

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

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

Schema coverage is 100% and each parameter has detailed descriptions (type enum values, context subfields, claim_token usage). The description adds extra context for the claim_token parameter by explaining the lifecycle (file without account → get token → pass back later to read status). This goes beyond the schema's description, so a 4 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (send feedback). It also distinguishes from siblings by noting it's specifically for this connection's tools, not other MCP servers.

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

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

The description provides explicit when-to-use 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).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds caching duration (5min-1h), data source (CF analytics-engine), no-PII guarantee, and window behavior differences. No contradictions.

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

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

Three well-organized paragraphs with bullet points. Front-loaded with core action, then use cases, then implementation details. No redundant sentences; every line earns its place.

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

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

Given the tool's simplicity (1 param, no output schema), description fully covers return values, caching, use cases, and data origin. No gaps for an agent to safely invoke the tool.

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

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

Only one parameter (window) with enum and 100% schema coverage. Description adds meaningful interpretation: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enriching the enum values.

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

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

Clear verb ('Returns') and specific resources ('top tools, top packs, total call volume') with precise window options. Distinguishes from siblings by focusing on aggregated trending data, not individual queries or actions.

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

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

Explicitly lists three concrete use cases (discovering hot data, confirming canonical tool, aligning use case). Implicitly contrasts with sibling tools like `ask_pipeworx` (direct Q&A) and `query` (search), providing clear context for when to choose this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral details: how arbitrage detection works (date-axis/threshold-axis ordering, partition_sum≈1), semantic anchor and partition filter logic, and fill check with book depth. 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 comprehensive and well-structured, with clear sections and no wasted words. It is slightly long but justified by the tool's complexity. Could be slightly more concise, but it efficiently packs necessary detail.

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

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

Despite no output schema, the description fully specifies the response structure (opportunities[], partition_check, fill check fields). It covers parameters, usage modes, behavioral rules (semantic anchor, partition filter), and trade recommendations. Complete for a complex analysis 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%, and the description adds substantial meaning beyond the schema. It explains when to use each parameter, accepted formats (slugs or URLs), and what each mode returns, including examples and edge cases like skipped_low_similarity.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific purposes, which differentiates it from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It provides examples, recommendations, and a fill check warning not to trade when realizable_edge_pp ≤ 0.

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, openWorldHint, and destructiveHint false. The description aligns fully and adds context about caching (1h KV cache keyed on knobs), the rarity of concentrated longshots, and the 24h-move warning. No contradictions.

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

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

The description is lengthy and dense with technical details. While well-structured with clear segments, its verbosity may challenge conciseness; every sentence adds value, but a tighter version could improve readability.

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

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

Despite no output schema, the description fully explains the response structure: by_segment, fed_candidates, and diagnostics. It covers edge fields, knobs, and behavioral details, making the tool's output fully understandable 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?

Input schema has 100% coverage with detailed parameter descriptions. The tool description adds value by grouping parameters into 'tradeable-edge knobs' and explaining their system-level purpose, though the schema already provides solid semantics.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing the unique segmentation and data sources.

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

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

The description explains the tool is built for 'what should I bet on today' and how agents can use it without paging through markets. It provides explicit guidance on when to use tradeable-edge knobs and notes Fed bets are excluded from ranking, but doesn't explicitly state when not to use 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?

Annotations already declare read-only, idempotent, non-destructive. Description adds rich context: response structure with tracked/expired/snapshot_dates, limitations (60-day TTL, daily closes, no intraday). Goes well beyond annotations.

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

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

Well-structured: starts with purpose, details response fields, ends with limits. Dense with information; every sentence adds value. Slightly long but justified given no output schema.

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

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

Given no output schema, description thoroughly explains all response fields (tracked[], expired[], snapshot_dates[]) and covers limits and assumptions. Complete for a read-only telemetry 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 100%, so baseline 3. Description adds default values, clamp range, and explains window as 'snapshot family' with examples. Provides useful context 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 it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and trend. Distinguishes from sibling tool polymarket_edges which likely provides raw snapshots.

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

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

Explicitly says when to use: to know how long an edge has existed and if it's shrinking. Implicitly contrasts with single-snapshot analysis. Lacks explicit 'when not to use' but context is clear.

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

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

The description discloses critical behavioral traits beyond annotations: live order-book depth interaction, verdict categories (clean|degraded|cannot_fill), and forced directional risk details. Annotations already mark the tool as read-only, idempotent, and non-destructive; the description reinforces safety and adds context about edge cases (e.g., thin_legs). 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-organized: first sentence states purpose, then mode-specific details in logical sequence. It covers all necessary information without redundancy. A minor improvement could be briefer mode descriptions, but the clarity gained justifies the length.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It explains all return objects (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_clean_notional_usd, forced_directional_risk, etc.) and covers edge cases (thin_legs, strand risk). No output schema exists, so the description fully compensates.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: explains default values (size_usd=1000), interpretation in basket mode ('settlement notional — shares per leg'), auto side detection logic, and clamping range. This extra context justifies a score 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 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, specifies the return values (e.g., top_of_book, verdict), and differentiates from siblings by explaining its role as a pre-trade safety check for polymorphic arbitrage and edge tools.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to use it (e.g., theoretical overround on thin books not capturable) and warns of risks like partial basket fills converting arbs into unhedged positions, which directly helps the agent decide when to invoke.

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 this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: Kalshi fees are explicitly not modeled, spreads are gross rather than net tradeable edge, temporal_alignment null "means it could not be computed... not that the two sides align," and incompatibility codes are described in detail. It also discloses the matching method and that legs with unknown metric_type are never paired. This far exceeds the annotation baseline.

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

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

The description is front-loaded with the core purpose, but it is extremely long and somewhat repetitive: safety codes are enumerated, then the same flags appear again in the top_spreads_pp explanation, and temporal-alignment caveats are restated. Each detail is individually useful for this complex tool, so it is not egregiously wasteful, but several sentences could be condensed 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?

There is no output schema, so the description carries the full burden of explaining the response shape — and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment, fees_note, and skip counters. For a tool with this many edge cases and no output schema, the description is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it lists every valid topic, explains that explicit tickers override the topic-mapped side, and clarifies that both modes run the same token-overlap matcher. It could be stronger by stating what happens when both `topic` and an explicit parameter are provided, but overall it enriches 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 first sentence names the resource precisely: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It also clarifies scope by saying the spread only means something "when the bet shapes are equivalent." It does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so it misses the full sibling-differentiation bar.

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 clearly explains the two invocation modes — pre-mapped `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug` — and says both run the identical matcher. It gives practical context such as "pre-mapped ≠ tradeable" and warns that most topics return compatibility warnings. It does not explicitly state when to prefer a sibling tool, so it stops short of full exclusion guidance.

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

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

The description adds value beyond annotations by stating that the tool returns matching rows as JSON and mentions the default limit of 1000 from Socrata. This complements the readOnlyHint, idempotentHint, and destructiveHint annotations.

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

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

The description is very concise, using two sentences to convey the core purpose and key usage notes. It is front-loaded and efficient.

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

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

Given the complexity of SoQL queries and the fact that all parameters are fully documented, the description provides sufficient context for an agent to use the tool correctly, including the return format.

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

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

Schema description coverage is 100%, and the description adds further clarity by explaining that SoQL clauses should be used without the leading $ and that limit/offset control pagination. Examples in the schema enhance understanding.

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

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

The description clearly states the tool runs a Socrata SoQL query against a specific dataset by resource_id, using a specific verb and resource. It distinguishes itself from sibling tools by specifying the data source (Pennsylvania Open Data) and the query language (SoQL).

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

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

The description provides clear context for when to use the tool (to query a specific dataset with SoQL clauses) and notes that clauses should be without the leading $. However, it lacks explicit exclusions or alternatives, though the sibling tools are functionally distinct.

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, destructiveHint. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and pairing with siblings, going beyond annotations without contradiction.

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

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

Two sentences, front-loaded with core purpose, no wasted words. Every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, read-only), with annotations covering safety, the description fully addresses what an agent needs: purpose, usage, scoping, and relationship to siblings.

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

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

Schema coverage is 100% for the single parameter 'key'. The description explains that omitting key lists all keys, adding semantic meaning not present in the schema's description.

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

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

The description clearly states it retrieves a value saved via remember or lists all keys when key is omitted. It distinguishes itself from siblings remember (save) and forget (delete) by explicitly pairing with them.

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

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

Provides explicit when-to-use (look up context stored earlier) and when-not (omit key to list all). Mentions pairing with remember/forget and scoping by identifier, offering clear guidance on alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds details on return fields (source, citation_uri, payload) and mark_read behavior, which supplements transparency 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?

Single paragraph, front-loaded with purpose, every sentence adds meaningful information with no redundancy or fluff.

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

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

Covers return structure, parameter usage, and alternative access method. While missing explicit pagination details beyond limit, the description is sufficiently complete for a read-only polling tool with no output schema.

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

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

Schema descriptions cover 100% of parameters, but description adds value by providing examples (e.g., 'sec_8k' for type) and explaining mark_read purpose, exceeding baseline level.

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

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

The description starts with 'Pull fired events from your subscription feed,' which clearly states the verb (pull) and resource (events). It distinguishes itself from siblings like list_subscriptions by specifying it returns fired events, not subscriptions.

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

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

Provides guidance on filtering by type and/or since, and explains the mark_read option for incremental polling. Mentions an alternative REST endpoint for scripts/dashboards, but lacks explicit exclusions compared to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO (soft-fail until May 2025), and return structure with grouped changes and citation URIs. 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 efficiently structured: starts with common query patterns, then the technical summary, fallback behavior, parameter details, and return structure. Every sentence adds information without redundancy.

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

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

Despite having no output schema, the description adequately describes the return format (changes[] grouped by source, total_changes count, citation URIs). The tool is moderately complex (multi-source, conditional fallback), and the description covers all relevant aspects for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value beyond schema by clarifying the `since` shorthand formats (e.g., '7d', '30d'), the ticker/CIK formats for `value`, and the USPTO soft-fail behavior. This extra context justifies a 4.

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

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

The description starts with concrete query examples ("What's new with X", "latest on Y") and immediately states it's a change feed for a company. It explicitly distinguishes itself from sibling tool `entity_profile` by specifying when to use each, making the purpose crystal clear.

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

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

The description provides explicit guidance on when to use this tool (for change feed over a window) and when to use `entity_profile` instead (for static profile regardless of window). It also includes example queries and acceptable `since` formats, leaving no ambiguity.

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

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

Adds behavioral context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations indicate idempotent and non-destructive, which description does not contradict.

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, front-loaded with purpose and usage. No redundant information; each sentence adds value.

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

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

Complete for a simple write tool without output schema. Covers purpose, usage, scoping, persistence, and pairing with siblings.

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 does not add additional meaning beyond what schema provides, so baseline 3.

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

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

Description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from siblings by mentioning pairing with '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.' Provides context for usage but does not explicitly list when not to use or alternatives beyond recall/forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond that: it explains graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI is down), cascading internal lookups, ambiguous-match behavior (returns `figi_candidates` and asserts nothing), and explicit `unresolved` listing for missing identifiers. These are non-obvious behaviors an agent must know, and they are not present in annotations. No contradiction.

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

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

The description is long, but it is front-loaded with examples and structured into a clear flow: usage phrasings, 'Use FIRST', supported types with detailed behaviors, and graceful-degradation notes. Every sentence adds operational value for a complex tool. It is not tautological or wasteful, though it could be tightened slightly without losing meaning. A 4 reflects that it's appropriately sized for the complexity but not minimal.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, edge cases like non-equity instruments and ambiguous names), the description is remarkably complete. It covers what happens on unmatched names, multiple matches, unavailable external sources, and the exact format for bond issuers. Nothing an agent needs to call this tool correctly is missing, and it even provides background on why certain behavior is correct.

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

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

Schema coverage is 100% (both parameters described), so the baseline is 3. But the description adds substantial meaning: for `value`, it clarifies that a bond's value should be the issuer exactly as printed, not the full noun phrase, and that an ISIN resolves to the legal entity. For `type`, it explains the exact identifier sets each type returns. This goes far beyond the schema's simple enum, guiding correct input formatting.

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 phrasings ('What's the ticker for…', 'find the CIK for…') and states the core purpose: resolving a name to canonical identifiers other tools require. It names the specific identifier types per entity type (CIK, ticker, LEI, FIGI for company; RxCUI for drug) and explicitly says 'Use FIRST whenever you have a name but need an ID', which clearly differentiates it from siblings like entity_profile or compare_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?

It gives a crisp rule: 'Use FIRST whenever you have a name but need an ID.' It also explains when to choose company vs. drug and warns against passing full noun phrases for bonds. It doesn't name specific alternative tools, but the 'use FIRST' instruction is strong enough to route an agent, and it notes that the tool replaces 2-3 manual lookups, clarifying its role in the workflow.

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

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

Annotations already indicate safe, non-destructive, and idempotent behavior. The description adds valuable behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns per-entity score, confidence, and signal density. No contradictions with annotations.

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

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

The description is a single well-structured paragraph covering purpose, process, use case, and output. Every sentence adds value without redundancy.

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

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

Given the complexity (4 params, no output schema, many siblings), the description is sufficiently complete. It explains the ranking logic, return fields, and gives a concrete example. The output is well-described despite no formal output schema.

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

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

Schema coverage is 100% with good descriptions. The description adds extra semantics beyond schema, such as the first entity being treated as the 'subject' and the default for models. It also clarifies that context disambiguates common 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 clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes itself from siblings like ai_visibility_check by focusing on multiple entities and producing a ranked list.

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

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

The description provides a specific use case ('competitive AI-marketing audits') and an example question. It implies the tool is for multi-entity comparison, but does not explicitly state when to use alternatives like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds value by mentioning partial failures degrading gracefully, the timing caveat for bundlephobia's first measurement (5-30s), and the sources_failed field. This provides useful behavioral context beyond annotations.

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

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

The description is informative and front-loaded with the composite purpose. However, it is somewhat dense with technical details, which slightly reduces conciseness. Still, every sentence adds value, and it is 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?

Despite no output schema, the description thoroughly details the return values (summary block, per-advisory detail, links, alternative versions) and partial failure behavior. This is complete for a tool of 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% with descriptions for both parameters. The description adds context about scoped packages being accepted and version defaulting to latest, but this aligns with schema descriptions. With high schema coverage, the baseline is 3, and the description adds minimal extra meaning.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, including license, advisories, version history, and bundle size. It differentiates from siblings by focusing on npm and the specific use case of evaluating an npm package's safety, popularity, or size.

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 usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies ecosystem limitation (NPM only in v1) and mentions alternatives for other ecosystems, providing clear guidance on when 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds critical behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K), truncation flagging. 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?

5 sentences, front-loaded with purpose and usage. Every sentence adds meaningful information: use case, pairwise alternative, technical details, limitations. No superfluous 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, description explains return values: 'top-N passages with character offsets and similarity scores.' Covers limitation (200K char cap, truncation flagged). Sufficient for an agent to understand input, behavior, and 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% (all 3 parameters described in schema). Description enhances with examples for query (e.g., 'supply-chain risk', 'drug interactions with warfarin'), explicit range for limit (1-20, default 5), and constraint for text (max ~200K chars). 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?

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb (search) and resource (inside a record). It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and implying it's not for fetching whole documents.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt.' Also provides alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both usage context and exclusion criteria.

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 non-readOnly and non-destructive. The description adds behavioral context: OAuth requirement, type-specific parameter formats, delivery channel details including webhook signing and auto-disable, and the always-on feed. It covers most relevant behaviors 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 lengthy but well-structured, front-loading the main action and then detailing types and delivery in the same paragraph. Every sentence adds value, though it could be slightly more concise 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?

Given the tool's complexity (multiple types, delivery channels, prerequisites), the description covers all critical aspects: OAuth requirement, type-specific params, delivery options with rate limits, webhook details. It lacks error handling or subscription lifespan info, but is adequate for agent use. No output schema, but return value is stated.

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

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

Schema coverage is 100%, but the description enriches each parameter with concrete examples and constraints (e.g., sec_8k items codes, polymarket_edge topic, SMS phone verification, webhook HMAC signing). This far exceeds the schema's bare descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create) and resource (subscription), and distinguishes it from siblings like unsubscribe and list_subscriptions.

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

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

The description provides explicit prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also details delivery options and rate limits (SMS 10/day cap), implied usage context for each type. However, it does not explicitly contrast with alternative tools for managing subscriptions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds context about the return format (category-bucketed examples with tool+argument shapes) and argument behavior, aligning with annotations. No contradictions.

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

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

The description is detailed and well-structured, front-loading common user questions. While comprehensive, it could be slightly more concise without losing 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?

Despite lacking an output schema, the description sufficiently explains the return format (categorized examples) and covers the primary use case. Could mention that results are illustrative, but it is complete for a discovery tool.

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

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

Schema coverage is 100% with one optional parameter. The description explains the single parameter 'topic' with examples and clarifies behavior when omitted (full spread). Adds significant meaning beyond the schema, which only provides a terse description.

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

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

The description clearly defines the tool as an onboarding entry point for new users to discover what Pipeworx can do, returning categorized example questions with tool calls. It distinguishes itself from sibling tools like ask_pipeworx by focusing on discovery rather than answering specific queries.

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 to use this 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context, but does not explicitly exclude scenarios where the user already knows what to ask, which could improve 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 idempotentHint=true and destructiveHint=false. The description adds context that the row is deactivated (not deleted) and historical events stay available, which clarifies the non-destructive mutation behavior beyond the annotations.

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

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

Two sentences with zero fluff. First sentence states the action, second adds constraints and side effects. Efficient and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership constraint, row status, and mentions related tool (recent_alerts). Complete and informative.

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 description for 'id' already explaining it's a uuid from subscribe. The description does not add further parameter meaning.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription identified by id). It differentiates from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), which provides a clear usage constraint. However, it does not explicitly state when not to use or compare to alternatives.

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

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

Goes far beyond the readOnly/idempotent annotations by explaining the SEC EDGAR fast path vs. grounded pipeline, the full verdict vocabulary, and critical semantics of could_not_verify and unsupported. It also discloses that could_not_verify means the check did not happen and must not be treated as evidence, which is crucial 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 dense but every part serves a purpose: user-phrase examples, use-case trigger, internal routing, return format, and failure-mode caveats. It is front-loaded with the intent phrases and maintains readability, though it is somewhat long and could be trimmed without losing essential 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?

Despite no output schema, the description fully accounts for return values (verdict, value, citation, reasoning), error semantics, and the two execution paths. It even emphasizes the absence of coverage for unsupported claims. Given the tool's complexity, the description covers all necessary context and eliminates ambiguity for the agent.

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

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

The input schema already covers both parameters with descriptions, so the baseline is 3. The tool description adds valuable nuance, especially for tolerance_pct, explaining how it overrides implied tolerance and recommending values for hallucination detection, which is more than a restatement of 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 opens with concrete user-phrase examples and explicitly states 'natural-language claim verification against authoritative sources,' giving a specific verb+resource+scope. It clearly distinguishes itself from general querying by focusing on fact-checking claims with structured verdicts, and even notes it 'Replaces 4–6 sequential calls,' setting it apart from siblings.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives a clear trigger. It outlines internal routing for financial vs. other claims but does not explicitly name alternative sibling tools or provide when-not-to-use exclusions, stopping short of a 5.

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