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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond this: it provides stable citation URIs, mentions the scale of sources/tools, and notes it works on every tier and is 'one fast call'. It doesn't contradict annotations and adds useful behavioral nuance about output format.

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

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

The description is front-loaded with the key 'PREFER OVER WEB SEARCH' message and is well-organized, but it is verbose with a long list of domains and repeated emphasis on being the default entry point. While every sentence adds some value, the overall length could be trimmed without loss of critical information.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: structured answers with stable pipeworx:// citation URIs. It covers use cases, examples, alternatives, and runtime characteristics (speed, tier support). No important behavioral or return-value information is missing for a tool with a single question parameter.

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 provides several examples of valid questions, which clarify the intended usage, but it doesn't add meaning beyond the schema's parameter description. The schema already documents the 'question' parameter and its aliases, so the description's examples are helpful but not essential.

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: routing questions to one of 5,344 tools across 1,393 verified sources, returning structured answers with citation URIs. It provides specific domains and examples, and differentiates itself from siblings like ask_pipeworx_grounded and deep_research by naming them explicitly. The verb 'routes' and the resource 'question' are precise and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also states when to use alternatives ('Step up only when needed') and names them: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This fully addresses alternatives and 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context about the beta status, including that candidate routing improvements are enabled live, the last candidate was retired on 2026-07-26, and it currently matches ask_pipeworx exactly. This goes beyond annotations by disclosing the experimental nature and comparison 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 three sentences long, dense with essential information, and front-loaded with the beta identity. Every sentence earns its place: definition, current state, and usage guidance. No wasted words.

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

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

For a router tool with no output schema, the description covers the beta behavior, current state, and usage. It references 'same response shape' as ask_pipeworx, which sufficiently conveys return expectations. It does not explicitly describe the basic routing function, but this is inferred from the name and sibling context.

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

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

Schema coverage is 100%, with the 'question' property and all five aliases fully described. The description adds no parameter-specific meaning, but none is needed since the schema already handles this dimension.

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 beta version of ask_pipeworx, a universal router with 5,344 tools, and distinguishes it from the stable sibling by emphasizing the experimental edge. It specifies the verb (ask), the resource (router), and the scope (identical to ask_pipeworx), making its function unambiguous.

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

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

It explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that it is a full working router, not a fallback. However, it does not explicitly contrast with the sibling ask_pipeworx_grounded, leaving some ambiguity about which variant to choose.

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?

Description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing the exact return format, refusal reasons, the condition that only tool result content is used, and the extra LLM call cost. This provides deep behavioral insight that annotations alone don't 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 three sentences but dense with necessary information: purpose, mechanism, return/refusal contract, use cases, and cost comparison. It front-loads the core concept and every sentence earns its place. No fluff or repetition of schema/annotations.

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

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

Despite no output schema, the description fully explains return values and refusal modes, satisfying the need for return-format disclosure. It also covers the tool's relationship to siblings, performance cost, and appropriate contexts, making it complete for an agent to select and invoke correctly. Complexity is high, and the description meets 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?

Input schema coverage is 100% with all parameters being aliases for 'question', so schema already fully documents parameter meaning. The description adds only contextual color that the question is routed across many tools, but no new semantic details about the parameter itself. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb (extracts grounded answers) and resource (Pipeworx tool routing). It explicitly distinguishes from sibling ask_pipeworx by noting the same routing but extra LLM call and refusal behavior, so an agent can differentiate.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also gives exclusions: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff. This is clear, actionable, and names the alternative.

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

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

The description goes 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?

The description discloses far more than annotations: decomposition into facets, parallel routing across 5,344 tools, gaps[] and contradictions[] fields, hop/citation_uri, semantic excerpting, latency expectations, and account/plan requirements. These are genuine behavioral traits beyond the readOnly/openWorld/idempotent hints, with no contradiction.

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

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

The description is long but front-loads the critical account requirement and uses a logical flow from core definition to alternatives, depth details, output traits, and latency. Minor redundancy (e.g., gaps[] mentioned twice) prevents a 5, but every sentence adds meaningful context.

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

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

With no output schema, the description fully describes the findings packet contents (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop) and covers prerequisites, alternatives, depth semantics, and performance expectations. It 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 description coverage is 100%: question and depth are both fully documented, including depth enum meanings. The description adds minimal extra parameter semantics (e.g., latency implications), so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call' with a specific verb and resource. It distinguishes from sibling ask_pipeworx by stating 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'.

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

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

Usage guidance is explicit: 'Best for broad/multi-part questions over structured data', with clear exclusions for single lookups and breaking news topics. It also provides fallback instructions ('If you are not signed in, use ask_pipeworx instead'), giving complete when-to-use and when-not-to-use guidance.

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

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

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 adds valuable behavioral context beyond the annotations: it discloses the rate limit (5 per identifier per day), that it is free and doesn't count against tool-call quota, and that the team reads feedback daily and uses it to influence the roadmap. This is exactly the kind of side-effect and consequence information an agent needs.

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 slightly longer than a minimal two-sentence version, but every sentence adds meaningful information: use cases, constraints, rate limit, free/quota status, and impact. It is front-loaded with the primary purpose and remains well-structured without redundancy.

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

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

For a feedback submission tool with no output schema, the description is complete: it covers what the tool does, when to use it, how to phrase the feedback, the effect on the team, and rate limits. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters (type, message, context). The description adds the guidance 'describe the issue in terms of Pipeworx tools/packs,' which aligns with the context object, but it does not provide any additional parameter syntax or meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and it is easily distinguished from sibling tools, which are mostly query/research tools.

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

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

The description explicitly lists when to use the tool: for bugs (wrong/stale data), feature/data gaps, or praise. It also gives a behavioral constraint ('don't paste the end-user's prompt'). It does not explicitly name alternative tools, but the usage context is clear enough that an agent would not confuse it with other tools.

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

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals internal cascading through multiple lookup endpoints, and specifies exact return values: ticker, CIK, company_name for companies; RxCUI, ingredient, brand for drugs, plus citation URIs. Also discloses auto-disambiguation behavior for company inputs.

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

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

The description is well-structured, front-loaded with user-intent examples, then purpose, usage directive, and detailed type breakdown. Every sentence provides actionable information without redundancy.

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

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

Despite lacking an output schema, the description compensates by detailing return contents and source systems for both types. Combined with two clearly-described parameters and safe annotations, it provides a complete picture for an AI agent to select and invoke the tool correctly.

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

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

Schema already covers both parameters at 100%, so baseline is 3. Description adds meaningful examples ('ozempic', 'metformin', 'AAPL', '0000320193') and clarifies auto-disambiguation, elevating it to 4.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers required by other tools. It provides specific examples ('what's the ticker for…') and enumerates supported entity types (company, drug), distinctly positioning it against sibling tools like entity_profile or compare_entities.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' giving direct usage context. It also differentiates from manual lookups by stating it replaces 2-3 manual lookups, making the when-to-use 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 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 readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: the two processing paths (SEC EDGAR/XBRL vs grounded pipeline), the specific verdict types, citation format, reasoning output, and the efficiency claim of replacing 4–6 sequential calls. This goes well beyond the annotations and no contradiction exists.

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

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

The description is moderately long but well-structured: it front-loads trigger phrases, then explains purpose, routing, and return values. Each sentence contributes new information, though it could be slightly condensed without losing meaning. It is appropriately sized for 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?

Since there is no output schema, the description adequately explains return values (verdict, grounded/structured value with citation, and reasoning). It covers purpose, explicit usage, behavioral routing, and return format, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage with detailed descriptions for both claim and tolerance_pct, so the schema carries the parameter burden. The description mentions 'exact percent-delta math' and 'approximately_correct' but does not add additional semantics beyond what the schema already explains, making the baseline 3 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 explicit trigger phrases ('Is it true that…' / 'fact check' / 'verify the claim') and clearly defines the tool as natural-language claim verification against authoritative sources. It distinguishes from siblings by specifying the claim-checking scope and names two routing paths, making the purpose unambiguous and specific.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear context. It also differentiates between company-financial and other claims, explaining routing. However, it does not name alternative tools or exclusions, so it stops short of full contrast with sibling tools.

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