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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context by explaining that the tool routes questions across 5,798 tools and 1,517 verified sources, fills arguments, and returns structured answers with citation URIs. It does not contradict the annotations. Minor gap: it does not describe failure behavior or citation format details, but the routing and sourcing behavior is well disclosed.

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 fairly long and front-loaded with the key preference instruction, then rich examples, but it ends with a long, run-on 'packs' sentence that adds a playful rhyme but little functional clarity. The core guidance is valuable, but the final sentence is over-stuffed and hard to parse, reducing conciseness.

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

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

For a retrieval/routing tool with no output schema, the description tells the agent what it does, when to use it, what it accepts, and what the output contains (structured answer with stable citation URIs). It covers the key decisions: when to call vs web search, what question types are suitable, and example usage. It lacks detail on citation format or error handling, but for this tool's simplicity those are optional rather than essential.

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 main `question` parameter thoroughly described and aliases documented. The description adds semantic value by clarifying the expected input style (natural language, open-ended factual questions), including examples. It goes beyond the schema's bare 'Your question or request in natural language' by specifying what kinds of questions work best and that the tool fills arguments automatically.

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 and resource: it routes questions to one of many tools/sources and returns structured answers with citations. It explicitly distinguishes itself from web search and lists concrete domains and example queries, making its purpose highly identifiable.

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

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

It gives explicit when-to-use guidance: prefer over web search for current/historical factual data, use for 'what is', 'look up', 'find', 'get the latest', etc. It also states 'START HERE for most questions', providing a clear decision rule. It doesn't enumerate alternatives, but it directly addresses the main alternative (web search) and gives strong use-case heuristics.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that candidate routing improvements can be enabled live, that none is currently active, that it currently matches ask_pipeworx exactly, and that it does not fall back to another tool. This gives the agent important behavioral context about potential variability.

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 somewhat verbose with historical details, but the key facts are front-loaded and each sentence adds transparency about beta status, current equivalence, and usage intent. The redundancy around matching ask_pipeworx is minor given the importance of setting expectations.

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 could explain the exact response shape more concretely, but it does say the response shape is identical to ask_pipeworx, which is a useful anchor. The input side is fully covered by the schema, and the tool's experimental nature and fallback behavior are well documented.

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

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

The input schema already provides 100% coverage for the parameters, including aliases q, text, and input. The description only says 'same arguments' as ask_pipeworx, which confirms consistency but does not add meaningful semantics beyond what the schema already provides.

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

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

The description clearly identifies this as a beta universal router with the same 5,798 tools, same arguments, and same response shape as ask_pipeworx, while explicitly distinguishing it as the experimental edge. This sets clear expectations that it is not the stable router.

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 to use it exactly like ask_pipeworx when the newest routing is desired, and clarifies that results are compared against the stable router to decide merges. The alternative ask_pipeworx is implicitly the stable choice when experimental routing is not wanted.

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 and idempotent; the description adds genuine behavioral detail: it uses only the tool result, returns verbatim evidence, can explicitly refuse with enumerated reasons, and costs an extra LLM call. No contradiction with 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 purpose and usage are front-loaded and most sentences earn their place. The dense single paragraph is acceptable given the tool's complexity, though the precise '5,798 across 1517 sources' count is optional detail.

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

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

With no output schema, the description supplies the full return shape and all refusal reasons, and it explains both the use case and the casual-lookup alternative. The input side is fully covered by the schema, so nothing needed for correct invocation 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 coverage is 100% and every parameter is an alias for 'question', so the schema already carries the parameter meaning. The description adds no field-level detail, but with full coverage 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 anchors the tool as a 'hallucination-resistant answer mode' for high-stakes reads and states that it extracts answers only from tool output, which clearly distinguishes it from ask_pipeworx and other siblings. It also names the sibling variant explicitly, so an agent can tell them apart without inferring.

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

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

It gives explicit when-to-use guidance ('quoted, cited, or acted on', 'must not invent facts') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), plus the cost tradeoff. This is unusually actionable guidance for a tool with several similar siblings.

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

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

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are already strong; the description adds substantial context on top: account/paid-tier requirements, 15-90s latency expectations, the findings-packet return shape (verbatim evidence + confidence + source + fetched_at + gaps[] + contradictions[]), a no-hallucination guarantee ('never invented'), and semantic-excerpting behavior. No contradiction with annotations — readOnly agrees with a research tool.

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

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

The description contains a leaked editorial placeholder — '(one large block about second iteration / hop / `hop` field / citation_uri...' — that reads as author notes left in the final text. Content is also duplicated: the citation_uri/resolvable-URI guarantee and the contradictions[] scan each appear twice nearly verbatim, and depth-tier behavior is repeated across the schema, the garbled block, and the clean text. Front-loading is good (account requirement first), but the repetition and unedited block are material structural defects.

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 and only 2 parameters, the description delivers the full operational picture: auth requirements, pricing tiers, latency, return packet structure, citation resolvability, and gap/contradiction behavior. Nothing an agent needs to call it correctly is missing — though the garbled duplication makes that information harder to extract cleanly than it should be.

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 depth enum description already documents facet counts, hops, and the contradictions scan. The description adds value beyond the schema by tying 'thorough' to a paid plan requirement and giving latency expectations per tier. This exceeds the baseline-3 for full schema coverage but does not drastically re-explain the parameters.

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

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

States a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call' with explicit negation ('this is NOT open-web search'). Clearly distinguishes from siblings by naming ask_pipeworx for single lookups and describing the facet-decomposition mechanism.

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?

Gives explicit routing rules: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' Also frames the ideal use case positively: 'Best for broad/multi-part questions over structured data' with concrete examples. No ambiguity about when this tool beats its 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?

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 read-only/idempotent behavior, and the description adds substantial context: source fan-out, soft-failing USPTO patents, expected empty FDA sections, resolved:false for private companies, and sources_used/sources_failed semantics. This goes far beyond the minimal safety hints.

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

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

The description is dense and front-loaded with examples, but also long and run-on, with repeated clarification of company/ticker interchangeability that the schema already states. Every sentence carries useful information, yet the structure could be tighter without losing 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 multi-source tool with no output schema, this description is thorough: it explains all major sections, empty-result semantics, failure behavior, and parameter resolution. An agent has enough information to call it correctly and interpret expected outcomes.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds valuable nuance beyond the schema: both type values behave identically, value accepts ticker/CIK/name, CIK should be zero-padded, and name resolution goes through SEC EDGAR. This justifies above baseline without being redundant.

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

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

The description opens with concrete user utterances and a specific verb-resource pairing: 'full cross-source profile of a US public company in ONE parallel call.' It clearly defines what the tool returns and distinguishes it from chained single-pack lookups, so an agent can tell it apart from siblings like resolve_entity or compare_entities.

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

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

It explicitly says to prefer this tool over chaining SEC/XBRL/news lookups when a holistic view is requested. It also notes acceptable inputs and describes fallback behavior for private companies, giving the agent clear selection and invocation guidance.

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

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

Annotations already declare readOnlyHint, 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?

Beyond the read-only/idempotent annotations, the description discloses extensive behavioral traits: pairing_unverified is set whenever pairs are returned, legs with unknown metric_type/match_subtype are never paired, null temporal_alignment means 'could not be computed' rather than confirmed alignment, and the tool does not model Kalshi's fee schedule so all spreads are gross. It even reveals that compatibility warnings can be non-empty despite matched_pairs>0, which is a critical non-obvious 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 well-organized with CAPS labels and dense with information, but it is very long and contains redundancy: the warning to read compatibility fields even when matched_pairs>0 is repeated, and the temporal_alignment null semantics are explained twice. While every paragraph adds value, tighter editing would improve scannability for an agent.

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

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

For a tool with no output schema, the description is remarkably complete: it enumerates the return fields (top_spreads_pp, compatibility_warning, compatibility_codes[], flags[], temporal_alignment{}, fees_note, skipped_cross_type/subtype, low_confidence_pairs[]), explains the meaning of every compatibility code, and covers edge cases like null alignment and unknown leg types. An agent has enough context to invoke the tool and interpret its response 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 each parameter already has a description. The description adds meaningful semantic context by framing topic as a pre-mapped shortcut mode, explaining that explicit ticker/slug override the topic-mapped side, and stating that both modes run the identical token-overlap matcher. This enriches the agent's understanding of how the parameters interact beyond the schema's individual 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?

The description opens with a precise statement of purpose — "Cross-venue spread between Kalshi and Polymarket for the same resolving question" — naming both the resource (cross-venue spreads) and the behavior (computing/reporting them). It also distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by emphasizing the Kalshi–Polymarket cross-venue focus and the two operating modes.

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

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

The description clearly explains when to use each mode: topic shortcuts for 10 pre-mapped macros, and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped ≠ tradeable. However, it never explicitly names sibling tools as alternatives or states when NOT to use this tool versus those siblings, so the guidance is context-rich but lacks formal 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=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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial non-obvious behavior: ambiguous matches return figi_candidates rather than asserting, unresolved identifiers appear under 'unresolved', enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, and each call cascades through multiple lookup endpoints. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage guidance, and the detailed type-specific caveats are valuable. It is dense and somewhat long, but the length is mostly earned given the tool's two entity types and identifier-ambiguity edge cases.

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 what the tool returns, and it covers identifiers, source labels, unresolved values, ambiguity handling, fallback behavior, and ownership information. An agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is already 100%, and the description adds significant extra meaning: accepted input forms for company (ticker, CIK, ISIN, name), the ISIN-to-LEI mapping behavior, and the crucial warning to pass the issuer name exactly as printed rather than the full noun phrase. This materially improves correct parameter use.

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 names a specific operation — resolving user-spoken names to canonical/official identifiers — and clearly scopes it to company and drug entity types. It distinguishes this tool from siblings by emphasizing that it produces the IDs other tools require as input, and it opens with representative user phrasings.

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

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

It gives explicit trigger phrases and the direct instruction 'Use FIRST whenever you have a name but need an ID.' It does not name sibling tools like entity_profile or compare_entities or explicitly state when NOT to use this tool, so it falls just short of full routing guidance.

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

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

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.