translate

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

Annotations already declare read-only and non-destructive behavior. The description adds valuable context about external calls (Workers AI free default, Anthropic BYO key with direct billing), and the per-model return structure. It does not describe rate limits or failure modes, but these are less critical given the strong annotation coverage.

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

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

The description is two sentences, front-loaded with purpose and output, then efficiently covers model options, billing, return format, and use cases. No wasted words; every clause 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?

The tool has 4 parameters, no output schema, and moderate complexity. The description covers the return structure (per-model fields + combined view), the default model, the optional key, and the use cases. It doesn't explain 'signals' in detail or address rate limits, but for a read-only probe with good annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, providing a baseline of 3. The description goes beyond the schema by explaining the default model, the conditionality of `_apiKey` (only needed if 'anthropic' is in models), and the output format per model. This added meaning justifies a 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 verb ('Probe one or more LLMs'), the resource (what they know about an entity), and the output (visibility score 0-100). It is specific and distinguishes itself from obvious read-only tools, but does not explicitly differentiate from sibling 'scan_competitor_ai_presence' which may overlap in use case.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not, however, state when not to use it or mention alternatives, so it falls just 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description adds concrete behavioral details: it routes questions to a large number of tools, fills arguments automatically, and returns answers with stable citation URIs. It does not mention potential constraints like rate limits or failure modes, but the added context is useful and does not contradict 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 overly verbose and repetitive, with long lists of example sources and redundant phrases like 'PREFER OVER WEB SEARCH' and 'START HERE' repeated across multiple sentences. It could be condensed significantly without losing meaning, making it harder 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?

The description covers the tool's scope (multiple data sources), its default status, and clear differentiation from alternatives. It also explains the output (structured answers with citations). While it does not describe an output schema (none exists), it provides sufficient context for an agent to choose and use the tool correctly, though it could be more efficient.

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 six parameters as aliases for the question, and the description reinforces this by stating 'Accepts query, q, prompt, text, input as aliases' and clarifying the input is a natural-language request. The examples further illustrate the expected format, adding value beyond the minimal schema descriptions.

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

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

The description clearly states the tool's function: it answers questions about current/historical data by routing to thousands of verified sources and returns structured answers with citations. It also distinguishes itself from sibling tools by explicitly naming it as the preferred default over web search and mentioning alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, including 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up instructions for ask_pipeworx_grounded (for hallucination-resistant answers) and deep_research (for broad multi-part questions). This makes the decision clear for an agent.

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

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

The description adds meaningful behavioral context beyond the annotations: it is a live experimental variant, currently matches ask_pipeworx exactly, and 'falls back to nothing' — it is a full working router. It also discloses that routing improvements are enabled only when under test, which annotations could not convey.

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

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

The description is a compact three-sentence paragraph where each sentence earns its place: what the beta is, current candidate status, and usage guidance. The final fallback sentence is slightly redundant but reinforces that this is not a degraded variant.

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 beta router with no output schema, the description gives enough context: identical to ask_pipeworx, same tools and response shape, current state, and comparison purpose. It does not describe the actual response shape, but deferring to 'same response shape' is sufficient given the sibling ask_pipeworx exists.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question.' The description only says 'same arguments' and does not add new parameter-level meaning, 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 identifies this as 'Beta version of ask_pipeworx: identical universal router' with 5,564 tools, distinct from the stable ask_pipeworx and ask_pipeworx_grounded. It states the exact scope and experimental nature, so an agent can immediately understand what the tool does and how it differs from siblings.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It does not explicitly say 'do not use when you need stability,' but the contrast with the stable router and the note that no candidate is active provide clear decision 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 readOnly/openWorld/idempotent annotations, the description reveals critical behaviors: answers are extracted only from tool results, refusals happen with specific reasons (not_in_source, no_tool_match, etc.), and success returns evidence as a verbatim quote. It also discloses the extra LLM call cost, which is valuable operational context. No contradiction with annotations.

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

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

The description is dense but purposeful, covering functionality, output shape, refusal reasons, use cases, and cost comparison in one paragraph. It is longer than strictly necessary, slightly reducing conciseness, but every section contributes meaningful decisions for the agent.

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

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

There is no output schema, but the description fully specifies the success return object, refusal object, refusal reason enum, and behavioral constraints. It also explains the cost trade-off versus the sibling tool, making the description sufficient for the agent to select and call 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 description coverage is 100%; all six parameters are documented alias forms of the same 'question' field. The description adds no additional parameter-level meaning beyond the schema, 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 explicitly states this is a hallucination-resistant answer mode for high-stakes reads, indicating a specific verb ('extracts the answer') and resource (Pipeworx tool routing across 5,564 tools). It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and evidence-based refusals.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a when-not-to-use and alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, naming the sibling alternative directly.

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

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

The description goes far beyond the annotations by detailing internal behaviors: the resolver contract (match_confidence, match_score, alternatives), fan-out to specific data packs, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread tradeability warnings, and cancellation-rule parsing. It also discloses that closed markets may surface via low_confidence_match and that both routes are blocking. This is exceptionally transparent for a read-only tool.

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

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

The description is long but well-organized with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence provides useful detail, and it is front-loaded with a concise opening. The length is justified by the complexity of the tool, though a slightly tighter structure would be even better.

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

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

With no output schema, the description fully explains the return structure: result.market, result.analysis, result.evidence, result.parent_event, news fields with fallback info. It also covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation-rule risks. For a complex data-fan-out tool, this is a comprehensive and complete description.

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

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

The schema already covers 100% of parameters with descriptions, giving a baseline of 3. The description adds extra semantic value by explaining how the 'market' parameter is resolved (slug, URL, or question text) and the consequences of depth (fan-out extent) and include_raw (response size under ~20KB vs 50-500KB). This enhances parameter understanding 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 opening sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and mechanism (fan-out to data packs). The description also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges or deep_research.

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

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

The description provides explicit usage guidance with 'Use for...' examples, telling agents when to invoke this tool for bet-related research. It also explains the one-call fan-out behavior, which differentiates it from more manual alternatives. However, it does not explicitly mention when not to use this tool or name alternative tools for different scenarios, 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?

Adds substantial behavioral detail beyond the readOnlyHint annotation: pulls latest 10-K data, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This enriches the agent's understanding of execution behavior without contradicting annotations.

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

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

The description is dense but every sentence contributes: trigger phrases, comparison scope, preference rule, data details, sorting, and output. It is front-loaded with the core purpose and efficiently packs secondary details 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?

Even without an output schema, the description covers the return format (paired data + pipeworx:// URIs) and data source specifics. For a 2-parameter tool with rich annotations, this is sufficient for confident invocation.

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

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

The description significantly enhances the parameters: it explains the 'type' enum values with concrete data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and provides examples for the 'values' parameter format. With 100% schema coverage, this extension is valuable.

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 side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with explicit trigger phrases ('X vs Y', 'rank these companies'). It distinguishes itself from sibling tools by emphasizing 'ALWAYS PREFER over sequential single-pack lookups when comparing 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?

Provides explicit when-to-use guidance via trigger phrases and a strong directive to prefer this over sequential lookups. It also details what each type ('company' vs 'drug') retrieves, giving clear context for selection.

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

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

Despite solid annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavioral context: it returns a findings packet with verbatim evidence, gaps[] for unanswered facets, never invents answers, provides contradictions[] for standard/thorough, semantic excerpting, and latency expectations. It also clarifies citation resolvability and hop fields, which are not inferable from 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?

This is a long description, but it is tightly packed with diverse, high-value information: account requirements, tool differentiation, return format, citation behavior, latency, and depth semantics. It is front-loaded with the most critical constraint (account requirement). While a few redundancies exist (e.g., repeated comparisons to ask_pipeworx), every sentence contributes to successful tool usage. Could be slightly trimmed but remains efficient for its 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?

For a research tool with no output schema, the description is exceptionally complete. It covers prerequisites (sign-in, paid tier for thorough), alternative tools and when to use them, expected latency, detailed return packet contents, citation resolvability guarantees, gap handling, and the behavior of each depth mode. It leaves no significant usage question unanswered.

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

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

The schema already provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description goes beyond this by adding critical parameter-specific semantics: depth:"thorough" requires a paid plan, standard adds gap recovery and contradictions scan, thorough performs iterative follow-up hops. This enriches the bare enum descriptions with actionable meaning.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It uses a specific verb+resource (research across structured data sources) and explicitly distinguishes itself from ask_pipeworx by noting 'this is NOT open-web search' and targeting 'broad/multi-part questions over structured 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?

Usage guidance is exemplary: it explicitly tells users when NOT to use the tool ('If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'). It also explains the account tier requirements and when to choose each depth option, providing clear decision rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds the return format (array with confidence scores), which is useful behavioral detail beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with the core action, no unnecessary words. Excellent conciseness.

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

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

For a simple one-parameter tool with an output schema and strong annotations, the description provides the essential behavior and return information. Nothing more 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 coverage is 100% with the 'text' parameter described as 'The text whose language should be detected'. The description only repeats this, adding no additional semantic detail, so the baseline 3 applies.

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

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

The description uses a specific verb ('Detect') and resource ('language of a text string'), clearly distinguishing it from siblings like translate and list_languages. The scope is unambiguous and matches the tool name.

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 context of use is clear: when you have a text and need to identify its language. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by disclosing the return format (top-N tools with names, descriptions, full input schemas, curated examples) and that results are directly callable without a second lookup. This goes 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?

Purpose is front-loaded in the first sentence. The domain list is lengthy but directly supports usage guidance, and the output format is explained in a single, information-dense sentence. Slightly verbose but effectively structured, and every part 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?

The description covers purpose, usage conditions, return format, and actionable guidance. It also explains what results look like in the absence of an output schema. Combined with a thorough input schema and safety annotations, it is sufficiently complete for a discovery tool. Missing only edge-case details like ranking methodology, which are not essential.

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

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

Schema description coverage is 100%, with all parameters and aliases thoroughly documented. The description does not add significant meaning beyond the schema's parameter descriptions; it only reiterates that query is a natural language description. Baseline 3 is appropriate because the schema carries the parameter burden.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists supported domains and explicitly positions itself as a tool-discovery meta-tool, distinguishing it from sibling tools that perform specific tasks. The instruction to 'Call this FIRST' further reinforces its unique role.

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

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

Provides clear when-to-use guidance: browse, search, look up, or discover tools, and 'Call this FIRST when you have many tools available'. It also hints at a when-not-to-use condition ('not just one answer'), but does not explicitly name alternative tools or exclusions, preventing a top score.

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

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

Even with annotations indicating read-only and idempotent behavior, the description adds important context: it fans out across multiple sources, returns up to 5 filings, soft-fails on the USPTO PatentsView API after sunset, and uses a GDELT→GNews fallback. No contradiction with annotations; it enriches behavioral understanding.

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

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

The description is a single dense paragraph but is well front-loaded with examples and the key 'ALWAYS PREFER' instruction. Every sentence conveys necessary information, though a more structured format (e.g., bulleted returns) would improve scannability without losing 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?

Since there is no output schema, the description fully covers return values (CIK, filings, fundamentals, patents, news, LEI), including source details and fallbacks. It also handles edge cases like unsupported names and API sunset, making it complete for a complex tool with two required parameters.

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

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

Schema coverage is 100%, and the schema already fully describes 'type' and 'value', including the ticker/CIK format and name-not-supported note. The description reiterates this but adds no new parameter semantics beyond what the schema 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 states the tool creates a 'full cross-source profile of a US public company' with explicit verbs like 'tell me about' and 'research', and lists concrete outputs. It clearly distinguishes itself from siblings by naming resolve_entity for names and positioning itself over chained single-pack lookups.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity first for names. Also excludes non-US companies and names, making when-to-use vs alternatives very 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?

The annotations already declare destructiveHint=true, and readOnlyHint=false, so the agent knows it's destructive. The description adds context by stating the deletion purpose and the kind of data (memories, sensitive data), which goes beyond the annotations. It doesn't mention irreversibility or missing-key behavior, but the idempotentHint covers 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 two sentences, front-loaded with the action, and includes usage guidance without unnecessary verbosity. 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 delete-by-key operation, the description is complete: it states the action, key usage, when to use, and companion tools. Annotations cover safety. The lack of output schema is acceptable for a deletion tool. Minor missing detail is the behavior on missing keys, but idempotentHint implies tolerability.

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

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

Schema description coverage is 100% for the single parameter 'key' ('Memory key to delete'), so the schema already provides full meaning. The description only says 'by key', adding no additional detail 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 'Delete a previously stored memory by key', which is a specific verb (delete) and resource (memory). This distinguishes it from sibling tools remember and recall, making its purpose unambiguous.

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

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

It explicitly provides usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier. Pair with remember and recall.' This tells the agent when to use the tool and mentions companion tools, satisfying the 'when vs alternatives' requirement.

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 valuable behavioral context by revealing that the tool 'fetches the page' (external network request) and emits a 'single text blob' as output. 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 concise and front-loaded, with two clear sentences followed by a bulleted 'Useful for' list. Every sentence adds value, and the structure makes the tool's purpose and use cases immediately scannable.

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

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

For a tool with only two parameters, no output schema, and comprehensive annotations, the description covers the core functionality, workflow, output format, and use cases. It could add notes about network dependency or error handling, but the current content is sufficient for effective tool selection and invocation.

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

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

The input schema already fully describes both parameters with 100% coverage. The description adds no additional parameter-specific meaning beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states a specific action ('Generate a production-ready llms.txt file for any URL'), the exact output ('standard llms.txt markdown format'), and the process ('Fetches the page, extracts title/description/key links'). It uniquely identifies the tool among siblings by focusing on llms.txt generation, and the use cases distinguish it from related tools like scan_competitor_ai_presence.

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 three concrete use cases: '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.' This provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it returns language codes and names, but this is likely redundant given the output schema exists. No contradiction with annotations; however, no additional behavioral context is disclosed.

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

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

The description is two concise sentences: first states the action and scope, second states the return content. Every word earns its place, with no redundancy or unnecessary 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?

For a simple listing tool with zero parameters, an output schema, and robust annotations, the description is complete. It accurately communicates the tool's purpose and output, and no further 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?

The tool has zero parameters, so there is nothing to document. The description correctly omits parameter details, and the baseline score for a no-parameter tool is 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 uses the specific verb 'List' and identifies the resource as 'all languages supported by the translation API'. It clearly distinguishes from sibling tools like 'translate' or 'detect_language' by specifying the tool's unique output of language codes and names.

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 usage when one needs the full set of supported languages before using translation or detection tools, but it does not explicitly state when to use or not use this tool versus alternatives. No exclusions or alternative tool mentions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral insight by specifying that it lists only the caller's subscriptions and by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count), which is useful context 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 three concise sentences with no wasted words. It front-loads the core purpose and then efficiently adds return-value details and usage guidance.

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

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

For a simple read-only list tool with one optional parameter, the description covers the purpose, the returned fields, and the intended use case. The output schema is absent, but the description explicitly lists the output fields, making the tool sufficiently complete without needing to over-explain.

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 the include_inactive parameter already documented as 'Include cancelled subscriptions in the response (default false).' The description does not add additional meaning to the parameter beyond what the schema provides, 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 uses the specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions,' which unambiguously distinguishes it from sibling tools like subscribe and unsubscribe. It also lists the returned fields, making the tool's scope explicit.

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

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

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

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

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

Annotations are all false, so the description adds critical context: rate-limited to 5 per identifier per day, free (doesn't count against quota), and the claim_token workflow. While it doesn't detail data retention or internal handling beyond "team reads digests daily," it covers the key operational behaviors.

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 adds necessary information for correct usage. It is slightly long, but the complexity of the tool (claim_token, rate limits, scope) justifies this length. The structure flows logically from purpose to exclusions to mechanics.

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 explains the claim_token return behavior and how to check resolution status. It covers required context: what counts as relevant feedback, how to scope it, rate limits, and the follow-up mechanism. No significant gaps remain.

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

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

The schema already provides 100% coverage of parameters, so baseline is 3. The description adds value by explaining the claim_token lifecycle (filing without an account returns a token, pass it back later to read status) and by clarifying the message should be specific but not include end-user prompts. This supplement goes beyond the schema.

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

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

The description clearly states the tool's purpose: "Tell the Pipeworx team something is broken, missing, or needs to exist." It lists specific feedback types (bug, feature/data_gap, praise) and emphasizes it applies only to tools from this Pipeworx connection, distinguishing it from sibling tools like ask_pipeworx or bet_research.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and when-not-to-use (if tool is from a different MCP server). It even gives a heuristic: "Not sure? Pipeworx tool names are the ones this connection lists" and clear instructions on what to include/exclude (don't paste end-user's prompt).

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

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

Annotations already declare read-only, idempotent, and open-world hints, but the description goes further by disclosing that the signal is self-aggregated from a specific analytics engine, that no PII is included (only pack, tool, count), and that caching varies from 5 minutes to 1 hour depending on the selected window. This adds meaningful behavioral context beyond the structured annotations.

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

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

The description is compact yet information-dense. It front-loads the core purpose, then uses a numbered list for use cases, and finishes with the aggregation source, privacy note, and caching detail. Every sentence serves a purpose without bloat, making it easy for an agent to parse and act on 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is comprehensive. It explains what results are returned, why the metric is useful, how it is derived, what data is excluded (PII), and that results are cached. This fully equips an agent to decide when and how to invoke the tool without additional lookups.

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

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

The input schema already documents the single optional 'window' parameter with enum values and a clear description, so schema coverage is 100%. The tool description adds extra semantics by linking cache duration to the window choice ('Cached 5min-1h depending on window'), which is not present in the schema and helps agents reason about freshness expectations.

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, engaging question ('What other AI agents are calling on Pipeworx right now') and immediately specifies the exact returns: top tools, top packs, and total call volume over a 24h/7d/30d window. This makes the tool's purpose unmistakable and clearly distinguishes it from sibling discovery tools like discover_tools, which focus on catalog discovery rather than popularity signals.

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

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

The description provides explicit use cases via a 'Useful for' list: discovering hot data sources for current events, confirming a canonical tool before asking a question, and checking alignment with common agent needs. It clearly states when to use the tool but does not mention when not to use it or name alternatives, so it falls short of the top mark.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds extensive behavioral context: the SEMANTIC ANCHOR with Jaccard threshold, PARTITION FILTER with placeholder fraction, response structure, and the FILL CHECK that compares theoretical vs realizable edge at the CLOB depth. It clearly discloses a limitation and warns against trading when realizable edge is ≤ 0. No contradiction with annotations.

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

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

The description is long but every section earns its place. It is well-structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose and mode selection. No fluff or redundancy; it packs a large amount of critical detail into a scannable format.

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

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

For a tool of this complexity (three modes, custom filters, output shape, fill-check caveat), the description covers everything needed for correct invocation and interpretation. It describes the return fields, explains the internal checks, and includes safety guidance. Given no output schema, the description carries the full burden and succeeds.

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

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

Schema coverage is 100% with descriptions for both `event` and `topic`, but the tool description significantly enriches semantics. It provides example slugs ('fed-decision-may-2026'), explains the single-event vs cross-event distinction, and clarifies that `event` is recommended for a specific market while `topic` catches cross-event patterns. This goes well beyond the baseline schema descriptions.

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

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

The description opens with a specific and clear statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This identifies the exact action (find arbitrage), resource (Polymarket), and methodology, making the tool's purpose unambiguous. It also differentiates from siblings like polymarket_fill_risk by pointing to it for custom sizing.

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, actionable usage instructions: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`.' It gives concrete examples of event slugs and topic queries, explains when to use each mode, and even tells the agent 'do not trade it' when the fill check yields realizable_edge_pp ≤ 0. It also names an alternative tool for custom sizing, satisfying the when/when-not/alternatives criterion.

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, and the description does not contradict them. It adds extensive behavioral detail: edge is computed net of slippage, Kelly is capped at 0.25, there's a 24h-move warning, placeholder-slug filters, diagnostics counters, and 1h KV-level caching. This goes far 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 long but every sentence earns its place. It is front-loaded with the core purpose, then organized into segments, knobs, response structure, diagnostics, and caching. Each section is clearly labelled and dense with actionable details, making it appropriately concise 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?

With no output schema, the description compensates thoroughly: it explains top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), what diagnostics show (funnel counters, filter_skips), and why segments can be empty. It also covers caching and the Fed signal caveat, leaving no major gaps for an agent.

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

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

Though the schema covers 100% of parameters, the description adds substantial meaning: it groups knobs into 'tradeable-edge' filters, explains min_partition_leg_kelly's unusual per-leg behavior, and details why slippage_pp matters (no trading fees but 20-50bp book walking). This enriches the schema baseline.

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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions the tool for 'what should I bet on today' and distinguishes it from manual market browsing ('without paging hundreds of markets').

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

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

The description provides clear usage context, including the intended discovery use case and guidance on when to adjust knobs (e.g., min_liquidity, max_spread_pp as 'tradeable-edge filters'). It also warns about the Fed signal being unreliable and notes the rare-by-design nature of concentrated longshots. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or edge_tracker, so alternatives are only implicit.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: snapshot TTL (60 days), cache-miss-driven gaps, daily-close calculation for decay, sign convention for edge_pp_net, and response structure. No contradiction with annotations.

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

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

The description is front-loaded with the core question, then organizes args, response fields, and limits. It is dense and well-structured, though the rhetorical example ('wide for a reason nobody is willing to take') and some extra prose add length without carrying essential 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?

With no output schema, the description fully explains return values (tracked[], expired[], snapshot_dates[]), their semantics, and important caveats like TTL limits and data gaps. This is complete for a 2-parameter read-only tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description restates defaults ('default 14, max 30', 'default 1wk') and adds the phrase 'snapshot family' but does not meaningfully extend what the schema already provides. Baseline 3 applies.

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

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

The description clearly identifies the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and states the exact question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling polymarket_edges (the snapshot source) and other market tools.

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

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

Usage context is clear: use it to assess edge longevity and decay, with a concrete example comparing a fresh wide edge to a 3-week-old one. However, it does not explicitly name alternatives or state when not to use this tool, so it misses the 'explicit when-not/alternatives' 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?

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already provided, the description adds substantial behavioral context beyond annotations. It explains how the tool 'walks the ladder', interprets size_usd differently per mode, returns specific fields like 'vwap_fill_price' and 'verdict', and warns about 'forced_directional_risk' and 'partial basket fills'. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and then uses clear section labels ('SINGLE-MARKET', 'BASKET') for structured reading. It is quite long, but nearly every sentence adds critical detail. The only minor issue is that some explanatory content (e.g., 'the dominant loss mode in real arb-bot P&L') could be trimmed without losing essential usage 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?

Given the tool's complexity (two modes, multiple parameters, and no output schema), the description is remarkably complete. It enumerates key return fields for both modes, including 'top_of_book', 'slippage_pp', 'thin_legs[]', and 'max_clean_notional_usd'. It also covers risk scenarios such as partial fills and unhedged positions, making the agent fully informed.

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?

Even though schema coverage is 100%, the description significantly enriches parameter meanings. For instance, it clarifies that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains side defaults and clamping behavior (10–1,000,000), 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 defines the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' which immediately communicates its function. It further distinguishes itself from sibling tools by explicitly stating to use it 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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, directly naming the sibling tools and the threshold condition. It also delineates two modes ('single-market mode' vs 'basket/partition mode') and explains when each is applicable, including the default auto behavior for basket side. This is exemplary usage guidance.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by explaining detailed behavioral nuances: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and conditions where spreads are meaningless. It also discloses that many pre-mapped topics currently return warnings, which is critical behavioral context not available in annotations.

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

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

The description is long but every sentence carries meaningful information—purpose, modes, response fields, safety warnings, and limitations. It uses clear structural markers like 'TWO MODES' and 'SAFETY FIELDS' to aid scanning. While not as lean as a two-sentence description, the density 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?

With no output schema, the description must explain return values, and it does comprehensively: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skip counters. It also covers edge cases and semantics thoroughly, making the tool well-specified for an agent despite its 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 substantial value by explaining how the three parameters interact: topic selects a pre-mapped pair, while kalshi_event_ticker and polymarket_event_slug override each side independently. It also clarifies the exact list of valid topic shortcuts, which is not in the schema's enum (no enums defined). This elevates the score above baseline.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which precisely identifies the tool's function and its unique cross-venue scope relative to sibling tools like polymarket_arbitrage. It further details two operational modes, 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 explicitly explains the two modes ('topic' shortcuts vs explicit tickers) and when each is appropriate. It also warns that 'Real cross-venue spreads are rarer than the macro-shortcut list suggests' and that 'pre-mapped ≠ tradeable,' providing strong usage cautions. However, it does not explicitly name alternative tools for when cross-venue spreads are not suitable, so it stops 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, and the description aligns with these. The description adds valuable context beyond annotations by disclosing scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the dual behavior (retrieve vs. list all) which is not obvious from annotations. Minor missing details like error behavior for unknown keys prevent a perfect score, but the addition of scoping is a strong transparency plus.

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: action and alternation, usage scenario, and scoping/relationship to siblings. It is front-loaded with the primary verb and resource, contains no redundant or filler content, and every sentence adds critical decision-making information. This is exemplary conciseness.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers the action, when to use it, scoping, and how it relates to remember/forget. The absence of return-value details is acceptable given the tool's trivial return types (a value or a list of keys) and the lack of an output schema. An agent has sufficient information to invoke the tool correctly in all expected scenarios.

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

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

The schema already covers the sole parameter (`key`) with 100% description coverage, so the baseline is 3. The description adds semantic richness by providing concrete examples of key values ('user's target ticker, an address, prior research notes') and restating the omit-to-list behavior. This helps the agent understand what keys are meaningful and reinforces the optional nature of the parameter, going slightly beyond the schema's terse description.

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

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

The description clearly states the tool's core function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and identifies the resource (saved memory), and explicitly differentiates from sibling tools by naming remember and forget. The examples of stored context (target ticker, address, research notes) further clarify its 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?

The description provides explicit usage guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains when to use the alternative tools via 'Pair with remember to save, forget to delete,' clearly distinguishing the tool's role in the save/recall/delete lifecycle. This gives the agent actionable criteria for selecting this tool over siblings.

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

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

While annotations already indicate readOnlyHint=true, the description goes further by disclosing the optional mutation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also reveals that events carry source, citation_uri, and raw payload, and explains the persisted feed nature. This adds critical behavioral context beyond the annotations without 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 five sentences, each earning its place: purpose, return payload, filtering, mark_read side effect, and alternative access method. It is front-loaded with the core action in the first sentence and contains no fluff or repetition. Ideal length 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?

Despite no output schema, the description clearly explains what each returned event carries (source, citation_uri, raw payload). It also covers the main use cases (filtering, polling with mark_read) and gives an external endpoint fallback. With 5 optional parameters and no required ones, the description provides enough context for an agent to invoke it correctly and understand results.

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

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

The schema covers all 5 parameters with descriptions, so the baseline is 3. The description adds value by providing an example type ('sec_8k'), clarifying the since parameter as ISO timestamp, and explaining the state-changing effect of mark_read. It doesn't rehash limit or unread_only, but the schema already covers those; the added examples and side-effect explanation elevate it above baseline.

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: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from siblings like list_subscriptions or recent_changes by focusing on fired events from the persisted feed, and even mentions the evaluator's role. This makes the tool's 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?

It explicitly provides an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This tells agents when to use the tool (interactive polls) versus when to use the HTTP endpoint. It also gives filtering guidance with examples ('sec_8k') and explains the mark_read behavior for sequential polling.

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, destructiveHint=false. The description adds substantial behavioral detail beyond those: fans out to SEC EDGAR, GDELT→GNews fallback (GNews when rate-limited or 5xx), USPTO patents granted, PatentsView API sunset May 2025 causing soft-fail, and the return format (changes[] grouped by source + total_changes count + pipeworx:// citation URIs). 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 front-loaded with user-intent examples, making it immediately clear what problem the tool solves. Every sentence earns its place: data sources, fallback behavior, date formats, return structure, and an alternative tool reference. Dense but efficiently structured without 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?

Despite having no output schema, the description fully discloses the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// URIs). It also explains the multi-source fan-out, failure modes (GDELT→GNews fallback, USPTO soft-fail), and a relevant constraint (PatentsView sunset). This is more than adequate for an agent to invoke 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%, but the description adds meaning beyond the schema: it explains `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), and `value` accepts ticker or zero-padded CIK. This clarifies format and usage that the schema only hints at.

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

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

The description opens with concrete example queries ('What's new with X', 'latest on Y') then clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the resource (company change feed) and distinguishes from sibling entity_profile by stating when to use that instead.

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 triggers ('What's new with X' style questions) and an explicit exclusion: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' Also notes the fallback chain (GDELT→GNews) and timeout behavior, which helps the agent choose appropriately.

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 explains the key-value storage model, scoping by user identifier, and the persistence difference between authenticated users (permanent) and anonymous sessions (24 hours). It also mentions the pairing with recall/forget, which clarifies the full lifecycle. 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 four sentences long, front-loads the core purpose, and then layers usage examples, storage details, and sibling references. Every sentence provides distinct information with no redundancy or filler.

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

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

For a simple write tool with no output schema, the description covers everything needed: purpose, when to use, storage semantics, persistence behavior, and relationships with recall/forget. The tool's complexity is low, and the description is fully sufficient for an agent to invoke it correctly.

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

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

The schema already covers both parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds extra value with a concrete example for the key format and clarifies that value accepts 'any text,' which helps agents formulate correct inputs. This goes slightly beyond the schema without over-explaining.

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

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

The description uses the specific verb 'save' with a clear resource ('data the agent will need to reuse later') and explicitly contrasts with sibling tools by naming 'recall' and 'forget'. This makes the tool's purpose unmistakable and differentiates it from other memory operations.

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

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

It provides explicit 'when to use' guidance with concrete examples (resolved ticker, target address, user preference, research subject). It also names the companion tools (recall, forget) as alternatives, though it does not explicitly state when *not* to use it. The context is strong enough to guide agent selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: it cascades through multiple lookups internally, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns explicitly labeled identifiers with sources, and includes an `unresolved` field for failures. No contradiction with annotations.

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

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

The description is front-loaded with example queries and the primary directive 'Use FIRST,' then organizes information by supported type. It is lengthy but each sentence adds value—examples, identifier details, graceful degradation, and source labeling. Minor inefficiency in the first paragraph's list of examples could be tightened.

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

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

Given the tool's complexity (multiple identifier sources, ownership data, graceful degradation) and the absence of an output schema, the description is remarkably complete. It covers input formats, output structure (identifiers, unresolved field, source labels), internal cascading behavior, and fallback logic. No gaps are apparent.

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

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

Schema coverage is 100% with two parameters, and the description adds significant meaning: for type='company', it accepts ticker, CIK, ISIN, or name; for type='drug', brand or generic; and details the returned identifiers (CIK, ticker, LEI with ownership, FIGI, RxCUI). This goes well beyond the schema's basic 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 clearly states the tool resolves names to canonical/official identifiers with specific examples like tickers, CIKs, LEIs, and RxCUI. The verb 'resolve' paired with 'name to identifier' is specific and distinct from sibling tools (e.g., entity_profile takes an ID, not a name). The scope is well-defined through 'SUPPORTED TYPES'.

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

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

The description explicitly directs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. However, it does not explicitly mention when not to use this tool or compare it to alternatives like compare_entities or search_within. The statement that it replaces 2-3 manual lookups implies efficiency but not exclusion criteria.

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

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

Discloses that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density—useful behavior beyond the readOnly/idempotent annotations. It does not address potential edge cases 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?

Three sentences, front-loaded with purpose and mechanism, with no wasted words. Every sentence adds value.

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

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

Covers purpose, mechanism, use case, and return format, and schema/annotations fill in parameter and safety details. Missing explicit exclusions or failure handling, but adequate for 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 schema already documents all four parameters. The description adds only contextual meaning ('your brand + N competitors') but no new syntax or 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing itself from ai_visibility_check by referencing it as the underlying probe and adding ranking/surfacing behavior. The verb 'Compare' and resource 'AI visibility' are 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?

Provides a clear use case: competitive AI-marketing audits, with an illustrative question. It implies using this tool when comparing multiple entities vs. single checks, but does not explicitly mention alternatives or 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?

Discloses substantial behavior beyond the readOnly/openWorld/idempotent annotations: it fans out to two external services, includes both license/advisory and bundle-size data, returns a specific summary block and per-advisory details, degrades gracefully on partial failure, and calls out the 5-30s first-measurement timeout. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: composite purpose, use cases, return contents, ecosystem scope, and timeout/failure behavior. It is front-loaded and structured appropriately for a complex multi-source tool.

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

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

With no output schema, the description fully carries the burden of explaining the return value, and it does so with a field list, per-advisory detail, links, and alternative versions. It also covers failure modes, ecosystem limits, and timing behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond the schema; it mentions package names and versions only in the context of outputs and limitations, not additional syntax or format details.

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 ('Composite check whether to add this npm package') and clearly distinguishes itself from siblings by naming the underlying sources (deps.dev and bundlephobia) and the question it answers. It is far more specific than the generic title.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives an exclusion/alternative: NPM-only in v1, with PyPI/Maven/Cargo/Go falling under deps.dev:version directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses key runtime behaviors: returns top-N passages with offsets and similarity scores, truncates inputs over 200K chars with a flag, and uses specific embedding settings (BGE-base-en, cosine, overlapping windows). This materially helps the agent understand what to expect.

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

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

The description is compact but information-dense. The first sentence states the core function, the second gives usage context, the third explains the workflow pairing, and the final sentence covers technical constraints. Every sentence earns its place, and it is front-loaded with the most actionable 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?

With no output schema, the description clearly explains the return format (passages, offsets, scores) and the verification use case. It also provides performance limits and suggests a sibling tool for end-to-end grounding. This gives the agent everything needed to decide when and how to invoke it.

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

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

The schema already provides 100% coverage for all 3 parameters with clear descriptions. The tool description adds useful real-world examples (SEC 10-K body, 'supply-chain risk') but no critical semantics that are absent from the schema, so it stays at the baseline.

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 "Semantic search INSIDE a fetched record," which clearly identifies the verb and resource. It distinguishes this tool from siblings like ask_pipeworx by focusing on searching within user-provided text, and it explicitly mentions the companion tool ask_pipeworx_grounded to differentiate the workflow.

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

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

"Use when the record is too big to cram into the prompt" provides a direct when-to-use. It also explains how it pairs with ask_pipeworx_grounded, offering an explicit alternative and integration path. No exclusions are needed since the scope is well-defined.

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

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

The description richly discloses behaviors beyond annotations: authentication requirements (Pipeworx OAuth account, anonymous/BYO cannot persist), delivery channel details (feed always on, email/SMS/webhook), constraints (SMS verification, 10/day cap), and webhook-specific nuances (signing secret returned once, auto-disable after 10 failures). This far exceeds the minimal safety info in annotations and provides substantial operational transparency.

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 but well-organized: purpose, return, requirements, types with examples, and delivery channels with caveats. Every sentence adds useful operational detail, and the front-loading of the main action ensures key information appears early. Despite its length, it is efficient and structured for an agent to parse.

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

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

The description covers the return value, auth requirements, and most delivery details, which is necessary given no output schema. However, it omits two subscription types (patent_grant, clinical_trial) and the webhook channel from the prose, even though they appear in the schema. This creates a potential completeness gap where an agent might assume only the listed types/channels are available.

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?

With 100% schema coverage, the baseline is 3, and the description adds valuable context: concrete examples for three of the five types, delivery channel constraints (phone verification, daily caps), and the prerequisite of an OAuth account. However, it omits two enum values (patent_grant, clinical_trial) and the webhook delivery channel from the main text, relying on the schema for those, which is a slight gap.

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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of new subscriptions, with specific resource types and delivery mechanisms.

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

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

The description provides clear context for when to use the tool—when proactive monitoring of live-data streams is needed—and outlines supported subscription types with examples. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide an agent, especially with sibling tools like recent_alerts for one-off queries.

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 behaviors. The description adds useful context beyond annotations by explaining that calling with no arguments returns the full spread, that results are drawn from a live catalog of thousands of tools, and that the output includes tool call shapes. No contradictions with annotations.

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

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

The description is long but information-dense, front-loaded with example queries and structured with a clear list of categories. Every sentence contributes to understanding the tool's purpose, usage, and output. It could be slightly tightened but is well-organized for an onboarding tool.

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

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

Despite having no output schema, the description adequately explains the return value: category-bucketed example questions with tool and argument shapes. It covers invocation modes, parameter behavior, and provides a clear use case. With annotations handling safety, the description is 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?

Schema coverage is 100% for the single topic parameter, so the schema already fully documents it. The description adds examples of valid topics (finance, pharma, betting) and clarifies the behavior when omitting the parameter, but this is marginal value beyond the schema's own description.

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

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

The description clearly states the tool is the onboarding entry point for discovering what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape that answers each. It distinguishes from siblings by explicitly positioning it as the first tool to use when uncertain about capabilities.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit vs. pass the topic parameter. However, it does not explicitly state when not to use it or mention alternative tools like discover_tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by requiring a user-supplied API key or endpoint, which is not covered by annotations. It does not elaborate on rate limits or errors, but this is acceptable given the annotation coverage.

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

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

Two sentences, front-loaded with the primary action, and every sentence provides distinct value: the first explains the mechanism, the second offers an alternative. No redundancy or fluff.

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

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

Given the output schema exists and annotations cover safety, the description is sufficient for effective selection and invocation. It addresses the key prerequisite (API key/endpoint) and alternative tool. A minor gap is not mentioning how to discover language codes, but sibling tools like list_languages cover that.

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

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

Schema coverage is 100% for text, source, and target, so the description does not need to repeat those. It adds mentions of _apiKey and _endpoint, but these are not present in the input schema, which could confuse parameter handling. Still, the core parameters are self-explanatory, and the description adds some operational context.

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: 'Translate text between languages using a LibreTranslate instance you supply'. It specifies the resource (text translation) and distinguishes it from siblings by highlighting the LibreTranslate backend requirement and the alternative deepl_translate.

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 when you have an API key or endpoint, and explicitly directs users without a key to 'deepl_translate' as an alternative. This gives clear usage context and an exclusion condition.

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 significant behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies the soft-delete behavior and the ownership restriction, which are not captured in the annotations (readOnlyHint=false, destructiveHint=false, etc.). 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 two sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by two essential behavioral constraints. 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?

For a simple single-parameter tool with strong annotations and no output schema, the description is complete. It covers the action, ownership, and side-effect (deactivation) which is enough for the agent to select and invoke the tool correctly. No missing critical info.

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

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

Schema description coverage is 100% for the single 'id' parameter, which is already described as 'Subscription id (uuid) returned by subscribe.' The description adds no new semantic detail beyond 'by id,' so it doesn't go beyond the schema. Baseline 3 applies.

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

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

The description clearly states the action: 'Cancel a subscription by id.' This is a specific verb (cancel) and resource (subscription). It distinguishes from siblings like subscribe (create) and list_subscriptions (list), and clarifies the operational effect (deactivation, not 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?

The description provides clear contextual guidance: ownership is enforced, so only the user's own subscriptions can be cancelled. It implicitly tells the agent when this tool is appropriate (cancelling a subscription) and that it cannot be used for others' subscriptions. However, it doesn't explicitly name alternatives or contrast with siblings, but the context is sufficient.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes well beyond this by explaining return verdicts, the distinct meanings of could_not_verify (with verification_error details) and unsupported, the underlying data sources and routing logic, and the fact that it replaces a multi-step workflow. This gives the agent critical behavioral context for correctly using the results.

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 each sentence delivers functional information: usage, routing, return semantics, and error handling. It is front-loaded with examples and the core directive, and later sections systematically cover behavior and output. No filler or redundancy, though the length might be slightly overwhelming for a simple tool; here it is justified.

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 provides a complete picture of return values and verdict types, explains error states, describes the internal pipeline, and even notes the performance benefit. This is more than sufficient for an agent to select and invoke the tool correctly, and it covers edge cases like could_not_verify that would otherwise be ambiguous.

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

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

The schema already documents both parameters with examples, but the description adds substantial value: it explains how tolerance_pct overrides the claim wording, recommends 1–2 for hallucination detection, and states the default cap. The claim parameter is also embedded in the description with natural-language examples, reinforcing the expected input format.

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 unambiguously identifies the tool's purpose: natural-language factual claim verification with a verdict. It lists concrete trigger phrases ('fact check', 'verify the claim that') and contrasts with sibling tools by framing itself as the replacement for 4–6 sequential calls, making its unique role clear.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and details the two routing paths (SEC EDGAR for company financials, grounded pipeline for everything else). It does not explicitly name alternatives, but the scope is so clearly defined that an agent can easily decide when to invoke this tool. The error semantics (could_not_verify vs unsupported) further guide the caller on how to interpret results.

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