Bis

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

Annotations already declare this as read-only, idempotent, non-destructive, and open-world. The description adds operational behavior: it calls external LLMs, the default model is free (Workers AI Llama-3.3-70b), and using Anthropic requires the user's API key and direct payment, which is beyond the basic annotation.

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

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

Three sentences, front-loaded with the core purpose, then key operational details and use cases. No wasted words; each sentence provides 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 covers the purpose, supported models, API key requirement, return format, and use cases. With no output schema, it adequately describes the per-model response structure, making the tool's behavior predictable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning to `_apiKey` by explaining its purpose (BYO key, direct charge) and clarifies the default model for the `models` parameter (free if omitted), which adds value beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('Probe') and resource (LLMs), and uniquely positions it as a visibility scorer (0-100) across models, distinguishing it from siblings like ask_pipeworx or compare_entities. The scope (business/brand/product/topic) and output shape add specificity.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass `_apiKey` for additional models. It doesn't explicitly exclude alternatives or name sibling tools, but the context is sufficient for an agent to decide.

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 convey read-only, non-destructive, open-world, and idempotent behavior. The description adds meaningful behavioral detail: it routes to 5,529 tools across 1,455 sources, fills argument lists automatically, and returns structured answers with pipeworx:// citation URIs. It does not disclose failure modes or latency, but overall goes beyond annotation coverage.

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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and remains information-dense throughout. Examples and explicit sibling-tool comparisons earn their place, though some redundancy exists (e.g., 'default entry point' and 'one fast call' repeat earlier points).

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

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

With no output schema, the description compensates by stating the return format (structured answer with stable citation URIs). It covers when to use, when to step up to alternatives, and provides representative examples. It lacks commentary on limitations or failure cases, but for a read-only query tool with rich annotations and schema, it is substantially 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%: the single required parameter 'question' and its aliases are fully documented in the schema. The description adds useful examples and clarifies natural language acceptance, but it does not need to compensate for missing parameter docs. Baseline of 3 is appropriate.

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

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

The description explicitly states what the tool does: answer factual questions using structured data from many sources. It provides concrete domains (SEC filings, FDA, FRED, patents, etc.) and examples, and clearly distinguishes this tool from ask_pipeworx_grounded and deep_research by naming exact alternatives.

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 tool is unambiguously positioned as the preferred default over web search, with trigger phrases ('what is', 'look up', 'get the latest'), explicit 'START HERE' guidance, and step-up alternatives with names and use cases. It also explains when to use ask_pipeworx_grounded vs deep_research, making selection straightforward.

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 (readOnly, openWorld, idempotent), the description adds critical behavioral context about the experimental nature: 'candidate routing improvements enabled live whenever one is under test' warns that behavior may change dynamically. It also clarifies the current state (no active candidate) and confirms it is a full working router with no fallback, providing transparency about reliability.

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

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

The description is concise and front-loaded, starting with 'Beta version of ask_pipeworx.' Three sentences cover key points: identical interface, experimental routing, current state, usage, and a reassurance about functionality. Every sentence earns its place with no wasted words.

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

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

For a router tool with rich annotations and a schema covering aliases, the description is complete. It explains the current experimental status, usage guidance, and points to the stable sibling for response shape. It does not need to enumerate all 5,529 tools; the universal router concept and explicit relationship to ask_pipeworx suffice.

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 provides 100% coverage with descriptions for all parameters, including aliases. The description adds no extra semantic information about parameters, only referring to 'same arguments' as ask_pipeworx, which the schema already clarifies. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as 'Beta version of ask_pipeworx' and explains it is an identical universal router with 5,529 tools, same arguments, and same response shape. This verb+resource+scope formula distinguishes it from the stable sibling ask_pipeworx by framing it as the experimental edge.

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

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

It explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that currently no candidate is active, so it matches ask_pipeworx exactly, which guides the agent in comparing alternatives. This is clear, actionable usage guidance with an implied alternative.

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

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

The description goes well beyond annotations by explaining the grounding process, the return structure (including evidence as verbatim quote), and explicit refusal reasons (not_in_source, no_tool_match, etc.). It also discloses the added cost of one extra LLM call. Annotations are readOnly/idempotent/openWorld, and the description does not contradict them.

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

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

The description is concise given the complexity, with each sentence earning its place: purpose/mechanism, return structure, and usage guidance. It is front-loaded with the key differentiator and avoids 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?

Even without an output schema, the description fully explains success and refusal return values, the reasoning for refusals, cost trade-offs, and appropriate use cases. It is complete for an agent to invoke correctly and interpret outcomes.

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 six parameters documented as aliases for the question. The description adds no extra parameter detail beyond the schema's existing definitions, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that extracts answers only from tool results, distinguishing it from sibling ask_pipeworx by its grounded behavior and refusal mechanism. It has a specific verb ('extracts') and resource ('tool result'), making its purpose 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?

Explicit guidance is provided: use for high-stakes reads where answers may be quoted/cited/acted on, and prefer ask_pipeworx for casual lookups due to extra LLM cost. This directly addresses when to use vs. 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?

This description goes far beyond the annotations. It discloses resolver confidence behavior (market_match_confidence, alternatives, suggestions), short-circuit statuses for low-confidence or closed markets, wide-spread tradeability flags, parent-event extraction, and cancellation-rule risk handling (refund_50_50, etc.). It even warns about 24h market moves relative to model edge. All this adds substantial operational context beyond the basic readOnly/idempotent hints.

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 extremely information-dense, with UPPERCASE headers (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) that aid scanning. It is front-loaded with the core purpose and each section earns its place by revealing critical behaviors. A few sentences could be tightened, but overall it is appropriately organized 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?

Given that there is no output schema, the description compensates remarkably by detailing response shapes (result.market, result.analysis, result.evidence), keyed evidence, parent_event output, news fallback fields, and status/blocking routes. It also covers safety and resolution-rule risk for sports/event bets, making it complete for the tool's complexity and parameter count.

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

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

The schema already documents all three parameters (market, depth, include_raw) with 100% coverage, so the baseline is 3. The description adds meaningful semantic depth for the 'market' parameter by explaining the resolver contract, match scoring, alternatives, and suggestion outputs, and it illustrates depth with fan-out examples. It does not add details about include_raw, but the schema covers it well.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by framing the tool as a comprehensive one-call research aggregator (e.g., fan-out to category-specific data packs) and explicitly lists use cases like 'should I bet on X' and 'is there edge in Z', which sets it apart from narrower tools like polymarket_arbitrage or validate_claim.

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 use cases ('Use for "should I bet on X", ...') and gives numerous fan-out examples (BTC, Fed, Hormuz, Yankees, etc.), which effectively communicate when to apply the tool. It does not explicitly state exclusions or name alternative siblings for when not to use it, but the context is strong enough to guide an agent.

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 (read-only, idempotent), the description discloses data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, handling of off-calendar fiscal years, and the inclusion of pipeworx:// citation URIs. This is rich operational insight.

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

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

The description is dense but not verbose. It front-loads with trigger phrases, uses bullet-like clarity, and every sentence adds information. The "Replaces 8–15 sequential lookups" is a helpful efficiency note, not 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?

With no output schema, the description still explains what the return contains: "paired data + pipeworx:// citation URIs per entity." It covers inputs, outputs, data sources, sorting, and scope (2-5 entities), making it fully usable by an agent.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by explaining type-specific behavior ("type='company' pulls LATEST 10-K...", "type='drug' pulls FAERS...") and gives concrete examples for values (AAPL, MSFT, ozempic, mounjaro), enhancing schema meaning.

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

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

The description opens with explicit trigger phrases ("Compare X and Y", "X vs Y") and a clear statement: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It names the resource (companies/drugs) and verb (compare), and distinguishes itself from single-pack lookups.

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

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

States "ALWAYS PREFER over sequential single-pack lookups when comparing entities," giving explicit when-to-use guidance and implying when not (single entity comparisons). It also clarifies the two input types (company vs drug) and what each pulls.

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 extensive behavioral context beyond this: account/paid-tier requirements, decomposition pipeline, findings packet contents (verbatim evidence, confidence, source, fetched_at, citation), explicit gaps[] never invented, contradictions[] for standard/thorough, hop field, fetchable citation_uri, semantic excerpting, and expected latency. 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 long but information-dense, with a logical flow from account requirements to usage guidance to output details. Every sentence adds a distinct piece of information, but the wall-of-text format could be slightly better structured with paragraphs or bullets. It earns a 4 for being thorough yet front-loaded.

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

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

Despite no output schema, the description fully explains the return packet (evidence, confidence, source, citation, gaps, contradictions, hop, citation_uri) and operational details (timing, excerpting). It covers account prerequisites, alternatives, and limitations. Given the tool's complexity, the description is highly complete and leaves few open questions.

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 goes well beyond the schema by explaining the depth enum semantics in detail (quick=3 facets single-hop, standard=5 with gap-recovery + contradictions, thorough=8 paid with iterative hop + contradictions). It also clarifies that the question parameter accepts broad/multi-part natural language, which is useful guidance.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, decomposing questions into facets and routing to 5,529 tools in parallel. It also distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and comparing to 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: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx' and for breaking/current-news topics, prefer ask_pipeworx because deep_research returns empty gaps. It also notes account requirement and the fallback to ask_pipeworx if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral detail about the return: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output format and guarantees of the tool 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 front-loaded with purpose and usage, followed by return details and a priority instruction. It is three sentences, efficient in conveying a lot of information, though the middle sentence is long and packed with a domain list. Overall, it is appropriately sized and well-structured.

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

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

Given the tool's purpose (discovering tools) and the absence of an output schema, the description is complete. It covers what the tool does, when to use it, what it returns (top-N tools, schemas, examples), and that results are directly callable. The list of domains provides a concrete scope, and the 'Call this FIRST' instruction establishes operational context.

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

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

Schema coverage is 100% (all parameters documented), so the description does not need to compensate. The description's mention of 'describing the data or task' aligns with the query parameter's schema description but adds no additional semantics beyond what the schema already states. The alias parameters (q, task, search, description) are clearly documented in the schema.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It identifies the resource (tools), the action (discover/look up), and the method (describing data/task). It also lists specific domains, making the scope concrete, and differentiates from sibling tools by framing it as a meta-tool for discovering other tools rather than performing a domain-specific task.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This establishes when to use the tool and hints at when not to (when seeking a single answer), though it does not name specific 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 the readOnlyHint/idempotentHint annotations, the description discloses multi-source fan-out, specific output contents, a GDELT→GNews fallback for news, and the USPTO patents sunset (soft-fails until reactivated). This is substantial added context with 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 longer than typical but every sentence is informative, covering use cases, data sources, return fields, and caveats. The front-loaded query examples improve scannability, though the stream-of-consciousness style could be tightened.

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 enumerates the composed fields (cik, recent_filings, fundamentals, patents, news, LEI) and mentions pipeworx URIs. It also handles edge cases (names unsupported, patent sunset) making it complete for a complex multi-source tool.

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

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

Schema coverage is 100% with descriptions for both type and value. The description reinforces the value format with examples ('AAPL' or zero-padded CIK) and explicitly notes names are not supported, adding nuance beyond 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 defines the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources and return fields, distinguishing it from siblings like resolve_entity (which handles names) and single-pack lookups that would need chaining.

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 provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also instructs users to call resolve_entity first if only a name is available, and warns about the patents API sunset with soft-fail behavior.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: unbounded requests can time out on large flows, and start_period/end_period should always be passed. This goes beyond annotations by flagging performance risk and a mandatory usage constraint.

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 compact: a one-line purpose, two concrete examples, a key-format explanation, and a critical performance warning. Every sentence provides distinct value, and the information is front-loaded. No filler.

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

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

With an output schema present, return-value details are unnecessary. The description covers purpose, parameter usage, examples, required periods, and a timeout warning, plus pointers to sibling discovery tools. It is complete for a read-only fetch tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by giving real-world flow_ref examples, explaining the key string as a dot-separated dimension filter with an example, and listing accepted period formats. This exceeds the schema's basic descriptions, though some parameters (limit) are left to 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 'Fetch tidy rows from a BIS dataflow,' which is a specific verb+resource statement. Concrete flow_ref examples and mention of sibling tools (list_curated_flows, search_dataflows) distinguish this fetch operation from discovery-oriented 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 clear context: use this to retrieve rows from a known dataflow, and consult list_curated_flows or search_dataflows to discover flows. It also gives explicit guidance on the key format and the necessity of start_period/end_period. It stops short of explicit 'use X when Y / don't use when Z' exclusions, but the usage context is well implied.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive mutation. The description adds use-case context and confirms the key refers to a previously stored memory, but it does not add details about irreversible deletion or behavior on non-existent keys, which the idempotentHint annotation vaguely covers.

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

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

The description is two succinct sentences, front-loaded with the action verb, and each clause serves a purpose: defining the operation, providing usage triggers, and pointing to related tools. No unnecessary information.

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

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

For a one-parameter destructive tool with annotations covering idempotency and destructiveness, the description supplies the essential context: what it deletes, when to use it, and related tools. It does not mention the return value or what happens on missing keys, but these are less critical given the minimal schema and 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?

Schema description coverage is 100% ('Memory key to delete'), so the schema fully documents the 'key' parameter. The description adds no new parameter semantics; it only restates 'by key', which the 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 uses the verb 'Delete' and identifies the resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall. It is specific and unambiguous about the operation.

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

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

The description explicitly states when to use the tool ('context is stale, the task is done, or clear sensitive data') and names related tools (remember and recall) as alternatives. It does not explicitly say when not to use it, but the guidance 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?

The description explains the processing steps (fetch, extract, emit) and the output format ('single text blob ready to drop at site-root/llms.txt'). Annotations already declare readOnly/idempotent/openWorld hints, so the added behavioral details about the pipeline and return value are valuable supplementary context without contradicting the annotations.

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

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

The description is three sentences: the first defines the tool's purpose, the second details the process, and the third lists use cases. It is front-loaded with the most important information and contains no fluff, achieving high density of useful information.

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

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

For a tool with only two parameters and no output schema, the description adequately covers the input (URL, optional link limit), the process, the output format, and representative use cases. It lacks only edge-case details like error handling or timeout behavior, which are not critical for this simple tool.

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

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

The input schema already provides comprehensive descriptions for both parameters (url and max_links) with 100% coverage. The description does not add new parameter semantics beyond the schema, but it does reinforce the 'any URL' and 'extracts key links' concepts. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It uses specific verbs and nouns (generate, fetches, extracts, emits) and explicitly mentions the output format, distinguishing it from sibling tools that focus on AI visibility checks or competitor scanning.

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 concrete use cases ('getting a client's site indexed, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor') which clearly indicate when to use this tool. It does not explicitly exclude alternatives or mention sibling tools, but the guidance is sufficient for most scenarios.

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, and non-destructive behavior. The description adds relevant context about pre-vetted content and topic grouping, which goes beyond the annotations. It doesn't mention pagination or return format, but this is covered by the output schema and the low-risk nature of the tool.

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 tight sentences front-load the purpose, list topics, and provide usage directions. Every word earns its place; no fluff or redundancy.

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

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

Given the simple input schema, an output schema, and annotations that cover safety, the description fully covers what the tool does, how to use it, and when to use alternatives. No gaps remain.

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

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

The schema describes the 'topic' parameter as an optional filter, and the description enriches this by enumerating valid topic values (rates, fx, banking, etc.). This adds meaningful semantic value beyond the schema's generic description.

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

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

The description clearly states the tool lists pre-vetted BIS dataflow refs grouped by topic, with explicit topic examples. It differentiates from siblings by directing users to use fetch_dataset with the flow_ref and search_dataflows for everything else.

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

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

Provides explicit usage guidance: use the flow_ref with fetch_dataset, and for everything else use search_dataflows or browse stats.bis.org. This clearly delineates when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known safe and non-mutating. The description adds value by clarifying the caller scope ('the caller's') and listing the returned fields, which helps the agent understand what information to expect.

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. The first states the action and scope, the second lists return fields and provides usage context. No filler or redundant information.

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

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

For a simple read-only listing tool, the description covers purpose, target audience (caller), output fields, and intended use cases. No output schema exists, but the return fields are enumerated, making the tool behavior well-understood.

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

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

The schema fully describes the only parameter, include_inactive, with a clear description and default. The tool description does not add additional parameter-level detail, but schema coverage is 100%, so the 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 opens with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions for review or cancellation.

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.' This tells the agent when to invoke this tool relative to subscribe and unsubscribe.

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

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

Annotations are minimal (all false), so the description carries the behavioral burden and does so thoroughly: it discloses rate-limiting (5/day), free usage/no quota, the anonymous claim_token workflow, and that feedback is read daily and affects roadmap. 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?

Though longer than two sentences, every clause serves a purpose: usage boundaries, phrasing guidance, claim-token workflow, rate limits, and cost. The main purpose is front-loaded, and there is no filler or redundancy.

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

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

The tool has a nested context object and no output schema, but the description fully explains how to file, how to follow up anonymously, and what happens to the feedback. It also covers exclusions and practical constraints, making it complete for accurate invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value by explaining that claim_token must be passed with no other arguments to read a previous reply, that filing without an account returns a token, and that message should be tool-specific. This goes 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?

The first sentence gives a concrete action and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further distinguishes this from sibling research/discovery tools by listing specific feedback categories and scoping it to Pipeworx 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?

Provides explicit when-to-use guidance via bug/feature/data_gap/praise categories, and explicit when-not-to-use guidance: do not report issues for tools from other MCP servers. It also tells users how to phrase feedback and how to follow up with a claim_token.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is a self-aggregating signal from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes well beyond the annotations.

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

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

The description is concise and front-loaded with a clear hook, followed by concrete return values, use cases, and relevant caveats. No wasted sentences; every part 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 having no output schema, the description sufficiently explains what the tool returns (top tools, top packs, call volume) and key context (caching, PII, derivation). The tool is simple with a single optional parameter, so this is complete for agent selection and invocation.

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

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

The only parameter (window) is fully described in the schema with enum values and meaning (shorter vs longer windows). The description mentions the window options but does not add much beyond the schema's 100% coverage, so the 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 uses a specific verb ('Returns') and clearly identifies the resource: top tools, top packs, and total call volume from other AI agents. It distinguishes itself from siblings like discover_tools by focusing on aggregate trending usage rather than tool discovery.

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

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

Provides explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. However, it does not mention when not to use it or name alternative tools, so it stops short of a full 5.

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?

Despite annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context: fill check limitations ('realizable_edge_pp ≤ 0 means... do not trade it'), similarity thresholds (≥0.30 Jaccard), placeholder filters (>20% placeholder fraction), and response fields. No contradictions with annotations; the description significantly deepens understanding of tool behavior.

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 every sentence carries operational weight: mode selection, thresholds, response structure, fill-check limitations, and cross-references. It is front-loaded with the main purpose, then organized into clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). No filler or tautology.

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 arbitrage tool with no output schema, the description is exceptionally complete. It enumerates response fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check), explains failure conditions (skipped_low_similarity, placeholder filters), and describes edge cases like last-trade vs book liquidity. This equips an agent to invoke the tool correctly even without prior examples.

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% by definition (both properties have descriptions), but the tool description adds even more: mode-specific semantics, accepted input formats (full URLs accepted), example slugs, and why to choose each parameter. For instance, `event` is linked to 'partition_check' and `topic` to 'cross-event scan' with concrete seed questions, going well beyond bare schema text.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event vs topic) and differentiates from siblings like polymarket_fill_risk by mentioning custom sizing there. The purpose is unambiguous and actionable.

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: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also states exclusions ('skipped_low_similarity', 'placeholders dropped') and points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This fully contextualizes when to use this tool vs alternatives.

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

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

The description adds substantial behavioral detail beyond the readOnly/idempotent annotations: caching at KV level for 1h, diagnostics funnel counters to explain empty segments, per-leg favorite-longshot bias corrections, and a warning when recent price movement already exceeds the edge. This is exceptionally transparent. No contradiction with annotations found.

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

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

The description is lengthy and dense, containing a lot of specific parameters (e.g., per-sport alpha values) that may not be necessary for correct invocation. It is organized and front-loads the purpose, but it reads like a specification rather than a concise description. Some sentences could be trimmed without losing essential usage 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?

This is a complex tool with 9 parameters and no output schema. The description fully compensates by explaining the response structure (by_segment, fed_candidates, _diagnostics), edge fields, warnings, and knob behavior. It leaves little ambiguity about what the agent will receive and how to interpret empty segments.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining why min_kelly does not apply to partition_overround (parent-level Kelly is zero), the motivation for min_partition_leg_kelly, and the slippage default rationale (zero fees but 20-50bp typical spread cost). This compensates for any ambiguity in the schema alone.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings by detailing three response segments and the 'what should I bet on today' use case. This is unambiguous and unique.

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

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

The description states the intended use case ('Built for what should I bet on today') and explains tradeable-edge knobs, but does not explicitly name alternatives or when not to use this tool. It gives enough context for an agent to decide to use it, but could have explicitly contrasted with sibling tools like polymarket_arbitrage.

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?

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral context: snapshots are written on cache-miss, gaps mean no scan, history is bounded by 60-day TTL, and decay uses daily closes not intraday. This goes well beyond the annotations, disclosing important caveats.

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

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

The description is structured with purpose first, then args, then detailed RESPONSE and LIMITS sections. Although lengthy, every sentence earns its place, covering all essential aspects without redundancy. It is front-loaded with the core purpose and provides a clear roadmap for the reader.

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 an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and key metrics (trend, decay_pp_per_day, lifespan_days). It also addresses limitations and data collection behavior, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the 'days' parameter as lookback with a default of 14 and max 30 (though schema says clamp 2-30), and 'window' as the snapshot family with default '1wk'. It also explains how parameters affect the telemetry (e.g., window family), going slightly 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?

The description uses a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the key question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on persistence/decay rather than current edge values.

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: for assessing edge persistence and decay over time, with the example that a fresh wide edge differs from a 3-week-old wide edge. It doesn't explicitly name alternative tools or when-not-to-use, but the context is strong enough to guide selection.

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=true, idempotentHint=true, destructiveHint=false), the description discloses key behavioral traits: it requires one of market/event, walks the order-book ladder, returns a verdict, and warns that partial basket fills can strand the user unhedged. It also explains the interpretation of size_usd in each mode, giving a clear picture of what the tool does internally.

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 every sentence serves a purpose. It is front-loaded with the core function, uses clear uppercase labels for modes, and packs critical details without redundancy or filler. The structure is easy to scan despite its density.

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, many return fields, no output schema), the description fully covers what it does, what it returns, how it behaves, and when to use it. It even explains the risk of partial fills and thin legs, making it self-sufficient for an agent to invoke correctly.

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

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

Though the schema has 100% description coverage, the description adds crucial semantics: the REQUIRES one-of market/event constraint, side defaults and meanings, and the differentiated size_usd interpretation (max spend on buys, target proceeds on sells, settlement notional in basket). This goes far beyond the schema's basic descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely states the tool's function and resource. It explicitly details two modes (SINGLE-MARKET and BASKET) and returns, clearly distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert an arb into unhedged directional risk), making it unambiguous when to use this tool versus alternatives.

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

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

The description extensively discloses behavior beyond annotations: it explains the compatibility_warning logic, temporal_alignment field, skipped_cross_type/subtype counters, and what aligned:false means. It also clarifies that non-equivalent bet shapes mean no arbitrage exists. These details are not visible in the annotations (readOnlyHint, idempotentHint) and significantly enrich the agent's understanding of edge cases. No contradictions with annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is lengthy but each paragraph adds necessary caveats. Minor redundancy exists: the macro shortcut list is repeated in both the description and the schema, but this is a minor issue given the overall quality.

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

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

With no output schema, the description fully carries the burden of explaining return values. It details leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and skipped counters. It also covers limitations and caveats, making the tool's behavior clear for an agent. Given the complexity of cross-venue comparisons, this 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 description coverage is 100%, so the baseline is 3. The description adds semantic context by explaining the two modes: 'topic' as a shortcut and explicit kalshi_event_ticker/polymarket_event_slug as an override. This clarifies how parameters interact and are intended to be used, going beyond simple parameter descriptions.

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

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

The description opens with a specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's verb (spread calculation), resources (Kalshi and Polymarket), and scope. It also distinguishes itself from sibling tools like polymarket_arbitrage by specifying the cross-venue nature.

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 detailed usage guidance via TWO MODES, explaining when to use topic shortcuts versus explicit pairings. It also warns that pre-mapped topics often return compatibility_warning and are not automatically tradeable, informing users when to avoid relying on the shortcut. However, it does not explicitly compare itself to sibling tools (e.g., polymarket_arbitrage), so the 'vs alternatives' aspect is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: scoping ('anonymous IP, BYO key hash, or account ID') and the list-all behavior when key is omitted. This goes beyond the structured data, though it doesn't mention error handling or persistence details.

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

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

Three sentences, each earning its place: the first states the core function, the second explains the use case, and the third covers scoping and related tools. No filler or repetition of schema/annotations.

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 one-parameter read-only tool, the description covers purpose, usage, scoping, and sibling relationships. No output schema exists, but the return value (the saved value or key list) is obvious from the context. The description is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with the key parameter described, but the description adds crucial semantics: the key refers to a value 'previously saved via remember' and the omission behavior ('omit the key argument' to list all keys). This explains the parameter's purpose and special-case usage beyond the schema's simple 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 opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes the tool from siblings by naming remember (save) and forget (delete), making the retrieval purpose unambiguous.

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

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

The description explicitly states when to use: 'Use to look up context the agent stored earlier' and gives concrete examples like target ticker, address, research notes. It also contrasts with siblings by noting 'Pair with remember to save, forget to delete', providing clear usage boundaries.

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

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

Annotation Contradiction: Annotations declare readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which mutates state. This directly contradicts the read-only annotation. idempotentHint is also questionable with mark_read side effects.

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

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

Three sentences, front-loaded with the main purpose, and every sentence provides useful information: function, return shape, filters, mark_read behavior, and alternative access. 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?

Description covers what the tool returns (source, citation_uri, raw payload), how to filter, the read-flagging behavior, and provides an external endpoint for scripting. No output schema exists, so returning payload details is essential and handled well.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds value with a concrete type example ('sec_8k'), clarifies `since` as ISO timestamp, and explains the behavioral effect of `mark_read` on subsequent calls.

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

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

The description starts with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this from sibling tools like subscribe or list_subscriptions by focusing on retrieval of alert events from a persisted feed.

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

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

Provides clear usage context: 'Polls work fine' and notes the same feed is available at an HTTP endpoint for scripts/dashboards. It doesn't explicitly name sibling alternatives or exclusions, but the context is sufficient for typical use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds rich behavioral detail: fans out to multiple APIs, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, and the 'ONE parallel call' behavior. It also discloses the return structure, which is beyond what annotations provide.

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

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

The description is information-dense but every sentence earns its place: intent examples, source list, fallback logic, parameter syntax, return format, and an explicit alternative. There is no filler or repetition; the opening examples immediately ground the tool's purpose.

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

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

For a 3-parameter tool with no output schema, the description is remarkably complete. It specifies return shape (changes[] grouped by source, total_changes, citation URIs), behavior under edge cases (USPTO soft-fail), and the path to fetch static profiles. Nothing essential is missing.

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 three parameters are described), so the baseline is 3. The description goes further by explaining `since` with both ISO and relative shorthand examples ('2026-04-01', '7d', '3m'), interpreting `value` as ticker or CIK, and clarifying `type` is only 'company'. This adds contextual meaning that helps the agent select correct 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?

The description opens with concrete user intents ('What's new with X', 'latest on Y') and then precisely defines the tool as a change feed for a company over a time window in a single parallel call. It lists specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly differentiates from the sibling tool entity_profile, making its purpose unmistakable and distinct.

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

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

The description explicitly tells when to use the tool (for recent updates/news on a company) and when not to (use entity_profile for static profile). It also provides fallback logic (GDELT preferred, GNews when rate-limited/5xx) and parameter usage guidance for `since`. This is clear, actionable context with an explicit alternative.

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

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

The description extends beyond the annotations: annotations already indicate a write, idempotent, non-destructive operation. The description adds key contextual behavior: key-value storage scoped by identifier, authenticated persistence versus 24-hour retention for anonymous sessions, and cross-session reuse. No contradiction with annotations.

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

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

Two sentences, front-loaded with 'Save data,' and every clause earns its place: purpose, usage, storage mechanism, persistence, and relationship to sibling tools. No filler, no redundancy.

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

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

The tool is simple (2 params, no output schema), and the description covers purpose, when to use, storage details, scoping, and companion operations. The annotations cover safety profile. Nothing important is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds value by giving real-world key examples and clarifying that the key is scoped by the user's identifier, which helps agents understand key naming and namespace. Slightly above the baseline of 3.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It clearly distinguishes this tool from siblings by naming recall and forget as complementary operations, and provides concrete examples (resolved ticker, target address, user preference) that make the purpose unmistakable.

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

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

The description explicitly states 'Use when you discover something worth carrying forward' and explains the benefit (so you don't have to look it up again). It also names exactly which sibling tools to pair with: 'Pair with recall to retrieve later, forget to delete,' giving clear when-to-use and alternative-tool 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?

This description goes well beyond the annotations. It details the cascading lookup behavior, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling for identifiers, and the explicit handling of unresolved identifiers. This provides rich behavioral context beyond the read-only/idempotent hints.

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

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

The description is dense and well-structured with an example list, a clear action statement, and a breakdown of supported types. It is longer than average, but every sentence contributes functional value. The front-loaded examples make the purpose immediately recognizable.

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

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

For a tool with no output schema, this description is remarkably complete. It explains what identifiers are returned for each type, how sources behave under failure, the internal multi-endpoint nature, and what happens with unresolved identifiers. It fully equips an agent to invoke and interpret the tool correctly.

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

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

The schema already has 100% parameter coverage, so the baseline is 3. The description adds meaningful extra context: it explains how 'value' differs for 'company' vs 'drug', gives concrete examples (e.g., 'AAPL', 'ozempic'), and clarifies when certain identifiers like FIGI are resolved. This enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides multiple example queries, specifies the supported entity types (company, drug), and states that it returns official identifiers required by other tools. This distinguishes 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and notes that it replaces 2-3 manual lookups. It also explains the supported input types and the fallback behavior. However, it does not explicitly list when not to use this tool or name alternative tools for different use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it internally calls ai_visibility_check, ranks by score, and returns score/confidence/signal density. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds value. It includes an illustrative example phrasing and specifies the output components, all without unnecessary fluff.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description covers the main behavioral aspects: what it does, how it works internally, when to use it, and what it returns. Annotations handle safety semantics, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining that the first entity in the 'entities' array is treated as the 'subject' for narrative, while the rest are competitors. This meaningfully augments the schema's simple array 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 a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and distinguishes itself from sibling tools by mentioning it probes with ai_visibility_check and ranks results. It also provides a concrete example use case, making the purpose unambiguous.

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

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

The description gives a clear context for use ('competitive AI-marketing audits') and implies when to use it over ai_visibility_check (for multiple entities). It does not explicitly state when not to use it or name alternative tools, but the use case is well-defined enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: it warns about bundlephobia's first measurement taking 5-30s, explains graceful degradation with sources_failed listing timeout sources, and details the response structure (summary block, per-advisory details, links, alternative versions). 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 appropriately sized for a composite tool. It is front-loaded with the core purpose, followed by usage, return values, ecosystem scope, and failure behavior. Every sentence adds distinct information; no wasted words.

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

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

Given the tool's complexity (composite across two services, multiple output fields, edge cases), the description is highly complete. It covers what the tool does, when to use it, what it returns, ecosystem limitations, latency behavior, and error handling. No critical information is missing even without an output schema.

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

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

Schema coverage is 100% with both parameters documented. The description does not significantly add parameter-specific semantics beyond what the schema already provides; it contextualizes the 'version' parameter implicitly through the return values. Baseline 3 is appropriate given the high schema coverage.

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

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

The description states a specific verb+resource: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It clearly lists the aspects covered (license, advisories, bundle size, dependency count, ESM/tree-shake support) and explicitly limits to the NPM ecosystem, distinguishing from a direct deps.dev call for other ecosystems.

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 when-to-use guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' For non-NPM ecosystems, it points to 'deps.dev:version directly', offering a clear alternative. This makes it easy for an agent to decide when to select 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 read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details beyond annotations: keyword matching against both name and ID, the capped result size with default and maximum limits, and the return format with a concrete example. This provides sufficient transparency for a read-only search operation.

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, front-loaded with the action and resource. The example of a flow_ref is compact and illustrative. No redundant or filler content.

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

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

With only 2 parameters, 100% schema coverage, and an output schema present, the description provides all necessary context: what it searches, how results are capped, and how results integrate with a sibling tool. The description is complete for a search-then-fetch workflow.

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

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

Schema already describes both parameters at 100% coverage, so baseline is 3. The description adds meaning by clarifying that 'query' matches against ID as well as name, which the schema does not mention, and by explaining the returned flow_refs format. This extra context raises the score.

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

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

The description clearly states a specific action ('Search'), the resource ('BIS SDMX dataflow registry'), and the matching criteria ('by keyword against dataflow name and ID'). It also distinguishes the tool by showing how results connect to fetch_dataset, making it distinct from generic search 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 clear context: use this when you need to find dataflows by keyword and obtain flow_refs for fetch_dataset. It does not explicitly list alternatives or exclusions, but the integration hint ('ready to pass to fetch_dataset') gives practical usage guidance.

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

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

Annotations already mark read-only/idempotent, but description goes further to disclose embedding model, windowing, length cap with truncation flag, and output attributes (offsets, scores). These details are beyond the schema and help predict behavior.

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 compact despite dense information—each clause carries value. Front-loaded purpose followed by usage and tech details, with no filler.

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

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

Given no output schema, description adequately explains return values (passages with offsets and scores). It also covers edge cases (truncation flagged) and technical constraints, completing the picture.

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

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

Schema covers all 3 parameters, but description adds contextual meaning: text is 'already pulled' and query is 'natural-language', with example queries. The 'top-N' phrasing clarifies limit. This enriches rather than repeats schema.

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

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

Clearly states it performs semantic search inside a fetched record, distinguishing from siblings like ask_pipeworx_grounded by emphasizing 'already pulled' text. The verb is specific and the resource is clearly the record content.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt', giving a clear condition. It also pairs with ask_pipeworx_grounded, showing workflow integration. However, it does not explicitly name alternatives or exclusion cases, so slightly below a perfect score.

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 (readOnly=false, openWorld=true, idempotent=true) are supplemented with useful context: auth persistence, phone verification, SMS 10/day cap, and always-on feed behavior. No contradiction with annotations; the description adds meaningful behavioral detail.

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

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

At over 200 words, the description is dense and duplicates many schema examples (e.g., specific type params). It is organized, but several details could be left to the schema; the description should earn its length by providing non-redundant guidance.

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

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

Given the complex 3-parameter nested schema and no output schema, the description covers the essential context: purpose, auth prerequisites, supported types, delivery behavior, and what is returned ('new subscription id'). The webhook secret is covered in the schema, so this is sufficiently complete.

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

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

Schema coverage is 100% with rich descriptions for type, params, and delivery, including examples. The description largely repeats those examples and adds a little conceptual framing (e.g., what sec_8k matches) but doesn't significantly expand parameter semantics beyond the schema.

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

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

The description clearly states it 'Create a proactive monitoring subscription to a live-data event stream' and enumerates supported types and delivery channels. This specific verb+resource framing distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

It explicitly notes the OAuth account requirement, that anonymous + BYO cannot persist subscriptions, and contrasts proactive subscriptions with pulling via recent_alerts or a JSON endpoint. It doesn't explicitly say 'when not to use', but the exclusions are practical and sufficient.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context: it returns the full spread when called with no arguments, and focuses when `topic` is provided. It also discloses that results are drawn from a live catalog of thousands of tools, which implies dynamic content. Minor gap: it doesn't mention any pagination or limits, but these are unlikely for this tool.

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

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

The description is longer than average but front-loaded with user-intent phrases, then a clear definition, then call guidance. Every sentence contributes useful information. It could be slightly tightened by trimming the list of example phrasings, but the impact is 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?

There is no output schema, so the description carries the duty of explaining the return value. It does so thoroughly: category-bucketed example questions, exact tool + argument shape, and the list of categories. For a simple zero-to-one-parameter tool, this is fully 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% (the only parameter `topic` is fully described). The description adds value by giving concrete example values ('finance', 'pharma', 'betting') and explaining the omitted-argument behavior ('Omit for a cross-category spread'), which enriches the schema definition.

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: it returns category-bucketed example questions to help an agent learn what Pipeworx can do. It uses specific verbs ('returns', 'onboarding entry point') and lists concrete categories, distinguishing it from general discovery tools by explicitly framing it as the first use for learning how to call meta-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 gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to call with no arguments vs. with a `topic`, and names the alternatives (ask_pipeworx, entity_profile, compare_entities) that the agent should learn about.

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 important behavioral details beyond annotations: ownership enforcement, soft-delete semantics, and retention of historical events in recent_alerts. This aligns with destructiveHint=false and readOnlyHint=false, adding context without contradicting.

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

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

Three concise sentences, each delivering value: action, ownership rule, and side effects. Front-loaded with the verb, no unnecessary repetition.

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

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

For a simple single-parameter tool, the description fully captures purpose, constraints, and consequences. The mention of recent_alerts connects the data lifecycle clearly. No output schema needed given the simplicity.

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

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

Schema already has 100% coverage for the 'id' parameter. The description adds a meaningful ownership constraint (only your own subscriptions), which goes beyond the schema's description and helps the agent pass a valid parameter.

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

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

Description states a specific verb (Cancel) and resource (subscription) with the method (by id). It clearly distinguishes from siblings like subscribe and list_subscriptions, and the title reinforces the action.

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

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

Provides clear context: ownership is enforced (only own subscriptions) and behavior (deactivated, not deleted) is explained. It does not explicitly name alternatives, but sibling tools make the intended use obvious.

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, and idempotent behavior. The description adds crucial behavioral details: the meaning of 'could_not_verify' (verification error, not evidence), 'unsupported' (no source found), and the fast path vs fallback differences. It also mentions exact percent-delta math and verbatim evidence, significantly enriching transparency beyond the annotations.

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

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

The description is a dense, well-front-loaded paragraph (~200 words) packed with purpose, routing logic, return payload, and a critical caller warning. It avoids filler and every sentence earns its place. It loses one point for being an unstructured wall of text; breaking it into bullet points for the verdict list and routing paths would improve scannability.

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

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

For a tool with no output schema, the description thoroughly explains return values (verdict, actual value with citation, reasoning), the two special statuses (could_not_verify, unsupported), and the efficiency benefit of replacing multiple calls. It also mentions the SEC EDGAR fast path and grounded pipeline fallback, giving enough context for correct invocation. Minor vagueness about 'grounded pipeline' is acceptable given sibling context.

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

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

The input schema has 100% coverage, with detailed descriptions for both 'claim' and 'tolerance_pct'. The tool description itself does not add parameter semantics beyond the schema—it does not restate tolerance_pct or its usage. Therefore, the baseline score of 3 is appropriate because the schema already provides comprehensive 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 tool verifies natural-language factual claims against authoritative sources, provides example query forms ('Is it true that…' / 'fact check'), and distinguishes between financial and non-financial claims. It specifies a concrete action (verify) on a clear resource (claims), and the mention of SEC EDGAR and grounded pipeline separates it from generic search 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear context. It also explains the two routing paths (company-financial vs any other factual claim) and notes it replaces 4–6 sequential calls, implying it is the consolidated alternative. It does not list explicit when-not-to-use cases (e.g., subjective questions), which prevents a perfect score.

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