Paleobiodb

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

Even with annotations declaring readOnly/idempotent/non-destructive, the description adds valuable behavioral context: the default free model, the BYO-key requirement for Anthropic with direct payment to Anthropic, and the per-model output structure. This goes beyond what annotations provide and sets clear expectations for cost and external calls.

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 (three sentences) and front-loaded with purpose, then defaults, then return format, then use cases. Every sentence adds distinct information with no filler. It earns a top score for efficiency.

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 detailing the per-model response fields (score, confidence, signals, raw_response) and the combined view. It covers inputs, defaults, pricing, and output in a concise package, making it complete for a moderately complex tool.

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

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

Schema coverage is 100% and each parameter already has a thorough description. The tool description adds minimal parameter-specific meaning beyond the schema—it mentions the default model and cost implication for _apiKey, but these are more behavioral than semantic. Baseline 3 is appropriate when 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 uses a specific verb ('Probe') and names the exact resource (LLMs) and subject (business/brand/product/topic). It clearly states the scoring output (visibility 0-100 per model), which distinguishes it from vague 'check' tools. The return format and default model details further pin down the tool's identity.

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 clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly mention when not to use it or name alternatives (e.g., scan_competitor_ai_presence). It provides context for when to invoke but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it routes among 5,529 tools, fills arguments, returns structured output with pipeworx:// citation URIs, works on every tier, and makes a single fast call. This significantly helps the agent set expectations.

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 well-structured: it leads with a strong priority directive, then covers scope, alternatives, examples, and operational notes. Every section earns its place, and the use of bold and bullet-like list style makes it scannable. It could be tightened slightly, but the length is justified by the routing complexity.

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

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

With no output schema, the description carries the burden of explaining return value behavior, and it does: structured answer with stable citation URIs. It also covers the full decision context—when to use, when to step up to siblings, the breadth of data sources, and operational guarantees—making the tool's behavior sufficiently 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 description coverage is 100%, including aliases, so the schema already documents all parameters. The description reinforces natural-language usage with examples but does not add meaning about parameter formats or edge cases beyond the schema. This is the standard baseline for high schema coverage.

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

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

The description clearly states what the tool does: routes a natural-language question to the relevant Pipeworx tool and returns a structured, cited answer. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and the 'PREFER OVER WEB SEARCH' framing sets a clear scope.

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, including example query patterns ('what is', 'look up', 'find'), specific domains, and even a list of sample questions. It also provides when-not-to-use direction by naming ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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, covering the safety profile. The description adds that routing behavior may change when candidates are under test and clarifies it is a full working router with no fallback, which is valuable context beyond annotations.

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

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

The description is moderately verbose but every sentence serves a purpose: beta status, current state, usage guidance, and clarification of fallback behavior. It could be tightened slightly, but it remains efficient and front-loaded with the core identity.

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 explains the tool's nature as a router and its current equivalence to ask_pipeworx, but it does not detail the response shape or routing mechanism beyond saying 'same response shape'. Given no output schema and the tool's complexity, this leaves some ambiguity, though the sibling tool may fill the gap.

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

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

Schema coverage is 100% with each parameter described as an alias for 'question'. The description mentions 'same arguments' but adds no semantic detail beyond what the schema already provides, 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 clearly identifies the tool as the beta version of ask_pipeworx, a universal router for 5,529 tools. It states 'identical universal router' and specifies that it accepts the same arguments and returns the same response shape, effectively distinguishing it from the stable ask_pipeworx sibling.

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

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

Explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It also mentions no candidate is currently active, so it matches ask_pipeworx exactly, giving a clear when-to-use and when-not-to-use comparison.

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, open-world), the description details the refusal mechanism with specific refusal_reason values, the return schema on success, and the fact that it uses only tool result content. It also flags an extra LLM call cost. These add substantial behavioral context not available in annotations.

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

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

The description is detailed yet every sentence adds vital information: purpose, routing, extraction behavior, return format, refusal reasons, use cases, and cost comparison. It is front-loaded with the core purpose and structured to escalate from description to behavior to guidance.

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

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

Given the complexity of a grounded Q&A tool with refusal modes and no output schema, the description fully covers the return contract, error handling, cost, and relation to ask_pipeworx. It leaves no critical ambiguity for an agent trying to select and invoke the tool.

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

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

Schema coverage is 100% with six parameters, but all are aliases for the same 'question' parameter. The description does not add parameter-level meaning beyond the schema, but the schema is already explicit (e.g., 'Your question in natural language. Accepts query, q, prompt, text, input as aliases.'). Thus the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and details its function: 'extracts the answer using ONLY what the tool result contains.' This distinguishes it from sibling ask_pipeworx by emphasizing the grounded nature, making the purpose specific and 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 provides explicit usage context: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also tells when NOT to use it: 'prefer ask_pipeworx for casual lookups,' and mentions the cost tradeoff. This is a model of when/when-not guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses rich behavioral traits: parallel fan-out, resolver contract with match confidence and alternatives, low-confidence short-circuit, market_closed_or_inactive status, illiquid_wide_spread flag, GDELT fallback fields, and parsing of cancellation rules with EV impact. It also explains that both blocking paths are distinct mechanisms. This far exceeds what annotations convey and adds critical safety context.

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

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

The description is long but well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). The opening sentence gives an immediate one-line summary, and each section earns its place by documenting necessary behavior. Some elaboration (e.g., audited arb-bot ledgers) is verbose but justified 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?

With no output schema, the description must document return values—and it does thoroughly: result.market fields, result.analysis (model_probability, edge_pp, kelly_fraction_half, 24h-move warning), result.evidence keying, match_confidence contract, parent_event extractor, news fallback fields, and status codes. It also covers edge cases (closed markets, wide spreads, cancellation rules), making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaningful operational nuance. It clarifies when to pass include_raw=true (recompute deltas, cite observations, post-process), differentiates depth='quick' vs 'thorough' via fan-out scope, and explains the market parameter's flexibility (slug/URL/question text). This goes beyond the schema's field descriptions by providing usage rationale.

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 defines input formats (slug, URL, question text), output (evidence packet + market-vs-model comparison), and explicitly frames its use case ('should I bet on X'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage that target different analytic needs.

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 for' with three concrete query types and provides fan-out examples (e.g., BTC bet → coingecko + fred, Fed bet → fred + kalshi_macro) that make the invocation context clear. However, it lacks explicit when-not-to-use guidance or named alternatives like 'use polymarket_edges for cross-market scanning,' so it stops short of full exclusion semantics.

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 (read-only, open world, idempotent), the description discloses data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting behavior by primary metric, and output format with citation URIs. This significantly enriches the agent's understanding.

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

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

The description is dense but well-structured, starting with example queries, then stating the core purpose, followed by type-specific details and output format. Every sentence adds value without repetition or fluff.

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

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

Given the lack of an output schema, the description adequately covers return values (paired data + citation URIs) and edge cases (off-calendar fiscal years). The tool's behavior, data sources, and limits are fully specified, making it complete 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?

Although the schema already covers both parameters (100% coverage), the description adds meaning by detailing what each type ('company' vs 'drug') retrieves. It also provides realistic examples for values and explains how results are sorted, going beyond the schema.

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

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

The description clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses a specific verb ('compare') and resource (companies/drugs), and distinguishes from alternatives by noting it should replace sequential single-pack lookups.

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

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

Explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides example queries to clarify user intent and notes it replaces 8–15 sequential lookups, giving clear context.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds crucial context: account/paid-plan requirements, latency expectations, gaps[] for unanswered facets, contradictions[] scans, semantic excerpting, and guaranteed fetchable citations. This goes well beyond what annotations alone provide.

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

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

The description is long but every sentence serves a distinct purpose: usage exceptions, distinct data scope, return format, limitations, latency, and depth semantics. It is front-loaded with the account requirement and closest alternative, making critical information immediately visible. Slightly verbose but justified by the tool's complexity.

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

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

With no output schema, the description fully explains the return packet including verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop field. It also covers edge cases like large records and breaking news, making the tool's behavior predictable in complex scenarios.

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

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

Schema coverage is 100% and the enum description for depth already explains the three levels. The description adds valuable behavioral semantics for both parameters: 'question' benefits from decomposition, and 'depth' is tied to hop behavior and gap recovery, enhancing the schema's structural definitions.

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

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

The description specifies a clear verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in 'ONE call'. It also distinguishes itself from siblings by contrasting with ask_pipeworx for single lookups and live news, making the tool's unique value obvious.

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 and when-not-to-use guidance: use ask_pipeworx if not signed in, for single lookups, or for breaking/current news topics. It also explains depth-level selection and when multi-hop iteration is beneficial, giving the agent clear decision criteria.

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

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

While annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context by detailing the return format (top-N tools, names, descriptions, full input schemas, curated examples) and the fact that results are ready to call directly with 'no second schema lookup needed.' This goes beyond the annotations to explain observable 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 front-loaded with the core purpose, then gives usage context, and finally explains return behavior. The listing of data domains is somewhat lengthy but adds useful scope information. No unnecessary filler, and each sentence contributes a distinct piece of guidance.

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

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

Given the tool's role as a meta-search for other tools and the lack of an output schema, the description fully covers what the tool returns, how to use it, and when it is appropriate. It provides enough detail for an agent to invoke it confidently as a first step, including the promised immediate usability of results.

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

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

Schema description coverage is 100%, with every parameter, including aliases, already documented in the schema. The description does not add new semantic meaning to the parameters (e.g., explaining how to form a good query), so it relies on the schema's own definitions. 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 'Find tools by describing the data or task,' a specific verb+resource that clearly states the tool's function. It further distinguishes itself as a meta-tool for browsing or discovering available tools, especially with the instruction to 'Call this FIRST,' setting it apart from sibling tools.

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

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

Usage guidance is explicit: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It provides clear context and a strategic placement, though it does not explicitly state when-not-to-use or name 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?

Annotations already signal safety, but the description adds substantial behavioral detail: parallel call, up to 5 filings, latest 10-K fundamentals, patent soft-fail until May 2025, GDELT→GNews fallback, and input format constraints. 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 dense and front-loaded with examples, but it is a single long paragraph. All sentences earn their place, though breaking into bullets could improve readability. Still, it is efficient given the complexity.

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

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

Despite no output schema, the description enumerates every return component (cik, filings, fundamentals, patents, news, LEI) with specifics like sorting and URIs. It also covers edge cases (patent sunset, CIK zero-padding), making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with concrete examples (AAPL, 0000320193), notes zero-padding requirement, and explicitly states names are unsupported—clarifying the value parameter 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 produces a full cross-source profile of US public companies, with specific example queries (e.g., 'Tell me about X', 'research Acme'). It also differentiates itself from chaining single-pack lookups by explicitly saying 'ALWAYS PREFER' when a holistic view is requested.

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 (holistic view) and when-not-to-use (names unsupported, use resolve_entity first). It mentions the parallel fan-out across sources, making it clear this is a one-stop-shop for company profiles.

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: subtaxon matching, age units in Ma, and keyless access. 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 three sentences, front-loaded with purpose, then return values, then matching behavior. Every sentence adds information 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?

With no output schema, the description explains return values (occurrences with lat/lng, country, ages) and clarifies units and keyless access. Combined with rich annotations and complete schema coverage, the description is sufficiently complete for an agent to invoke the tool.

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

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

Schema description coverage is 100%, with each parameter well-documented. The description repeats the subtaxon matching behavior already present in the taxon parameter description, adding no new semantic value. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds fossil occurrences for a taxon from the Paleobiology Database, specifying the resource and the action. It distinguishes itself from sibling tools like get_taxon or list_subtaxa by focusing on occurrence data with locations and ages.

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 implies when to use the tool (when needing fossil occurrences with locations and ages) but does not explicitly mention alternatives or when-not-to-use. The context is clear, but exclusions or alternative tool references are absent.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about the purpose of deletion (stale context, sensitive data) and positions it as a cleanup action, which goes beyond the raw annotation flags.

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

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

Two sentences, front-loaded with the core action, followed by concise usage context. Every word earns its place; no redundancy or filler.

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

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

For a one-parameter destructive tool with rich annotations (destructive, idempotent) and no output schema, the description fully covers purpose, usage, and behavioral context. 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 description for the single 'key' parameter is complete (100% coverage), and the description simply restates 'by key' without additional semantic value. Baseline of 3 applies because schema covers all needed information.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from siblings like remember and recall by explicitly contrasting store, retrieve, and delete.

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 guidance on when to use: when context is stale, task is done, or sensitive data needs clearing. It also suggests pairing with remember and recall as alternatives, but lacks explicit 'when not to use' conditions.

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 (read-only, idempotent), the description explains the underlying process: fetching the page, extracting title/description/key links, and emitting standard markdown. This adds valuable behavioral 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, front-loaded with the core purpose, followed by process and use cases. Every sentence contributes meaning without redundancy, making it efficient and well-structured.

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

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

Given the tool's simplicity (two well-described parameters, no output schema needed, annotations covering safety), the description covers the purpose, process, output format, and use cases. It is complete enough 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?

The schema already provides thorough descriptions for both parameters (url and max_links) with 100% coverage. The description adds minimal extra semantics, only mentioning 'key links' and the markdown format, which does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the action (generate), resource (llms.txt), and target audience (AI crawlers), distinguishing it from sibling tools focused on analysis or 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 lists explicit use cases: getting a client's site indexed, drafting your own llms.txt, and auditing competitors. It provides clear context for when to use the tool, though it doesn't explicitly mention exclusions or 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 this as a safe, read-only, idempotent operation. The description adds value by disclosing the specific output fields (rank, attribution, first/last appearance, subtaxa) and the 'Keyless' note, which informs the agent about authentication and return content beyond what annotations convey.

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

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

The description is a single, well-structured sentence. It front-loads the core action and resource, then lists the returned fields in a compact parenthetical enumeration. No redundant phrasing or fluff.

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

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

With a simple one-parameter schema, no output schema, and strong annotations, the description sufficiently conveys what the tool returns (detailed taxon information). It also notes 'Keyless', covering operational context. No critical information is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100% for the single 'name' parameter, which is well-documented in the schema with an example. The description does not add new parameter-level detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('look up') and clearly defines the resource ('a single taxon in the Paleobiology Database'). It lists the exact information returned (rank, attribution, appearance intervals/ages, subtaxon count), making the tool's function unambiguous and distinct from siblings like list_subtaxa or find_fossils.

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: it is for fetching details about a single taxon by name. It does not explicitly mention alternatives or exclusions, but the 'single taxon' scoping and the field list implicitly guide when to use it, and 'Keyless' indicates no authentication is needed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context about the caller scope and the exact fields returned, which 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 three sentences, each earning its place: the first states the action, the second lists return fields, and the third gives practical usage. No waste or redundancy.

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

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

For a simple read-only list tool with one optional parameter, the description is complete. It explains return values (since there is no output schema), mentions the scope, and provides usage guidance, while annotations handle safety attributes.

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 only parameter (include_inactive) already well-described in the schema. The description does not add any parameter information, 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 states the tool's function with a specific verb and resource: "List the caller's active subscriptions." It also lists the exact return fields and distinguishes its scope (caller's own subscriptions) from potential siblings like list_subtaxa.

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

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

The description provides explicit usage context: "Use this to review what you're monitoring before adding more or to find an id to cancel." This tells the agent when to use it, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so safety is well covered. The description adds meaningful context beyond annotations: it is 'Keyless' (suggesting no authentication barrier) and specifies what each returned child includes (rank and subtaxon count). 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 short sentences, front-loaded with the core purpose and output. The second sentence 'Keyless' is a concise, useful behavioral note. No redundant phrasing or filler.

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

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

For a simple list tool with rich annotations and fully described parameters, this description is largely complete. It covers output fields and access hints. A slightly lower score is warranted because it does not mention error behavior, pagination, or what happens when a taxon has no subtaxa, though these are not critical for basic invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no new parameter-level semantics beyond the schema; it simply refers to the parent taxon and output shape. The 'limit' parameter is already well described 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 uses a specific verb ('List') and clearly identifies the resource ('direct child taxa (subtaxa) of a taxon') plus the included details (rank and number of its own subtaxa). This differentiates it from siblings like get_taxon, which presumably retrieves a single taxon's details.

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 exact scope ('direct child taxa') and source ('Paleobiology Database'), making the use case clear. It also notes 'Keyless' as an access hint. However, it does not explicitly advise when to use this tool versus alternatives such as get_taxon or find_fossils, so it stops short of full exclusionary 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 are all false and provide no safety signals, so the description carries the burden. It discloses the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and operational details ('The team reads digests daily and signal directly affects roadmap'). This goes well beyond annotations.

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

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

Although longer than one sentence, every clause serves a purpose: purpose, triggers, scope exclusion, token flow, process transparency, rate limits, and cost. It is front-loaded with the core purpose and logically organized.

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

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

The tool has 4 params with 100% schema coverage but no output schema. The description compensates by explaining the token lifecycle, exclusions, and expectations. It covers purpose, usage, limitations, and post-submission flow, making it complete 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?

Schema coverage is 100%, so baseline is 3. The description adds value by reinforcing the enum meanings ('bug', 'feature/data_gap', 'praise'), giving token usage syntax ('pipeworx_feedback({claim_token:"pwfb_…"})'), and advising to describe issues in terms of Pipeworx tools/packs, which informs the context and message params.

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 clear statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the verb (tell), resource (Pipeworx team), and scope (broken/missing/exist). It distinguishes from siblings by explicitly scoping to tools served by this Pipeworx connection and directing other-server feedback away.

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-case triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is explicit when-to-use and when-not-to-use with an alternative action.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context by disclosing the data source (CF analytics-engine), that no PII is exposed, the exact data shape (pack, tool, count), and cache behavior (5min-1h), which goes 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 yet comprehensive: a one-line summary, output details, three numbered use cases, and a data provenance/caching note. Every sentence adds value, and the structure makes it easily scannable.

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

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

For a simple tool with one optional parameter, the description covers the return values (top tools, top packs, total call volume), the data shape, and caching caveats. The lack of an output schema is compensated by the explicit description of what is returned. It is complete for an agent to decide whether and how to invoke it.

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 documented in the schema with its enum and meaning. The description reinforces the window options and their relevance ('shorter windows surface what's hot right now; longer windows show steady-state demand'), but this largely duplicates schema-provided information. Since schema coverage is 100%, 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 states the tool returns top tools, top packs, and total call volume for recent windows, with a specific scope (what other AI agents call on Pipeworx). This distinguishes it from sibling tools like discover_tools or ask_pipeworx, which have different purposes.

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 tool choice, and checking alignment with agent needs. It does not mention when not to use the tool or name alternative tools, but the context is clear enough for an agent to decide applicability.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: the partition filter for placeholder slugs, Jaccard similarity threshold, fill check logic with realizable edge thresholds, and output structure. No contradiction with annotations.

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

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

The description is long but densely informative, with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose. Some redundancy exists, such as explaining partition_check multiple times, but every sentence adds meaningful context.

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

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

This is a complex tool with no output schema, and the description compensates by detailing return fields (opportunities[], partition_check), edge cases (placeholder fractions, low similarity, thin legs), and operational guidance (do not trade when realizable_edge_pp ≤ 0).

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining mode-specific behavior, accepting full URLs, providing concrete examples (e.g., 'fed-decision-may-2026'), and describing the fill check and custom sizing implications.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings by detailing three modes (trending_scan, event, topic) and referencing related tools like polymarket_fill_risk.

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

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

It explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also directs custom sizing to 'polymarket_fill_risk' as an 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?

Annotations already declare the tool read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: response structure (by_segment, fed_candidates, _diagnostics), caching at KV level for 1 hour, reasoning for excluding Fed bets, 24h-move warnings, Kelly caps, and funnel counters for empty segments. This goes far beyond what annotations convey.

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

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

The description is long, but it is well-organized into clear sections (purpose, model families, per-opportunity fields, tradeable-edge knobs, response format, caching). It is front-loaded with the core purpose. While every section adds value for the tool's complexity, the length is near the upper bound of what an agent can efficiently process.

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?

Since there is no output schema, the description shoulders the responsibility of explaining return values. It thoroughly describes top-level by_segment, fed_candidates/fed_note (with rationale), _diagnostics with WHY a segment is empty, per-opportunity attributes (edge_pp_net, kelly_fraction, liquidity, spread), and caching behavior. No significant 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?

Although the input schema covers all 9 parameters with descriptions, the tool description adds crucial semantics: it clarifies that min_kelly never filters partition arbs (parent-level kelly_fraction_half is deliberately 0), that min_partition_leg_kelly applies per-leg inside top_legs, and explains the slippage_pp default reasoning. This meaningfully enriches parameter understanding.

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

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

The first sentence states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. This is a specific verb+resource+scope, and it distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly frames the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides clear context and intended scenarios, but stops short of naming explicit alternative tools or when-not-to-use conditions, so it does not fully meet the highest bar.

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

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

The description goes far beyond the annotations by detailing limits (60-day TTL, cache-miss snapshot writing, daily closes not intraday), the return structure, and how to interpret gaps. This is critical behavioral context that annotations do not cover. No contradiction with readOnlyHint.

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

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

The description is well-structured with separate sections for purpose, args, response, and limits. It is dense and information-rich, and while the response section is lengthy, every part adds value. A slight trim would make it even more concise, but it earns its place.

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

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

For a read-only analytical tool with no output schema, this description is exceptionally complete. It details the tracked[], expired[], and snapshot_dates[] outputs, explains how trend and decay are computed, and covers edge cases like snapshot gaps and TTL. It fully prepares the agent to interpret results 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 descriptions already fully document both parameters, including defaults and clamping for days and the window options. The description's mention of 'snapshot family' and defaults adds little beyond what the schema provides, 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 opens with a specific purpose: edge persistence and decay telemetry derived from daily snapshots. It clearly differentiates from siblings like polymarket_edges (current edges) by focusing on history and trends, and uses the fresh vs. 3-week-old edge example to illustrate the unique value.

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 provides clear context for when to use the tool: to assess whether an edge is persistent and whether it is shrinking before acting. It implies this is a companion to polymarket_edges (which provides current edges), but does not explicitly name alternatives or exclusion criteria, so it falls slightly short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: walking the CLOB ladder, returning a verdict, and warning that partial basket fills convert an arb into an unhedged directional position. 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?

Every sentence earns its place and the first sentence is crisp, but the single-paragraph wall of capital-letter emphasis ('REQUIRES', 'BASket', 'USE THIS') hurts scannability. A bit of formatting would make it a 5.

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 enumerates all key returned fields for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk, etc.) and covers edge cases. Combined with annotations and full param schema coverage, it is fully actionable.

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

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

Schema coverage is 100%, but the description adds substantial meaning by explaining how each parameter behaves in single-market vs basket mode, including size_usd's dual interpretation, default values, clamps, and side auto-selection. This goes well beyond the schema's field 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?

Description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as the tools it should precede.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and provides mode-selection rules (single-market vs basket), including default behaviors and risk warnings. This is exemplary usage guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and an honest caveat that most pre-mapped topics return warnings today. 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries information; the density is justified by the tool's complexity, though it could be slightly more streamlined.

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 burden of explaining the response. It covers leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skip counters, making it complete for a read-only analytical 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% for the 3 parameters, and the description adds mode semantics: the topic parameter is a pre-mapped shortcut, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. This enriches the schema definitions without repeating them.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies what the tool does and distinguishes it from sibling tools like polymarket_arbitrage by emphasizing the Kalshi–Polymarket pairing and the compatibility-warning behavior.

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

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

The description explains two usage modes (topic shortcuts vs explicit ticker/slug), and provides guidance on when the output is meaningful by describing compatibility_warning cases and noting that 'pre-mapped ≠ tradeable.' It does not explicitly compare against sibling tools, but gives sufficient context for when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond these: scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key argument is omitted. 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 three focused sentences. It front-loads the primary action, then gives usage context, and finishes with scoping and pairing guidance. Every sentence earns its place with no filler or 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 tool with one optional parameter, no output schema, and strong read-only annotations, the description is complete. It covers the purpose, usage scenarios, scoping, and tool relationships (remember/forget). No critical missing context is apparent.

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%: the only parameter 'key' has the description 'Memory key to retrieve (omit to list all keys).' The tool description essentially restates this in the opening sentence, adding contextual meaning ('previously saved via remember') but no new syntax or format details. Per the baseline for high schema coverage, a 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This is a specific verb and resource. It also distinguishes from siblings by referencing remember and forget, establishing its unique role in the memory workflow.

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 to look up context the agent stored earlier' and provides concrete examples ('user's target ticker, an address, prior research notes'). It also explains the relationship to alternatives by saying 'Pair with remember to save, forget to delete,' giving clear when-to-use and when-not-to-use guidance.

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

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

The annotations declare readOnlyHint=true and idempotentHint=true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the read-only hint, making the behavioral guidance misleading for an agent.

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

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

The description is moderately concise; it front-loads the purpose and packs useful behavior into a few sentences. The final sentence about the alternative URL is slightly tangential but still valuable for scripts/dashboards.

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 read-oriented tool with 5 optional parameters and no output schema, the description covers return fields, filtering, and polling semantics. The mark_read behavior and persistent feed context give an agent enough to invoke correctly, though the annotation contradiction undermines full reliability.

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 covers all 5 parameters with descriptions, so the baseline is 3. The description adds meaningful nuance: an example type ('sec_8k'), the combination of type and since filters, and the side-effect explanation for mark_read. It does not mention limit or unread_only, but those are adequately covered 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 opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly identifies the tool's function. It further details what is returned (source, citation_uri, raw payload) and distinguishes it from siblings like list_subscriptions by focusing on alerts/events rather than subscription management.

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 clear usage context: it explains filtering by type/since, the mark_read behavior, and that polling works fine. It also notes an alternative HTTP endpoint for scripts/dashboards, which is a form of alternative, but does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Beyond annotations that declare read-only, idempotent, and non-destructive behavior, the description discloses the parallel fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-fail due to the PatentsView API sunset. It also explains date format handling and the return structure, adding rich behavioral context.

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

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

The description is dense and multi-purpose, covering example queries, core function, source list, fallback logic, date formats, output, and an alternative in a compact but substantial paragraph. It is front-loaded with the purpose and efficiently packs necessary details, though slightly long.

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 explicitly describing the structured return (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers failure modes (GDELT rate limits, USPTO sunset) and provides a clear alternative, making it self-contained and complete for a tool of this complexity.

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

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

The input schema already provides full descriptions for all three parameters, so the baseline is 3. The description repeats the date and value formats but does not add new semantic meaning beyond what the schema already states, though it reinforces with examples within the overall narrative.

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 (get changes) and resource (company change feed), framing it with example queries like 'What's new with X'. It distinguishes itself from siblings by explicitly contrasting with entity_profile, which serves static profiles rather than windowed changes.

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 names entity_profile as an alternative and advises using it when a static profile is needed regardless of window. It also provides context on when to use this tool (recent changes in a time window) and hints at fallback behavior, covering the when/when-not criteria.

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

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

The description adds behavioral context beyond the annotations: storage as a key-value pair scoped by identifier, persistence differences for authenticated vs anonymous sessions, and the ability to pair with recall/forget. It also implies idempotent overwrite behavior consistent with the idempotentHint annotation. No contradiction 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 composed of five short sentences, each earning its place: purpose, usage examples, storage model, persistence, and sibling pairing. It is front-loaded with the core purpose and contains 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?

For a simple write tool with full schema coverage and annotations, the description covers all essential context: what to store, when to use it, how storage is scoped, persistence behavior, and related tools. No output schema is needed for a write operation.

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 covers 100% of parameters with meaningful descriptions. The tool description adds only the general 'key-value pair' framing without new detail about the parameters themselves. Baseline 3 is appropriate for high schema coverage.

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

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

The description opens with a clear verb and resource: 'Save data the agent will need to reuse later.' It also explicitly contrasts with siblings by mentioning 'Pair with recall to retrieve later, forget to delete,' distinguishing the tool from the related retrieve/delete 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?

It gives concrete when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also references the alternatives (recall, forget) and the session persistence difference, which helps the agent choose correctly.

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 annotations: it explains source labeling ('every identifier is labelled with the source that established it'), unresolved handling ('stated explicitly under `unresolved` rather than omitted'), graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and internal cascading ('Each call cascades through several lookup endpoints internally'). These behaviors are not conveyed by the read-only or idempotent hints, making the description exceptionally transparent.

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

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

The description is front-loaded with example queries and a clear purpose, then flows into supported types and behaviors. While it is long, every sentence contributes value (input formats, source labels, fallback, efficiency). It could be slightly streamlined, but the density is justified given the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains return values for both supported types: company identifiers (CIK, ticker, LEI, FIGI) and drug identifiers (RxCUI, ingredient, brand, citation). It also covers failure modes (unresolved identifiers, degraded enrichment) and the scope of internal lookups. This makes the tool's behavior fully comprehensible without needing 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?

The schema already provides 100% coverage of the two parameters, so the baseline is 3. The description adds meaningful context beyond the schema: for 'company' it specifies accepted inputs as 'ticker (AAPL), CIK (0000320193), or name' and for 'drug' as 'brand or generic name (e.g., "ozempic", "metformin")'. It also ties parameter values to return behavior (e.g., 'when a ticker is implied' for FIGI), enriching 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 clearly states the tool's verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete examples of user queries and distinguishes itself from siblings by focusing on name→ID resolution. The supported types and specific identifiers (CIK, LEI, FIGI, RxCUI) are detailed, 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 explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This implies a when-not condition (when you already have the ID). It also explains that the tool replaces multiple manual lookups, giving context on efficiency. However, it does not explicitly name alternative tools or exclusions, so it misses the full 'when-not/alternatives' clarity of a 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?

Annotations already declare read only, idempotent, and open world hints. The description adds behavioral detail beyond that: it reveals the tool probes each entity with ai_visibility_check, ranks by score, and returns confidence and signal density per entity. It does not contradict 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 four concise sentences with no redundancy. It front-loads the core action, then explains the process, provides a use case, and lists return fields. Every sentence earns its place.

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

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

Even without an output schema, the description specifies the return elements (score, confidence, signal density per entity), explains the multi-entity workflow, and gives a concrete use case. Combined with full parameter descriptions and annotations, it is complete for the tool's complexity.

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

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

The input schema describes all four parameters with 100% coverage, so the description adds little extra meaning. It mentions entities ('your brand + N competitors') and the probe mechanism, but this largely mirrors the schema. A 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 states the tool 'Compare AI visibility across multiple entities side-by-side', names the underlying probe mechanism (ai_visibility_check), and describes the ranking and output. It distinguishes itself from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing specifically on AI visibility and competitive audits.

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 provides concrete context: 'Useful for competitive AI-marketing audits' and gives an example query. It implies use when comparing multiple entities, but stops short of explicitly stating when not to use it or suggesting alternative tools, hence a 4 rather than 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?

The description adds substantial context beyond the annotations. It explains the tool fans out to two external services, has a partial failure mode (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts), and discloses the ecosystem limitation. It also enumerates the return fields explicitly, which is especially valuable given no output schema. No contradiction with the readOnly/openWorld/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 information-dense yet well-structured. It front-loads the main purpose, then gives usage cues, output summary, ecosystem scope, and failure behavior. Every sentence adds value; there is no fluff or repetition of schema fields. The use of dashes and semicolons makes it easily scannable despite its length.

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

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

For a tool with no output schema, the description comprehensively covers return values (summary block fields, per-advisory detail, links, alternative versions). It also addresses failure modes, timing, and ecosystem constraints. This is a complete picture for an agent to decide when and how to invoke the tool, even without structured output metadata.

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

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

Schema coverage is 100% and both parameters already have clear descriptions in the schema. The tool description does not add new semantic meaning beyond what the schema provides (e.g., 'version' defaults to latest is already in schema). It earns the baseline of 3 for schema coverage, but does not go beyond it to add extra parameter 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's purpose: 'Composite "should I add this npm package to my project" check in ONE call.' It specifies the action (check) and the resource (npm package), and details the data sources (deps.dev, bundlephobia). It distinguishes itself from sibling tools by being the only one covering dependency scanning, and the use cases ('is X safe / popular / small') reinforce its unique role.

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

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

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clearly states exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which tells when not to use this tool and points to an alternative. This is exactly the kind of when-to-use vs. when-not-to guidance expected.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes further by disclosing technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap, and truncation with a flag. It also explains the return includes offsets and similarity scores, which is important for verifying quotes. No contradictions with annotations.

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

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

The description is concise yet information-dense: three sentences covering purpose, use case, and technical details. It is front-loaded with the core function and progressively adds operational context without waste.

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 must explain return values, which it does: 'top-N passages with character offsets and similarity scores.' It also covers limits, truncation behavior, and integration with another tool. This makes the tool fully understandable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical meaning: it clarifies that 'text' should be an already-fetched record (e.g., SEC filing, article), gives example queries for 'query', and reinforces the 200K character limit mentioned in the schema. This adds context beyond the schema definitions.

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

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

The description states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing 'inside a fetched record' and by naming the complementary tool ask_pipeworx_grounded. The scope (pass text + query, get passages) is explicit.

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

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

Provides explicit when-to-use: 'Use when the record is too big to cram into the prompt.' It also describes the alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clarifies usage context and relationship to alternatives.

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

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

Annotations already indicate non-read-only, open-world, idempotent, non-destructive, but the description adds valuable behavioral details: authentication requirements, always-on feed, optional delivery channels, phone verification, SMS cap, and webhook signing secret behavior. No contradiction with annotations.

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

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

The description is dense but organized: purpose first, then supported types, then delivery channels. Every sentence adds specifics, though length is substantial. It is front-loaded with the primary action and return 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?

For a create tool with no output schema, the description covers required auth, supported types, parameter formats, delivery options, and caveats (phone verification, SMS cap, webhook secret). It fully prepares 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?

Although schema coverage is 100%, the description significantly enriches parameter understanding with concrete examples: sec_8k items, polymarket_edge topic, fred_series series_id, plus delivery details like E.164 phone format and webhook HMAC signing. This goes well 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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this create operation from sibling tools like list_subscriptions and unsubscribe, and explicitly lists supported subscription types.

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 this tool: to create a subscription for event types like sec_8k or polymarket_edge. It also notes the OAuth account requirement as a prerequisite and directs users to recent_alerts or a feed URL for pulling delivered events, implicitly clarifying not to use this tool for retrieval.

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=true, openWorld=true, idempotent=true, and destructive=false, which the description supports. The description adds that the tool returns example questions with exact tool+argument shapes from a live catalog, giving the agent expectations about the response's nature 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 longer than average but each segment serves a purpose: example utterances for pattern matching, output expectations, and parameter usage. It is reasonably front-loaded with the user intents at the start, though a tighter summary sentence could come earlier.

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 a single optional parameter and no output schema, the description covers all essential aspects: when to use, what it returns, how to specialize the input, and its role in onboarding. It even mentions the relationship to other meta-tools, making it fully self-contained 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 description coverage is 100% because the only parameter `topic` has a detailed description in the schema. The description repeats this info with examples but does not add new semantic details beyond what the schema already states, so baseline 3 applies.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what to ask Pipeworx, with a specific verb ('Returns category-bucketed example questions') and a defined output. It distinguishes itself from siblings by explicitly naming meta-tools it teaches (ask_pipeworx, entity_profile, compare_entities), which helps the agent differentiate it from direct Q&A 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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear when-to-use context. It also explains how to invoke with or without the `topic` parameter, but does not explicitly state exclusions or compare with similar discovery tools like discover_tools.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds specific context: ownership enforcement and that deactivation keeps historical events available. This goes beyond the annotation flags, though it could have mentioned idempotency explicitly.

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

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

Two sentences, front-loaded with the core action and followed by meaningful qualifications. No redundancy or filler.

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

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

Given a single parameter and no output schema, the description covers the action, ownership restriction, and the deactivation side effect. It doesn't describe return values, but for a straightforward cancellation the effect is clearly stated.

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

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

The schema fully describes the id parameter (uuid returned by subscribe), so the description's 'by id' adds little. No extra parameter semantics are provided beyond the schema, which meets the baseline for high schema coverage.

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

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

The description states a specific verb ('Cancel') and resource ('subscription') and immediately distinguishes the tool from siblings like subscribe and list_subscriptions. It also adds the ownership constraint, further clarifying scope.

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

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

The description provides clear usage context: cancel your own subscription, with the nuance that rows are deactivated rather than deleted, and suggests recent_alerts for historical events. However, it doesn't explicitly say when not to use this tool or compare alternatives beyond that indirect mention.

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

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

Beyond the read-only, open-world, and idempotent annotations, the description adds crucial behavior details: the verdict set, the could_not_verify vs unsupported distinction, verification_error inclusion, and the fact that it performs the full pipeline. 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?

Although long, every section earns its place: trigger phrases, purpose, use case, two processing paths, return value summary, and critical error semantics. The structure is logical and front-loaded with the core 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 complex tool with no output schema, the description fully compensates by detailing return values, verdict meanings, error cases, and the pipeline it replaces. It is complete enough for an agent to invoke correctly and interpret results.

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

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

The input schema already covers both parameters with rich descriptions (claim with examples, tolerance_pct with default and usage). The description does not add new parameter-level meaning beyond what is in the schema, so baseline 3 applies.

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

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

The description explicitly names the tool as 'natural-language claim verification' with concrete trigger phrases and a clear verb+resource. It distinguishes itself from sibling tools by focusing on fact-checking and replacing multiple sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the routing between financial and other claims. However, it does not explicitly name alternative tools or provide 'when not to use' exclusions.

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