Domains

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context: the default free model, that an Anthropic key is passed through (with direct cost to the user), and the per-model return structure. It does not contradict annotations and goes beyond what they state.

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

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

Three sentences: purpose, model/cost clarification, and output/use cases. Fully front-loaded with the core behavior first, no filler, 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?

With no output schema, the description still explains the return structure (per-model {score, confidence, signals, raw_response} + combined view) and covers model options, cost, and use cases. It is concise and reasonably complete, though a bit more detail on what 'signals' means could add clarity.

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 meaning beyond the schema by explaining the default model, how the _apiKey parameter enables Anthropic at the user's cost, and why 'context' helps disambiguate. This richness justifies a 4, though not a 5 since entity/models/context are already well described.

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 'Probe' and a clear resource ('one or more LLMs'), stating it scores visibility (0-100) per model. It distinguishes itself from siblings like compare_entities and scan_competitor_ai_presence by focusing on LLM knowledge and providing a quantitative score.

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 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving clear contexts for use. However, it does not mention exclusions or contrast with alternative sibling tools, so it falls 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable insight beyond annotations: it routes through 5,596 tools across verified sources, fills in arguments, and returns to locations with stable citation URIs. It does not describe error cases or rate limits, but the core behavior is transparent.

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

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

The description opens with a strong, front-loaded directive and immediately lists the tool's value, mechanism, and trigger phrases. It is longer than average, containing some redundancy between the long domain list and the 'or anything requiring authoritative structured data' phrase, but every section contributes useful operational 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 one required parameter and no output schema, the description nevertheless tells the agent what to expect: a structured answer with pipeworx:// citations. It covers a wide range of question types and gives representative examples. Missing are possible edge-case behaviors like incomplete answers or unanswerable queries, but the agent has enough 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?

The input schema already documents the question param and all five aliases with 100% coverage, so the description doesn't need to compensate for a schema gap. The description's examples informally help users understand the kind of natural language, but that is more scoped behavioral guidance than semantic parameter detail.

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 clear verb and resource: route a natural-language question to the appropriate data source and return a structured answer with citation URIs. It distinguishes itself from generic web search by listing covered domains and data types, but it does not differentiate itself from its sibling variants ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description gives exceptionally strong usage direction: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and a set of concrete example questions. However, it does not mention any specific sibling alternatives or when to prefer them over this tool, so the exclusion guidance is incomplete.

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 carries the burden of explaining the experimental behavior — behavior is live and can change when a candidate is under test, and it explicitly states there is no candidate at the moment so it currently matches ask_pipeworx exactly. Annotations (readOnly, idempotent) already cover the read-only safety profile, and the description adds useful context above that, including the reassuring 'this IS a full working router' fact. 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 efficiently organized and every sentence contributes something functional: what it is, its current state, when to call it, and a clarifying assertion about it being a real working router. However, the 'identical/same/exactly like ask_pipeworx' idea repeats multiple times (the words 'exactly' and 'same' appear in several clauses), and the date-specific detail ('retired on outcome 2026-07-26') will age stale in a static definition.

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?

Nothing needed for calling it is missing: required param is obvious, alias params are quoted in the schema, annotations Fully describe its safety profile, and the description tells the agent That the live state may switch. The only noticeable gap is the absence of an explicit response shape — the definition says 'same response shape' but doesn't describe it inline, so an agent would need to know ask_pipeworx's response format to fully understand what's returned.

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% — question is described and all five aliases (q, text, input, alias, prompt) are listed in the schema. The description only says 'same arguments as ask_pipeworx' and adds no per-parameter semantics beyond that, which keeps it at the schema-heavy baseline of 3.

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

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

Begins with a precise noun and verb: 'identical universal router' that forwards a question to the same pool of tools as ask_pipeworx — and immediately names what makes it distinct: the beta candidate routing improvements. An agent can separate it from the stable twin (ask_pipeworx) and from the grounded variant (ask_pipeworx_grounded) just from the first sentence.

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

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

Explicitly says when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the results are compared against the stable router to decide merges. It does not list when not to use it (e.g., 'use ask_pipeworx_grounded when you need grounded answers'), so the exclusions are left for the agent to infer from the stable-vs-experimental contrast.

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 only indicate read-only/idempotent/non-destructive behavior, but the description adds the critical operational details: it uses only tool result content, can return explicit refusals with specific reasons, and costs an extra LLM call. This is substantial disclosure beyond what the annotations provide.

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

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

The description is detailed but reasonably front-loaded, leading with the core purpose and then the usage conditions. Slightly more verbose than strictly necessary because it recapitulates the full response shape and refusal reasons, but every sentence serves a functional purpose especially since there is no output schema.

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

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

The tool's behavior, output fields, refusal reasons, cost trade-off, and when-to-use guidance are all fully specified in the description. Since there is no output schema to document the return value, the description carries that burden and does so completely enough for an agent to invoke it correctly.

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

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

The schema already covers all parameters, including the question aliases, with 100% description coverage. The description does not add any parameter-specific format, constraint, or example beyond what the schema holds, so it meets but does not exceed the baseline for a fully documented parameter set.

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 hallucination-resistant answer mode that extracts answers exclusively from fetched tool results. It is explicitly distinguished from ask_pipeworx by the same routing plus the grounded extraction step, so an agent cannot confuse the two.

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 tells the agent when to use this mode — when answers will be quoted, cited, or acted on and the agent must not invent facts — and when not to, explicitly stating to prefer ask_pipeworx for casual lookups due to the extra LLM call. This is unambiguous and practical.

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 disclosing the resolver contract (market_match_confidence, alternatives, suggestions), the low_confidence_match short-circuit, the market_closed_or_inactive status, illiquid wide-spread handling, and resolution-rule risks like refund_50_50. It even warns about the 24h-move alert and recurring flat-50¢ void settlements, giving agents a clear picture of failure modes and safety mechanisms.

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

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

The description is very long and overflowing with intricate details (classifiers, response shapes, resolver contract, news fields, resolution rules). While it is well-organized with capitalized section headers and front-loaded with the core purpose, it is not concise. Every sentence adds some value, but the sheer length makes it heavier than necessary.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers response shapes (result.market, analysis, evidence), resolver contract fields, parent_event extraction, news fallback fields, safety short-circuits, and cancellation-rule parsing. It even tells agents to inspect match confidence before trusting the analysis, leaving no major gap in operational instructions.

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 describes all three parameters with 100% coverage, including the quick/thorough depth and include_raw behavior. The description repeats the market input format (slug, URL, question text) but adds no new semantic meaning beyond what the schema already provides. The fan-out examples are informative for the tool's behavior but not tied specifically to parameter semantics, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly distinguishes it from sibling tools like arbitrage or edge trackers by focusing on data fan-out and evidence packets.

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

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

The description provides explicit 'Use for' contexts and gives detailed fan-out examples for different bet categories (BTC, Fed, Hormuz, etc.). However, it does not explicitly name alternatives or when-not-to-use cases, so it misses the 'when-not' part of a perfect 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 meaningful behavioral context beyond the annotations by stating the tool is 'Keyless' and describing the exact return payload: DNS names, issuing CA, validity window, revocation status, and a deduplicated hostname list. It also clarifies that include_subdomains enables subdomain enumeration. This supplements the readOnly/idempotent annotations without contradicting them, though it omits details like pagination or rate limits.

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

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

The description is four sentences, each earning its place: purpose, usage guidance, subdomain behavior, and output summary. It is front-loaded with the primary action, immediately followed by practical use-case examples. There is no fluff or redundant repetition of the schema or annotations.

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

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

Given the tool has no output schema, the description compensates thoroughly by listing all return fields (DNS names, CA, validity, revocation status, discovered hostnames). It also specifies the default behavior of include_subdomains and notes that the hostname list is always complete. This provides a sufficiently complete mental model for an agent to invoke the tool 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?

Although the schema already has 100% coverage for parameter descriptions, the tool description adds extra semantic value. It explains that include_subdomains 'is what enables subdomain discovery' and that the discovered-hostnames list is always complete regardless of the limit. This goes beyond the schema's static descriptions and helps the agent understand the implications of parameter choices.

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: finding SSL/TLS certificates for a domain from Certificate Transparency logs. It uses a specific verb ('Find') and identifies both the resource (certificates) and the source (Cert Spotter), which differentiates it from other domain-related tools. It also explicitly outlines use cases like finding subdomains and checking expiration, leaving no ambiguity.

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

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

The description provides explicit when-to-use guidance with 'PREFER OVER WEB SEARCH' and lists concrete example queries ('what certificates does X have', 'find subdomains of X'). It also explains when the include_subdomains flag is relevant. However, it does not mention when not to use the tool or alternative tools except for web search, so it lacks a full exclusion statement.

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 and idempotent. The description adds useful behavioral context: it checks multiple TLDs in one call, returns availability/expiration, accepts full domain input, and documents the default TLD list and max 15. 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 sentences covering purpose, usage mechanics, and alternative. It is slightly long but every sentence contributes and the main purpose is front-loaded.

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

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

No output schema exists, but the description explains the return shape ('available true/false (+ expiration if taken)'), default behavior, and how it relates to sibling tools. Complete for a simple read-only lookup 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 both parameters have detailed descriptions. The description reinforces the default TLD list and the base-name handling but adds little beyond the schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Check whether a name is available to register across MULTIPLE TLDs at once'. It clearly distinguishes itself from domain_status by calling this 'the bulk/brainstorm version' and explicitly naming domain_status for single-domain detail.

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

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

Explicit use cases are listed: 'Use for "is X available"', 'find an open domain for my project', 'which TLDs is X free on'. It also provides a clear alternative: 'Single-domain detail is domain_status; this is the bulk/brainstorm version'.

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 as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), metric details, off-calendar fiscal year handling, result sorting, and citation URIs. 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 lengthy but deliberately structured with trigger phrases, a precedence rule, type-specific data details, and output notes. Every sentence provides valuable information, though terms like 'parallel call' are slightly redundant with 'side-by-side comparison'.

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

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

No output schema exists, but the description explains the return includes paired data and citation URIs, mentions sorting, and covers data sources and fiscal-year quirks. Minor gaps like error handling are outweighed by the rich context provided.

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

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

Schema descriptions cover both parameters, so baseline is 3. The description enriches this with concrete examples for type (company/drug), ticker/CIK formats, and explains what metrics each type pulls, making the parameters more actionable beyond schema definitions.

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

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

The description clearly states the tool performs a side-by-side comparison of 2–5 companies or drugs in a single call, using specific trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes from sequential single-pack lookups and implies a different scope from sibling tools like entity_profile.

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

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

Provides explicit trigger phrases ('Compare X and Y', 'X vs Y') and states 'ALWAYS PREFER over sequential single-pack lookups', giving clear when-to-use guidance and an alternative approach. It does not name a specific sibling tool, but the instruction is strong and unambiguous.

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 cover read-only/open-world/idempotent, so the bar is lower; the description still adds major extra context: account/pricing gates, paid plan requirement, facet decomposition and parallel routing, gap and contradiction passes, semantic excerpting, no invention guarantee, fetchable citations, and latency expectations. All beyond what annotations or schema provide.

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

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

Dense, purposeful, and well organized. Critical caveats (account required, fallback tool, paid tier) are front-loaded, followed by how the tool works, ideal use cases, output contents, and latency envelope. Every sentence earns its place even though the description is long for a 2-parameter, 1-required 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?

No output schema, but the description nonetheless explains the exact return shape: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, and explicit gaps, plus contradictions for standard/thorough. It also covers large-record behavior, citation resolvability, and runtime, so an agent can invoke the tool with correct expectations.

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 genuine extra value by illustrating the intended shape of the question parameter with an example ('compare X and Y...') and by connecting the depth parameter to timing and additional passes, even though part of that is reflected in the schema already.

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

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

Clear, specific verb and resource: grounded multi-source research across 1,465 structured data sources in one call, explicitly NOT open-web search. Also differentiates itself from the ask_pipeworx family by naming the contrast, so an agent can select deep_research without ambiguity.

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

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

Explicit usage and exclusion guidance: use ask_pipeworx if the user is not signed in or for a single lookup; use deep_research for broad/multi-part questions over structured data. Names the alternative tool and the exact conditions that route to 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, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N most relevant tools with names, descriptions, and full input schemas, and notes that results are ready to call directly with no second schema lookup needed. This goes beyond annotations and clarifies the tool's output 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 organized and front-loaded with a clear purpose statement. The list of example domains is somewhat long but directly informs the agent about the tool's coverage. Each sentence contributes meaning, though the domain list could be trimmed without losing the core message. It is efficient and not overly verbose.

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

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

There is no output schema, so the description appropriately explains what the tool returns: names, descriptions, full input schemas with examples, and readiness to call. This sufficiently covers the return contract for a simple discovery tool. Minor gaps like result ordering are unimportant and do not affect 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 all parameters are already well-documented in the schema. The description mentions 'top-N' and 'query' but doesn't add additional meaning beyond the schema's parameter descriptions. The baseline of 3 is appropriate because the schema carries the full semantic weight; the description does not compensate further.

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+resource: 'Find tools by describing the data or task.' It goes on to list example domains and distinguishes itself from siblings by being a meta-search tool that discovers other tools rather than performing those tasks directly. This is well differentiated from the sibling tools like domain_lookup or certificate_search.

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 when you need to browse, search, look up, or discover what tools exist' and even states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies that if a specific tool is already known, this discovery tool is unnecessary.

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 context beyond annotations by specifying the return fields and the universal TLD support. However, it does not disclose potential caveats like privacy redaction of registrant data, and 'full registration details' could be slightly overpromising. Overall, it adds useful behavioral context consistent with the 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 two sentences, front-loaded with the main action, and every sentence adds value. It is concise without sacrificing necessary detail.

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

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

Given the tool's simplicity, one parameter, and annotations covering safety, the description is largely complete. It could benefit from mentioning alternatives or when to prefer this over domain_status, but the output schema likely covers return details. Overall adequate.

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

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

Schema coverage is 100% with a clear description and examples for the domain parameter. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('full registration details for a domain') and lists specific return fields, making the tool's function unambiguous. It implicitly distinguishes from siblings like domain_status by covering comprehensive registration data.

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 some usage context ('Works for any TLD') but does not explicitly state when to use this tool over alternatives or when not to use it. No mention of sibling tools or 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 the tool as read-only, idempotent, and non-destructive, lowering the bar. The description adds behavioral context by specifying it returns registration status and expiration date, with the latter conditional on registration. This goes beyond the annotations, though it doesn't mention rate limits or other operational details.

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

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

The description is a single, front-loaded sentence that immediately states the tool's purpose and key outcome. Every word contributes value, and the structure is highly efficient.

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

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

For a simple tool with one parameter, a clear output schema, and thorough annotations, the description covers the essential use case. It explains what the tool does and what result to expect without unnecessary detail.

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

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

The input schema has 100% coverage, with the 'domain' parameter already described and exemplified. The description does not add additional parameter semantics 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 clearly states the tool's function: checking if a domain is registered or available, and returning registration status and expiration date. The verb 'check' and resource 'domain' are specific, but it does not explicitly distinguish itself from sibling tools like domain_lookup or find_available_domains, which may have overlapping functionality.

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 a lightweight, quick check, giving clear context for when to use it. However, it lacks explicit exclusions or alternatives, such as noting when to use domain_lookup or find_available_domains instead, which would be valuable given the large sibling list.

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

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

Annotations already mark readOnly/idempotent/non-destructive, but the description adds valuable behavioral context beyond those: it fans out across multiple sources, returns up to 5 filings with specific URIs, mentions the USPTO API sunset and soft-fail behavior, and describes the GDELT→GNews fallback. This gives the agent a clear picture of what happens internally and what to expect in response.

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

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

The description is dense but every sentence earns its place: it starts with example queries, states the core purpose, explains the cross-source fan-out, lists return fields, and covers input constraints and fallback behaviors. Though it's a long run-on paragraph, the information is highly relevant and front-loaded, with only minor redundancy (e.g., names not supported repeated in schema and prose).

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 multi-source aggregation tool with no output schema, the description is remarkably complete. It enumerates the specific return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), notes the patents API sunset and soft-fail, and explains the input prerequisites. This fully equips an agent to invoke the tool and interpret its 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% and both parameters ('type' and 'value') are well documented in the schema itself. The description largely repeats the schema's constraints (ticker/CIK, names not supported), adding only minimal extra value beyond examples like 'AAPL' and '0000320193.' With full schema coverage, 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 it provides a 'full cross-source profile of a US public company in ONE parallel call' with multiple example queries (e.g., 'brief me on Tesla'). It distinctly differentiates from sibling tools by emphasizing it aggregates SEC, XBRL, USPTO, news, and GLEIF data, positioning it as the go-to for holistic company research rather than single-source 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?

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies the required input format (ticker or zero-padded CIK) and instructs to 'use resolve_entity first if you only have a name,' clearly outlining when to use this tool versus alternatives.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds meaningful behavioral context: availability is a live registry (RDAP) signal, keyless, and results are ranked with exact match and .com first. This goes beyond what annotations alone communicate.

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 strictly necessary but each sentence serves a purpose: purpose, examples, use cases, output behavior, and alternatives. It is front-loaded with the main purpose and well-organized, though slightly verbose.

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

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

With no output schema, the description explains enough about the return value (available domains ranked, exact match + .com first) and the live/keyless nature of the data. It also covers alternatives and typical use cases, making it nearly complete for this 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 already provides 100% coverage for all three parameters: keyword, tlds, and include_variations. The description reinforces these with examples but does not add new semantic detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches for available domain names from a keyword and gives concrete examples (getacme.com, acmehq.com). It also distinguishes itself from sibling tools by explicitly naming domain_status and check_availability, making the purpose unmistakable.

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

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

The description provides explicit use case phrases like "find me an available domain for X" and "domain name ideas for my startup". It also gives clear alternatives: "For a single specific domain use domain_status; to check one name across TLDs without variations use check_availability." This exceeds basic 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 destructiveHint=true and idempotentHint=true, covering the delete and repeat-safety traits. The description adds context about clearing sensitive data and aligns with the destructive nature, but does not describe non-existent key handling or other behavioral details beyond what annotations provide.

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

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

The description is two sentences: the first states the core action, the second gives usage context and sibling references. Every sentence earns its place with no filler.

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

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

For a simple one-parameter delete tool with safety annotations, the description provides sufficient context to select and invoke it correctly. It doesn't discuss return values or error cases, but these are less critical given the low complexity and absence of an output schema.

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

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

Schema fully documents the single 'key' parameter with 100% coverage and a clear description. The tool description only references 'by key' without adding extra semantic meaning, so the baseline 3 for high schema coverage applies.

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

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

The description clearly states 'Delete a previously stored memory by key' – a specific verb, resource, and mechanism. It distinguishes from sibling tools remember and recall by focusing on deletion.

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

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

Explicitly lists when to use it ('context is stale, the task is done, or you want to clear sensitive data') and points to complementary tools ('Pair with remember and recall'). However, it does not explicitly state when not to use it, so it stops short of 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral context by explaining that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations but does not disclose potential edge cases (e.g., timeouts, error handling, rate limits), so it's adequate but not rich.

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

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

The description is concise and well-structured: the first sentence states the primary purpose and process, the second clarifies the output and use cases via a 'Useful for' list. No redundant or irrelevant information; 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?

For a simple read-only tool with two parameters and no output schema, the description is complete enough. It covers what the tool does, the process, output format ('single text blob'), and typical use cases. It lacks details on failure modes or constraints beyond max_links, but these are not critical for such a straightforward 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 both 'url' and 'max_links' already described in detail (e.g., default and max). The description adds no new parameter-specific meaning beyond what the schema provides; it only restates the output contains links. Baseline for full coverage is 3.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL.' It specifies the process (fetches page, extracts title/description/key links, emits standard format) and distinct use cases (indexing client sites, drafting for own project, auditing competitors). This differentiates it from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on the concrete output artifact.

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 contexts for use: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly state when not to use the tool or suggest alternative tools for similar tasks, lacking explicit exclusions or alternatives by name.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of listing only active subscriptions, which is not conveyed by 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 two sentences, front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence earns its place with no wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what it does, what it returns, and when to use it. No additional context is needed.

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

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

Schema provides 100% coverage for the single parameter `include_inactive` with a clear description. The tool description adds the context that active subscriptions are the default, but does not add new details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List the caller's active subscriptions') with a specific resource and scope. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

Provides clear usage context: use to review what you're monitoring before adding more, or to find an id to cancel. This implicitly contrasts with subscribe/unsubscribe tools, though it does not explicitly name alternatives.

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

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

The description richly discloses behavior beyond annotations, including the claim_token return mechanism for anonymous filings, how to follow up, rate limiting ('5 per identifier per day'), and that it is free and doesn't count against quota. It also explains how the feedback is used (daily digests, roadmap impact). 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 longer than average but every sentence carries important information. It is front-loaded with purpose and usage, then covers edge cases (other servers, claim_token, limits). It could be tightened slightly but remains efficient and well-organized.

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

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

Despite having no output schema and a nested object parameter, the description covers all essential aspects: when to use, what to include, how to retrieve follow-up status, rate limits, and the distinction from other MCP servers. It gives enough context for an agent to use the tool effectively without needing additional documentation.

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 parameter descriptions are already complete. The tool description adds meaningful usage context beyond the schema: it clarifies the claim_token flow ('pass it back later'), warns against pasting end-user prompts, and ties the 'message' parameter to specific feedback types. This goes beyond what the schema alone provides.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and differentiates from sibling tools by its focus on reporting issues about Pipeworx tools, not querying or research.

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

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

It provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count) tuples, and is cached for 5min-1h. This goes well beyond what annotations cover.

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 well-structured sentences. The first sentence states the core function; the second lists targeted use cases; the third provides technical context (no PII, derived from CF analytics-engine, caching). No filler, every sentence contributes.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the essential information: what is returned (top tools, packs, call volume), the window options, and the underlying data characteristics. It does not describe the exact output format, but that is largely predictable from the description. It is complete enough for an agent to confidently 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 schema already has 100% coverage for the single parameter 'window', including its enum values and default. The description adds extra meaning by explaining that shorter windows surface what's hot right now while longer windows show steady-state demand, enriching the parameter's semantics beyond the schema.

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

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

The description clearly states the tool's function: it returns top tools, top packs, and total call volume over a recent window. The verb 'Returns' plus the resource (Pipeworx trending data) make the purpose unambiguous. It also distinguishes itself from siblings by emphasizing it reflects what other AI agents are calling, not just generic discovery.

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

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

The 'Useful for' section provides three specific use cases, which implicitly guides when to choose this tool over alternatives like discover_tools. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls just short of 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?

Annotations declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral detail beyond annotations: the SEMANTIC ANCHOR (Jaccard similarity threshold, skipped_low_similarity), PARTITION FILTER (placeholder slug filtering, >20% null signal), and FILL CHECK (realizable_edge_pp vs theoretical, thin_legs, and the explicit warning 'do not trade it'). This gives agents a clear model of internal computation and safety guards.

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, the description is densely packed and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and mode-specific examples. It is front-loaded with the core purpose, and every sentence adds critical information—no filler or redundancy. The length is justified by the tool's complexity.

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

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

Given no output schema, the description explicitly states the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers no-arg behavior, parameter modes, filters, fill-check pricing, and cross-tool integration. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description drastically enhances both parameters. For 'event' it gives example slugs, clarifies full URLs are accepted, and explains the walk over child markets. For 'topic' it provides example seed questions and describes the cross-event flattening behavior. This goes far beyond the schema's simple type/description fields.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges (edge detection) and polymarket_fill_risk (fill risk). It further enumerates three call modes (trending_scan, event, topic), each with a distinct purpose.

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 usage instructions: 'Call with NO args for a trending_scan... pass event... or topic...' It also provides decision guidance: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It names a sibling alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' No exclusions are needed beyond the clear mode-based 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?

With readOnlyHint=true, idempotentHint=true, and destructiveHint=false already provided, the description goes far beyond annotations. It discloses output details (edge_pp_net after slippage, kelly capped at 0.25, 24h-move warning), internal filters (placeholder-slug, 20% placeholder fraction skip), design constraints (partition arbs return kelly_fraction_half=0 at parent level), and caching ('Cached 1h at the KV level keyed on all knobs'). This is exemplary transparency, exceeding what structured annotations can 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 highly structured and information-dense. It is front-loaded with the core purpose, then organized into response segments, output fields, knobs, and diagnostics. Every section serves a purpose—especially given the lack of an output schema. While more concise alternatives exist, the length is justified by the tool's complexity, and the structure aids scanning.

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

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

There is no output schema, so the description bears full responsibility for explaining return values. It does this thoroughly: top-level by_segment keys, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h-move warning), fed_candidates/fed_note behavior, and _diagnostics with funnel counters and filter_skips. It even explains why segments may be empty. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning not found in the schema, such as the 'TRADEABLE-EDGE KNOBS' section explaining how min_liquidity and max_spread_pp drop opportunities, and the nuance that min_partition_leg_kelly applies per-leg inside top_legs because parent kelly is always 0. This goes beyond simply restating parameter descriptions, though it does not detail every parameter.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the use case ('what should I bet on today') and clearly distinguishes this from sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) by describing the multi-model discovery purpose. That is a precise, differentiating purpose statement.

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 strong context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when knobs like min_liquidity and max_spread_pp should be adjusted. However, it does not explicitly name alternative tools or state 'use X instead when you need Y' — a minor gap given sibling tools like polymarket_arbitrage exist. Otherwise the usage context is clear.

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

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

Annotations declare read-only, idempotent, and non-destructive behavior, but the description goes far beyond that: it explains snapshot write triggers, TTL bounds, gap causes, and how decay is computed (daily closes, not intraday). This is exactly the kind of behavioral nuance that annotations cannot 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 exceptionally well-structured with clear 'Args:', 'RESPONSE:', and 'LIMITS:' sections. Every sentence adds operational detail (response fields, lifespan interpretation, TTL bounds) without fluff. It is appropriately sized for the tool's complexity and front-loads the primary use case.

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

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

Despite having no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) and critical limitations (TTL, snapshot gaps, decay calculation). It gives a complete mental model for an agent to invoke the tool and 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 coverage is 100% and both parameters are already described with defaults and allowed values. The tool description adds some context (e.g., 'snapshot family', lookback clamp) but largely restates the schema. No significant additional semantic value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the core question ('how long has this edge existed and is it shrinking?') and differentiates itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

It provides clear context for when to use this tool — analyzing edge longevity and decay — and contrasts it with current-edge tools via the fresh-vs-old edge example. It does not explicitly name alternative tools or state 'when not to use,' but the implied usage is strong and actionable.

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, but the description adds substantial behavioral context: it walks the order-book ladder, returns specific fill metrics, names risk endpoints (e.g., forced_directional_risk, thin_legs), and explains the dominant loss mode (partial fills converting arb to 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?

The description is a dense single block but front-loads purpose and clearly separates modes with 'SINGLE-MARKET:' and 'BASKET:'. Every sentence adds value, though it could be improved with bullet-point structure for readability. It's appropriately sized for the tool's complexity, but slightly overlong as a wall of text.

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

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

Given no output schema, the description compensates by enumerating return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) and explaining the basket mode's theoretical vs realizable comparison, capture_ratio, profit_usd, thin_legs, and risk naming. It also provides usage threshold (~$500) and failure mode, making it fully contextual.

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 enriches parameter meaning significantly. It clarifies that size_usd means 'max spend on buys' vs 'target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg)' in basket mode. It also explains side defaults ('auto' for basket) and how size is clamped, far exceeding what the schema 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb (check) and resource (edge against order-book depth). It clearly distinguishes two modes (single-market vs basket) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk and realizability.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable) and warns against partial basket fills, giving clear when-to-use and when-to-avoid context relative 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?

Despite annotations already marking the tool as read-only and idempotent, the description adds substantial behavioral detail: compatibility_warning logic, temporal_alignment semantics, and the meaning of skipped_cross_type/subtype counters. It explains unexpected outcomes (most topics return warnings) and internal matching limitations, going well beyond the annotations.

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

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

The description is lengthy but well-structured with clear sections (modes, response, safety fields). Every sentence delivers substantive information without fluff. It is near the upper limit of acceptable length, but the density justifies it.

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

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

With no output schema, the description fully covers return values (leg-by-leg prices, top_spreads_pp), internal state (compatibility_warning cases, temporal_alignment), and edge cases (skipped counters). For a complex cross-venue matching tool, this is exceptionally complete.

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

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

Schema covers 100% of parameters with descriptions, but the description adds crucial relationships: how topic maps to the other two parameters, when to use explicit overrides, and the full list of valid topic shortcuts. This adds meaning beyond the schema, though the schema already does heavy lifting.

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

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

The description clearly identifies the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (two prediction markets) and the operation (comparing prices). The two-mode structure (topic shortcuts vs explicit pairings) further clarifies scope and distinguishability from sibling tools like polymarket_arbitrage, which focuses on intra-venue arbitrage.

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 offers strong usage context: it explains when the spread is meaningful ('when the bet shapes are equivalent') and when it is not, and warns that 'pre-mapped ≠ tradeable.' It does not explicitly name alternative tools, but it clearly conveys when to rely on the results and when to expect compatibility warnings. This is clear context with implicit 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 indicate read-only and idempotent behavior. The description adds useful context beyond annotations by noting scoping to the user's identifier (anonymous IP, BYO key hash, or account ID), which clarifies data isolation. 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 sentences, each serving a distinct purpose: core function, usage rationale with examples, and scoping plus sibling relationships. It is front-loaded with the primary action and contains no superfluous content.

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

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

The tool is simple (one optional parameter, no output schema), and the description fully covers its behavior: retrieval, listing, scoping, and relationship to remember/forget. Nothing essential is missing for an agent to use it correctly.

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

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

The input schema already covers the 'key' parameter well (including 'omit to list all keys'). The description enriches this with concrete examples of what keys might contain (target ticker, address, research notes) and explicitly describes the omit-key behavior, adding value beyond the schema.

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

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

The description clearly states the tool's function: retrieve a previously saved value or list all saved keys. It uses a specific verb ('Retrieve') with the resource, and differentiates from siblings like 'remember' and 'forget' by explicitly naming them.

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

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

The description gives clear context for when to use the tool: to look up context the agent stored earlier, avoiding re-derivation. It also mentions pairing with 'remember' and 'forget', which provides a workflow context. However, it does not explicitly state when NOT to use it, so it stops short of a full 5.

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

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

There is a direct annotation contradiction. The annotations declare readOnlyHint=true and destructiveHint=false, yet 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. The description itself is transparent, but the structured annotations claim no modification, misleading an agent about the tool's side-effect profile.

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 with a distinct purpose: what it does/returns, how to filter and use mark_read, and additional usage notes (polling + alternative endpoint). No filler or redundancy.

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

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

There is no output schema, so the description appropriately compensates by naming the return fields (source, citation_uri, raw event payload). It also covers filtering, the mark_read side effect, polling behavior, and an alternative endpoint. The only unmentioned parameter (unread_only) is fully described in the schema, so the description is complete for this read-oriented 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 description. The description adds a concrete type example ('sec_8k') and clarifies the functional consequence of mark_read (affects future calls). This goes slightly beyond the schema, earning a 4 rather than a baseline 3.

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

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

The description opens with a specific action 'Pull fired events' and identifies the resource as 'your subscription feed'. It also lists the returned fields (source, citation_uri, raw event payload), clearly distinguishing it from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (which tracks 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 gives clear usage context: filters by type and/or since, the mark_read side effect, and that polling works fine. It also provides an alternative GET endpoint for scripts/dashboards, which helps an agent choose the right invocation. It does not explicitly exclude any sibling tools, but the guidance is sufficient for typical use.

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

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

Annotations already state readOnly, openWorld, and idempotent hints, and the description adds rich behavioral context: fan-out to multiple APIs, GDELT→GNews fallback on rate-limited/5xx responses, USPTO soft-fail due to PatentsView API sunset, and the exact return shape (changes[], total_changes, citation URIs). 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 front-loaded with user intent examples, then efficiently covers sources, parameter semantics, output format, and the alternative tool in a compact, logically organized paragraph. Every sentence earns its place; no filler or redundancy.

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

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

Given the tool's complexity (multiple data sources, fallback logic, date parsing, no output schema), the description is remarkably complete. It specifies the output structure, source-specific behavior, failure modes, and even recommends the alternative tool for static profiles, making it fully actionable for an AI agent.

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

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

The input schema already provides full descriptions for all three parameters (100% coverage), so baseline is 3. The description adds value by illustrating `since` with both ISO and relative examples, recommending '30d' or '1m' for typical monitoring, and showing `value` usage with a CIK example. This is helpful but not transformative 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 identifies the tool as a 'change feed for a company' with specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts it with entity_profile, making its purpose distinct from siblings. It starts with concrete natural-language triggers, so an agent can match queries like 'what's new with X' to this tool.

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

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

The description provides explicit when-to-use guidance via example queries and a clear alternative: 'Use entity_profile instead when you want the static profile.' It also gives practical usage details like the `since` parameter accepting '30d' or '1m' for typical monitoring and explains fallback behavior, leaving little ambiguity.

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

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

Annotations already cover idempotency, non-destructiveness, and write operation. The description adds valuable context about scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24-hour TTL) users, and the key-value storage model. This goes beyond the annotations and provides meaningful behavioral detail, though it could mention overwrite behavior or failure modes.

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 usage guidance, storage details, and sibling tool pointers. Every sentence adds distinct value without redundancy. It is concise yet thorough, making it easy for an agent to parse quickly.

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 memory-write tool, the description covers all essential aspects: intended use, key-value structure, scoping, persistence semantics, and relationships to recall/forget. No output schema is needed, and the complexity is low. The description is complete enough for an agent to invoke the tool correctly without further clarification.

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

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

The input schema has 100% coverage for both parameters, including descriptions and examples. The description adds a few usage examples (e.g., 'resolved ticker', 'target address') but does not provide substantive semantic enhancement beyond the schema. Following the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' – a specific verb with a resource. It distinguishes itself from sibling tools by mentioning persistence across conversations/sessions and by explicitly pairing with recall and forget. This makes the purpose unambiguous and differentiates it from other tools.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward' with concrete examples like a resolved ticker or user preference. It also hints at when not to use it (i.e., for transient data) and directs to alternatives ('Pair with recall... forget to delete'). This fully addresses usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: 'Each call cascades through several lookup endpoints internally', 'LEI/FIGI enrichment degrades gracefully', and the output structure ('every identifier is labelled with the source that established it, and an identifier that could NOT be resolved is stated explicitly under `unresolved`'). This goes well beyond what annotations provide, making the tool's behavior transparent.

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

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

The description is front-loaded with concrete examples and a clear purpose statement. However, it is lengthy (over 150 words) and includes dense technical details about each entity type's resolution chain. While every sentence adds value, a more streamlined version could improve readability. Still, it is well-structured and avoids wasted words.

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

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

Given the tool has no output schema, the description fully compensates by explaining the output structure (source-labelled identifiers, `unresolved` field) and edge cases (graceful degradation, non-US issuers via ISIN-to-LEI mapping). It covers both supported types, input formats, and internal cascading. The description is complete enough for an agent to understand what the tool does and what it returns.

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% (both parameters have descriptions). The description adds substantial value: for 'type' it explains the two valid values and their resolution behavior; for 'value' it provides examples and explains the accepted input formats (ticker, CIK, ISIN, name) for companies and brand/generic names for drugs. It also describes the internal enrichment and output composition, which the schema does not capture.

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 specific example queries ('What's the ticker for…', 'find the CIK for…') and explicitly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' The verb 'resolve' and resource 'entity' are precise, and the scope is well-defined.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing a clear trigger for when to invoke this tool. It also details the two supported entity types (company, drug) and explains the resolution process. While it doesn't explicitly list alternatives or when not to use, the context of sibling tools like entity_profile and compare_entities makes the usage scenario evident. Lack of explicit exclusions keeps it from 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 hints. The description adds valuable behavioral context by disclosing that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also gives an example of the kind of question it answers. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the main purpose, and includes an illustrative example. Every sentence earns its place: the first explains what it does, the second gives the use case and return values. 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?

Without an output schema, the description adequately explains returning a ranked list with score, confidence, and signal density. It covers the core workflow (probe each entity, rank, identify most/least recognized) and provides a concrete example. The annotations cover safety, and the schema covers parameters, so the description fills the remaining gaps effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra semantics beyond the schema; it mentions 'your brand + N competitors' which aligns with the entities parameter's schema description. No additional syntax or format details are provided, but the schema already documents all parameter constraints and meanings.

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 ('Compare') and clearly identifies the resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from siblings by mentioning it probes each entity with ai_visibility_check and ranks results, directly addressing competitive audits. This is unambiguous and not a tautology.

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 states the use case: 'Useful for competitive AI-marketing audits' with an example query. It implies this tool is for multi-entity comparison while sibling ai_visibility_check is for single entities, though it doesn't explicitly say 'use ai_visibility_check for a single entity'. No explicit exclusions are given, but the context is strong.

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?

Discloses important behavioral traits beyond the annotations: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30 seconds, and sources_failed will report timeouts while the rest still returns. This prepares the agent for non-obvious runtime behavior without contradicting the readOnly/idempotent hints.

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

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

Every sentence earns its place: purpose, usage, return object, ecosystem scope, and failure handling are packed into a compact paragraph. The information is front-loaded and logically structured, with no tautology 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?

Despite lacking an output schema, the description enumerates all summary fields (is_latest, license, bundle_kb_gz, etc.), mentions per-advisory details and links, and explains ecosystem limitations and failure behavior. This fully compensates for the missing schema and gives a complete picture of the tool's behavior.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds no new parameter semantics beyond what the schema already provides; it merely restates the npm ecosystem context. It does not compensate with additional syntax or edge-case 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 it is a composite npm package check that fans out to deps.dev and bundlephobia, listing specific data points (license, advisories, bundle size, etc.). This distinguishes it from sibling tools like domain_lookup or certificate_search, which serve entirely 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?

Explicitly instructs when to use ('whenever an agent asks is X safe / popular / small'), and provides a clear exclusion ('NPM ecosystem only in v1') with an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is strong guidance on both when and when not to use the tool.

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

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

Goes far beyond the readOnly/idempotent annotations by disclosing the underlying retrieval mechanism (BGE-base-en embeddings, cosine, 500-char overlapping windows), the 200K char cap with truncation flag, and the output format (top-N passages with offsets and similarity scores). This prepares the agent for edge cases without needing to invoke the tool.

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

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

Four sentences, each earning its place: core action, usage scenario, pairing guidance, and technical limits. No redundancy or filler; technical details are compactly bundled into the final sentence while keeping the front-loaded purpose immediately clear.

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?

Comprehensive for a 3-parameter tool with no output schema: it covers what it returns, when to use it, how it relates to siblings, and its hard technical limits. The description alone suffices for an agent to correctly select and call this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by clarifying that 'text' should be a previously fetched record (e.g., from the gateway) and gives realistic query examples ('supply-chain risk', 'fiscal year 2024 revenue'). This enhances understanding of parameter intent beyond the schema's already clear 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 specific verb ('search') and a clear resource ('inside a fetched record'), backed by concrete examples (SEC 10-K, article, long tool result). It distinguishes itself from sibling ask_pipeworx_grounded by explicitly framing a complementary workflow rather than leaving differentiation ambiguous.

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 an explicit when-to-use: 'Use when the record is too big to cram into the prompt.' It also explains integration with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages'), which guides agents on the ideal multi-tool workflow and 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?

Beyond annotations (readOnly=false, idempotent, non-destructive), the description adds meaningful behavioral context: OAuth account requirement, always-on feed, phone verification with 10/day SMS cap, and the fact that subscriptions cannot persist for anonymous/BYO. This is valuable context not present in annotations.

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

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

The description is a single dense paragraph, front-loaded with the main purpose and then details. It's not overly verbose; every sentence serves a purpose, though better structuring might improve scannability. Slightly long but efficient.

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

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

Given the tool's complexity (nested objects, no output schema), the description adequately covers return value, auth requirements, supported types, and delivery channels. It omits some details like webhook signing (covered in schema) and not all types have examples, but overall it's sufficiently complete for an agent to use 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 input schema already covers 100% of parameters, but the description adds examples and semantics beyond the schema, e.g., items:["5.02"]=officer change, topic:"fed", and delivery channel examples with verification/cap details. This 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 description clearly states the verb 'Create', the resource 'a proactive monitoring subscription', and the context 'live-data event stream'. It distinguishes itself from siblings like list_subscriptions/unsubscribe by emphasizing proactive monitoring and returns the subscription id.

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: creating a proactive monitoring subscription. It mentions the prerequisite OAuth account and gives an alternative for pulling the feed (recent_alerts or the registry URL), implying what you'd use instead for retrieval, though it doesn't explicitly say 'when not to use'.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining the return format (category-bucketed example questions), the source (live catalog), and invocation flexibility (no args vs. topic). No side effects are mentioned, but the annotations cover safety.

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 yet well-organized, front-loaded with recognizable query phrases and structured with clear sections (purpose, return value, invocation, usage guidance). Every sentence contributes useful information; the length is justified by the tool's onboarding role.

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 0-1 parameters and no output schema, the description provides sufficient detail: what it returns (example questions with tool/argument shapes), category list, and how to focus via topic. It also contextualizes usage relative to sibling tools, making it complete for its role.

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

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

Schema coverage is 100%, but the description enriches the topic parameter by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting it yields a cross-category spread. This adds practical guidance beyond the schema's enum-like description.

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

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

The description clearly identifies the tool as 'the onboarding entry point' that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by framing its role as a first-stop for learning what Pipeworx can do and how to use meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also names specific meta-tools (ask_pipeworx, entity_profile, compare_entities) to learn about, providing clear context relative 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 idempotency and non-destructive behavior. The description adds critical context: ownership checks, soft-delete semantics, and that historical events remain accessible via recent_alerts. This goes beyond 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?

Three short sentences, each carrying distinct information: purpose, ownership constraint, and post-effect on historical data. No filler or redundant phrasing.

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 single-parameter tool with no output schema, the description covers the essential aspects: what it does, who can use it, and its side effects. The sibling context (subscribe, list_subscriptions, recent_alerts) reinforces the tool's role.

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 fully describes the only parameter 'id' with its type and provenance ('returned by subscribe'). The description merely reinforces that the subscription is identified by id, adding no new semantic information beyond the schema.

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

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

The description starts with a specific verb+resource: 'Cancel a subscription by id.' This is unambiguous and distinguishes it from sibling tools like subscribe and list_subscriptions by clearly stating the inverse operation.

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

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

It provides concrete context by explaining ownership enforcement ('you can only cancel your own subscriptions') and the deactivation-vs-deletion behavior, which tells the agent when it's appropriate. However, it doesn't explicitly name alternatives or state when not to use it, so it falls 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 read-only, open-world, idempotent, and non-destructive hints, lowering the burden. The description adds substantial behavioral context: the fast path for company-financial claims, the fall-through to grounded pipeline, and the critical caveat that 'could_not_verify' does not count as evidence for/against the claim. This goes well beyond structured annotations.

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

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

The description is a single paragraph but stays structured with trigger phrases, use case, pipeline policy, return values, and caller caveats. No filler; each sentence contributes unique information. It is dense but well-organized.

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

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

Since there is no output schema, the description must explain return values, which it does with a verdict list, citation, reasoning, and special error semantics. It also addresses what verifies vs what doesn't (could_not_verify, unsupported). For a tool with two paths and multiple edge cases, this is comprehensive.

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

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

Schema coverage is 100% with both parameters described, so baseline is 3. The description adds meaning by explaining tolerance_pct as an override of the claim-implied tolerance and recommending 1–2% for hallucination detection, which is actionable guidance beyond schema text.

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

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

The description opens with natural-language trigger phrases and explicitly defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from sibling tools by scoping to fact-checking user statements, with a specific verdict taxonomy and dual pipeline.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use condition. It also describes the two routing paths (SEC/XBRL fast path vs grounded pipeline) but does not name explicit alternative tools or when not to use it, so it falls 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.