Libretranslate

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: default model is free, passing `_apiKey` invokes Anthropic with direct cost to the user, and the return shape includes per-model score/confidence/signals/raw_response and a combined view. This is meaningful behavioral disclosure for cost and expected output.

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, tightly packed with essential information: what it does, default/cost behavior, and return format plus use cases. Every sentence contributes value, no fluff or repetition. The structure is front-loaded with the core action, making it easy to scan.

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

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

There is no output schema, so the description must convey return values, and it does: per-model {score, confidence, signals, raw_response} plus a combined view. It also addresses which models are supported and the parameter for enabling Anthropic. Minor gaps (e.g., what 'signals' contains) exist, but overall it is reasonably complete for a non-destructive probe tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the parameter semantics by explaining that 'workers-ai' is the free default, 'anthropic' requires _apiKey, and that _apiKey is passed straight through to api.anthropic.com with the user paying directly. This adds meaning beyond the schema's basic descriptions, earning 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 tool's function: probe one or more LLMs for their knowledge about an entity and produce a 0-100 visibility score. The verb 'probe' and resource 'one or more LLMs' are specific, and the return format is described. However, it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence or ask_pipeworx, so it misses the top score.

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

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

The description gives clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model and how to enable Anthropic via _apiKey. It does not, however, mention when not to use the tool or explicitly compare to alternatives, 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?

The description adds substantial context beyond the readOnly/idempotent annotations: it routes to 5,462 tools across 1,419 sources, fills arguments automatically, returns structured answers with citation URIs, works on every tier, and handles live news. It fully aligns with annotations and provides valuable operational detail.

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: preference directive, coverage domains, routing behavior, trigger phrases, examples, tiering advice, and escalation paths. It is front-loaded with the most critical guidance and structured logically from primary use to alternatives.

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 6 parameters, no output schema, and rich annotations, this description is highly complete: it explains the return format (structured answer with citation URIs), scope (current and historical data), performance characteristics (one fast call), and how it fits with sibling tools. The examples cover diverse domains and the escalation logic covers edge cases.

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

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

Schema description coverage is 100% and clearly documents the question field and its aliases. The description adds natural-language examples and trigger phrases, but does not provide parameter-level constraints or formatting details beyond what the schema already states. This meets the baseline for high schema coverage without exceeding it.

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 this tool answers factual questions by routing them to appropriate data sources and returning structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, positioning itself as the default entry point.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual questions about real-world entities, with concrete trigger phrases and examples. It names alternatives for escalation (ask_pipeworx_grounded, deep_research) and explains when those are appropriate, covering both use and non-use cases.

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 beyond annotations by disclosing the experimental nature, noting that no candidate routing improvement is currently active, and confirming that the tool is a full working router that matches ask_pipeworx exactly. This adds valuable context about the tool's current behavior without contradicting the read-only, idempotent, open-world hints.

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

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

The description is concise and well-structured, with three sentences that each convey necessary information: beta status, current inactive candidate state, and usage direction. No fluff or repetition, and key details are front-loaded.

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

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

Given the tool's complexity and the absence of an output schema, the description satisfactorily covers purpose, usage, current behavior, relationship to stable ask_pipeworx, and even mentions the response shape. It fully prepares the agent to invoke the tool correctly in context.

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

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

The input schema fully documents all parameters (question and its five aliases) with 100% coverage. The description only generically mentions 'same arguments' and does not add any specific parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools and same response shape. It distinguishes itself from stable ask_pipeworx by noting candidate routing improvements, making its purpose as an experimental variant 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 instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This provides clear when-to-use guidance and implies the alternative of using ask_pipeworx for stable behavior.

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/idempotent annotations, the description discloses the extra LLM call, exact success and refusal return shapes, refusal reason enums, and that only tool result content is used. It adds substantial context about behavior and failure modes.

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

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

The description is information-dense and well-structured: definition, mechanism, return formats, usage guidance, and cost trade-off each in one sentence. No fluff or repetition; 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?

Given there is no output schema, the description fully specifies the success return fields and refusal reasons, covering all outcomes. It also provides context for high-stakes use cases, making the tool self-contained for correct invocation.

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

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

Schema coverage is 100% with all alias parameters described in the schema. The description adds no additional parameter semantics; baseline 3 applies since the schema handles parameter documentation.

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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, explaining its mechanism of extracting answers only from tool results. It clearly differentiates from sibling ask_pipeworx by emphasizing groundedness, evidence quotes, and explicit 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also contrasts with ask_pipeworx by noting the extra LLM call cost and advising preference for casual lookups.

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, openWorld, idempotent, non-destructive), the description discloses numerous behavioral traits: resolver contract with match confidence levels, status codes, news fallback behavior (429 handling), wide-spread warnings, cancellation-rule parsing, and suppression of analysis fields for low-confidence matches. This adds substantial context about how the tool behaves under various conditions, exceeding what annotations convey.

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

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

The description is long but structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every section provides unique value, but the sheer length may be more than necessary for simple use cases. Still, the organization and density of useful information make it appropriate for a complex tool.

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

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

With no output schema, the description comprehensively covers all response shapes (market, analysis, evidence), resolver fields, parent_event extraction, news fields, error/fallback statuses, and cancellation rules. It also explains edge cases like de-indexed markets and wide spreads. The description is thorough enough to guide an agent through correct usage and interpretation without ambiguity.

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

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

Although the schema covers all parameters with descriptions, the tool description adds significant practical semantics: market accepts slug/URL/question text, depth 'quick = 2-3 evidence sources' vs 'thorough = full fan-out', and include_raw controls response size (~20KB vs 50-500KB). This enriches the schema descriptions and helps agents choose appropriate values.

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 begins with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like ask_pipeworx and deep_research by focusing on Polymarket bets, classification, and parallel fan-out. The scope (slug/URL/question) and outputs (evidence packet + market-vs-model comparison) are precisely defined.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also includes detailed fan-out examples and notes on blocking routes (low_confidence_match, market_closed_or_inactive), giving strong clarity on when and why to invoke the tool. Though no explicit alternatives to siblings are named, the use cases are specific enough to differentiate.

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 well beyond the annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and return format including citation URIs. It also notes the tool replaces 8–15 sequential lookups, which is useful operational context. No contradiction with readOnlyHint or other 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 meaningful detail. It opens with user phrasing examples and ends with the efficiency claim. It could be slightly more structured (e.g., separating company vs. drug details), but it remains readable and focused 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?

Given no output schema, the description adequately covers return behavior: 'paired data + pipeworx:// citation URIs,' sorted results, and per-type metrics. It also covers limits (2–5 entities), data sources, and special handling of fiscal years. This is complete enough for an agent to know what to expect and when 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?

Schema coverage is 100%, but the description adds significant meaning: it explains what each type retrieves (10-K metrics vs. adverse-event/trial counts), gives concrete examples for values, and clarifies sorting behavior. This goes well beyond the bare schema descriptions, enriching the agent's understanding of how parameters affect output.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes a variety of trigger phrases and explicitly contrasts with sequential single-pack lookups, distinguishing it from sibling tools like entity_profile.

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

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

It provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases like 'X vs Y' and 'rank these companies.' However, it does not mention specific alternative tools by name or state when NOT to use this tool (e.g., for in-depth single-entity research), so it stops short of full when/when-not coverage.

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 rich behavioral context beyond the annotations: expected latency (15-60s), decomposition into facets, parallel routing, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] and contradictions[] arrays, hop field, and semantic excerpting behavior. No contradictions with annotations; the read-only and idempotent hints are consistent with the described behavior.

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

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

The description is long but dense with essential information; every sentence adds value. It is front-loaded with the most critical account requirements and alternative-tool guidance. However, it is a single unwieldy block of text; better paragraph breaks would improve scannability given the complexity.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers what the agent needs: return format, latency, edge cases (gaps when data missing), contradictions for deeper depths, citation fetchability, and the behavior of excerpting large records. No critical context appears missing.

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

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

Schema coverage is 100% and already describes both parameters thoroughly. The description adds some contextual flavor (e.g., depth behavior in 'Second-hop iteration') but mostly repeats or implies what the schema states. Thus it neither significantly adds nor detracts from the schema, meriting the baseline score for high coverage.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call. It distinguishes from siblings by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single 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 when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use with alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also mentions account prerequisites, making the usage context unambiguous.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that it returns ranked language candidates with confidence, which is useful behavioral information 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 two concise sentences, front-loaded with the core purpose and immediately followed by the key output detail. Every word earns its place with no 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 one-parameter tool with an output schema and strong annotations, the description covers the essential what and return behavior. It could mention use cases but is not incomplete given the available structure.

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 'Text to analyze' for the text parameter. The description adds no additional parameter details such as length limits or encoding, so it reaches the baseline but does not exceed it.

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 detects the source language of text, using a specific verb and resource. It distinguishes itself from sibling tools like translate and list_languages, which serve different purposes.

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

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

No guidance is given on when to use this tool versus alternatives such as translate or list_languages. The description simply states what it does without any contextual or exclusionary notes.

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, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it returns top-N results with full input schemas and curated examples, and explicitly states no second schema lookup is needed. This enriches understanding of the tool's output behavior.

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

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

The description is three sentences, each with a distinct purpose: stating the action, listing use cases/domains, and explaining the output and when to call. The front-loaded first sentence immediately communicates the core function. The domain list is detailed but relevant, and no sentence is redundant.

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 is complete for a simple read-only discovery tool. It explains the return value (top-N tools with names, descriptions, full schemas, curated examples) even without an output schema. The usage guidance is sufficient, and the annotations cover the safety profile. There are no significant gaps.

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

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

Schema description coverage is 100%, with each parameter already described (including aliases and limit). The description adds some contextual value by listing example domains (SEC filings, FDA drugs, etc.) and mentioning 'top-N' which relates to the limit parameter. However, it does not add substantial semantics beyond the schema's own descriptions, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by positioning itself as a discovery/meta tool, listing specific domains it covers. This makes its function unambiguous.

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

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

The description provides clear context for when to use the tool: 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available.' It implies when not to use it (when you need one specific answer) but does not explicitly name alternative tools. This is clear usage guidance without full exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses behavioral details such as the fan-out across multiple sources, the patents soft-fail due to USPTO sunset, the GDELT→GNews fallback, and specifics about returned data (e.g., sorted fundamentals, up to 5 filings, pipeworx URIs).

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 value: trigger examples, core purpose, explicit preference guidance, fan-out targets, return field list with nuances, and parameter constraints. The list format for return fields is clear and front-loaded.

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

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

With no output schema, the description fully explains the return values and their structure (cik, filings, fundamentals, patents, news, LEI). It also covers important caveats like soft-fails, fallbacks, and unsupported names, making the tool fully understandable for 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 covers both parameters fully, including the ticker/CIK examples and the unsupported name constraint. The description repeats this information verbatim, adding no new semantic meaning beyond what the schema provides. 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 it creates a full cross-source profile of a US public company in one parallel call, with a specific verb ('profile') and resource. It also explicitly differentiates from sibling tools by preferring it over chaining single-pack lookups for holistic views.

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

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

Explicitly says when to use: ALWAYS PREFER when the user asks for a holistic view, and provides an alternative: use resolve_entity first if only a name is available. This gives clear selection guidance and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns with this. The description adds contextual value by explaining why deletion might be needed (stale context, sensitive data) without contradicting the annotations. It doesn't mention irreversibility, but that's already implied by the destructive hint.

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, and every sentence adds value. No extraneous information or repetition of schema details.

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 no output schema, the description fully covers purpose, usage, and relationship to sibling tools. The annotations cover safety aspects, so nothing essential is missing.

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

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

Schema coverage is 100% and the only parameter 'key' is fully described as 'Memory key to delete.' The description adds only the phrase 'by key,' which doesn't enrich the schema's meaning. Given the high coverage, a baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' This is a specific verb+resource pairing that distinguishes it from siblings like remember and recall, which store and retrieve memories respectively.

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

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

The description provides explicit usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references complementary tools with 'Pair with remember and recall,' giving clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral context: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output shape ('single text blob ready to drop at site-root/llms.txt'). This goes beyond the annotations, though it doesn't cover failure modes or network limitations, so not a 5.

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

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

The description is three sentences, front-loads the core purpose, then explains mechanics and ends with concrete use cases. Every sentence earns its place; there is no filler or repetition of schema/annotation details.

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 moderate complexity, no output schema, and strong annotations, the description is mostly complete: it covers input, process, output format, and use cases. It omits potential edge cases (e.g., inaccessible URLs, link limits behavior) but for typical usage it provides enough context for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% coverage with clear descriptions for both parameters ('url' and 'max_links'). The description adds general context about key links but does not materially enhance the parameter semantics beyond the schema. With high schema coverage, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states what the tool does, the input (URL), the process (fetches page, extracts title/description/key links), and the output format (standard llms.txt markdown). It also differentiates from siblings by mentioning 'auditing how an AI crawler would see a competitor,' which aligns with and distinguishes from 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 provides explicit 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'), giving clear context on when to use the tool. However, it does not explicitly name alternative tools or provide exclusions for when not to use it, 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context that the results depend on the 'configured LibreTranslate instance', indicating the list is dynamic rather than static. There is no contradiction with annotations.

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

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

The description is a single, front-loaded sentence that directly states the function without any unnecessary words or redundancy. It earns its place and is easily scannable.

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

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

Given the tool's low complexity, zero parameters, and the presence of an output schema, the description provides sufficient context for correct invocation. The annotations fill in safety and behavioral details, making the overall tool definition 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?

The tool has zero parameters, so the input schema fully documents its input. The description does not need to elaborate on parameters, and the baseline of 4 applies because there is nothing to disambiguate.

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

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

The description uses a specific verb 'List' and identifies the resource as 'languages supported by the configured LibreTranslate instance', which clearly distinguishes it from sibling tools like detect_language and translate. The purpose is unambiguous and self-contained.

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: this tool retrieves the set of supported languages from the configured instance. While it does not explicitly name alternatives or state when not to use it, the tool's unique purpose among siblings makes the usage obvious and no exclusions are necessary.

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

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

Annotations already declare readOnlyHint and destructiveHint false, so the description only needs to add context. It adds the scope ('caller's' subscriptions) and lists return fields, which goes beyond basic annotation coverage and gives useful behavioral context 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 two sentences, front-loaded with the main action, and every sentence adds value: the first states what it does and what it returns, the second explains when to use it. No wasted words.

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

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

For a simple list tool with good annotations, the description covers purpose, scope, return fields, and use cases. The lack of an output schema is compensated by listing the returned fields in the description, 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?

The schema description coverage is 100% for the single parameter (include_inactive), so the baseline is 3. The description does not add any meaning beyond the schema for this parameter, but doesn't need to since the schema fully explains it.

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 'List the caller's active subscriptions' with a specific verb and resource, and it distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing. It also enumerates the return fields, making the tool's purpose unambiguous.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies alternatives (subscribe/unsubscribe) without naming them directly, so it falls just short of fully explicit when-not-to-use guidance.

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

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

With all annotation hints false, the description carries the full behavioral burden. It discloses rate limiting (5/day/identifier), that it is free and doesn't count against quota, the read/review process (daily digests), and the impact on roadmap. 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 fairly long but well-structured: it opens with purpose, then usage conditions, then scope exclusions, then content guidance, then rate limits. Every sentence adds operational value, though it could be tightened slightly without losing critical guidance.

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

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

Given the simple 3-parameter schema (fully covered), absent output schema, and neutral annotations, the description covers all necessary context: when to use, how to craft feedback, scope boundaries, rate limits, and expected handling. No important gap remains 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by advising users on message content ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which directly informs how to fill the message parameter. It also clarifies type semantics in 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 opens with a specific verb and target ('Tell the Pipeworx team something is broken...'), immediately clarifying this is a feedback channel. It distinguishes itself from sibling tools (like ask_pipeworx or discover_tools) by enumerating feedback types (bug, feature/data_gap, praise) and explicitly scoping to Pipeworx-served tools.

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

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

Explicitly states when to use the tool (bug, missing feature, praise), when NOT to use it (feedback for other MCP servers), and provides a decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). Also instructs what not to include (past user prompts).

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial transparency: it discloses the data source (CF analytics-engine), confirms no PII is included, and explains caching behavior ('Cached 5min-1h depending on window'). This gives the agent a strong understanding of what to expect and safety/consistency implications.

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 output, then provides a numbered list of use cases, and ends with technical/behavioral details. Every sentence adds value; there is no repetition or filler. The structure makes it easy to scan.

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 one optional parameter and no output schema, the description covers everything an agent needs: what it returns, how to think about the window, use cases, and data characteristics. No critical information is missing.

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

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

The schema already fully describes the 'window' parameter (enum with 24h/7d/30d and a description). The tool description adds semantic guidance on how window choice affects results ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which is useful beyond the schema's factual 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 opens with a clear statement of what the tool reports ('What other AI agents are calling on Pipeworx right now') and explicitly lists the outputs: top tools, top packs, and total call volume. This distinguishes it from sibling tools like discover_tools, which likely search for tools by query, while this provides aggregate trending data.

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

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

The description gives explicit use cases ('Useful for: (1) ... (2) ... (3) ...'), clearly indicating when an agent should invoke this tool. However, it does not explicitly mention when not to use it or name alternative tools, which prevents a perfect 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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: partition placeholder filtering, Jaccard similarity threshold, fill-check pricing against live CLOB depth, and the realizable_edge_pp <= 0 caveat. These details go well beyond what annotations alone provide.

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

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

The description is lengthy but organized with clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the core purpose and no-arg behavior, and every paragraph contributes distinct operational detail. Some redundancy exists, but the complexity justifies the length.

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

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

For a read-only analysis tool with two optional parameters and no output schema, this description covers invocation modes, input formats, internal filters, response contents, and important caveats. It is nearly self-contained and leaves little ambiguity about expected behavior.

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

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

Both parameters (event, topic) are already well documented in the schema (100% coverage), and the description further clarifies when to use each, provides concrete examples, and explains mode-specific behavior. It also adds the no-arg fallback semantics that the schema does not convey.

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

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

The description clearly states the tool finds Polymarket arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique detection methods and mode variants.

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 mode selection: no args for trending_scan, 'event' for single-market partition_check, and 'topic' for cross-event scanning. It also names polymarket_fill_risk as the alternative for custom sizing, giving clear when-to-use vs. alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context: caching at the KV level for 1 hour, a 24h-move warning when price already reflects the edge, fed candidates excluded from ranking due to unreliable signals, and _diagnostics to explain empty segments. It also discloses design choices like partition overround correction and placeholder-slug filtering, giving agents a clear understanding of behavior beyond the safety annotations.

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

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

The description is long but well-organized with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It is front-loaded with the core purpose and then details the response structure and filters. Some details (e.g., specific alpha values per sport) go beyond what an agent needs for invocation, but the structure earns its place for a complex tool.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: it describes the top-level by_segment structure, per-opportunity fields like edge_pp_net, kelly_fraction, market.liquidity, and spread_pp, plus the _diagnostics and fed_candidates/note sections. It also covers caching behavior and filter semantics, making the tool's behavior highly predictable for an agent.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description adds meaningful nuance beyond the schema, such as explaining that partition arbs have parent-level kelly_fraction_half=0 by design (which justifies the min_partition_leg_kelly knob) and the slippage rationale (zero fees but 20-50bp spread costs). These insights help agents choose parameter values more intelligently, though most parameter details remain in the schema.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scan/return), and the scope (top markets, discovery-oriented). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven edge discovery rather than pure arbitrage or tracking.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on when to adjust knobs like min_liquidity and max_spread_pp to filter out unusable edges. However, it does not explicitly name sibling tools or state when NOT to use this tool, so it stops short of full exclusion 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 well beyond the annotations (readOnly, openWorld, idempotent) by revealing response semantics (tracked[] vs expired[]), data freshness limitations (60-day TTL, snapshot gaps), and the specific methodology for decay calculation (daily closes, net of default slippage). This adds substantial value beyond the structured hints.

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

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

The description is long but dense and well-structured with explicit 'RESPONSE' and 'LIMITS' sections. Every sentence provides meaningful detail, and the front-loaded first sentence nails the core purpose. It earns a 4; it would be a 5 if it were slightly more compact, but the complexity justifies the length.

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

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

With no output schema, the description fully documents the response shape (tracked, expired, snapshot_dates) and explains key caveats (TTL, snapshot gaps, signed edge_pp_net, decay computation). It also covers practical limitations such as history depth and data origin, making it comprehensive for the tool's complexity.

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

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

The input schema already covers both parameters with descriptions (days lookback with clamp, window family with allowed values). The description merely restates the defaults and the window family name without adding new syntax or format guidance. Since schema coverage is 100%, the baseline of 3 applies, and the description does not elevate it.

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, with a specific question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges tool by focusing on historical behavior rather than current edge values.

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 strong context for when to use the tool (e.g., comparing a fresh edge to an old edge, using median lifespan as a competition clock) and explains data gaps due to cache-miss behavior. However, it does not explicitly state when not to use it or name alternative tools for specific scenarios, stopping short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral detail: it walks the order-book ladder, returns verdict enums, distinguishes top-of-book vs VWAP realization, flags forced_directional_risk, and explains why partial basket fills are dangerous. This far exceeds the structured hints and contains 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 dense and front-loaded, with clear SINGLE-MARKET/BASKET sections and a strong 'USE THIS' callout. It is longer than average, but the two-mode complexity and detailed return fields justify the length. It earns a 4 rather than 5 because bullets or more visual separation would improve scannability.

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

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

For a complex, mode-dependent tool with no output schema and no required parameters in the schema, the description fully compensates: it explains required inputs, defaults, return values for both modes, edge-case risks (thin_legs, forced_directional_risk), and provides concrete usage context. There is no missing information an agent would need 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?

Even though schema coverage is 100%, the description adds crucial interpretation: size_usd means max spend on buys but target proceeds on sells, basket size_usd is settlement notional with shares per leg paying $1, and side auto-selects based on partition sum. It also maps market/event to the two modes and explains what each returns, making parameter usage concrete and actionable.

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-object pair ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and immediately distinguishes single-market and basket/partition modes. It also lists exact return fields per mode, making the tool's purpose unambiguous and distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming sibling tools and a clear threshold. It also explains when each mode applies (single-market vs basket) and the risk scenario that motivates the check, leaving no guidance gap.

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, disclosing compatibility_warning conditions, temporal_alignment semantics, skipped_cross counters, and the limitation that many pre-mapped topics aren't tradeable. This adds substantial behavioral context about edge cases and output reliability. No contradiction with readOnly/idempotent 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?

Purpose is front-loaded and the description uses clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). However, it is fairly long and repeats the compatibility warning message multiple times, making it slightly less concise than it could be.

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 thoroughly covers response components (leg-by-leg prices, top_spreads_pp), safety fields, temporal alignment, and edge cases. It explains both modes and the meaning of skipped_cross_type/subtype, making the tool's behavior fully understandable for an agent.

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

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

Schema description coverage is 100%, but the tool description adds important behavioral meaning: topic mode auto-fetches matching events, while explicit parameters override the topic-mapped side. It also clarifies that custom pairings require both explicit fields. This goes beyond simply restating 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 states a specific verb and resource: computes the 'cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on same-event cross-venue pricing, and it details two explicit modes.

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

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

The description provides clear usage context: when to use the topic mode vs explicit kalshi_event_ticker + polymarket_event_slug. It also gives a strong caveat that most pre-mapped topics return compatibility_warning and 'pre-mapped ≠ tradeable.' However, it doesn't explicitly name alternative tools or state when not to use this tool.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description doesn't need to restate safety. It adds valuable behavioral context beyond annotations: the scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys when the argument is omitted. This enriches the agent's understanding without contradicting the annotations.

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

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

The description is only two sentences long, yet it covers purpose, usage examples, scoping, and relationships with sibling tools. Every sentence earns its place; there is no redundancy or filler. The structure is front-loaded with the core action and then contextual details.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It explains what the tool does, when to use it, the scoping model, and how it pairs with remember and forget. The annotations provide the safety profile, so the description doesn't need to restate that. The only minor omission is behavior for missing keys, but that is not essential for tool selection.

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 for the single optional 'key' parameter is 100%, giving a baseline of 3. The description adds meaningful semantics by explaining that the key refers to a value 'previously saved via remember' and provides concrete examples ('user's target ticker, an address, prior research notes'). It also clarifies the behavior when omitting the key (list all keys), which enhances the schema's 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 function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This uses a specific verb and resource, and explicitly distinguishes the tool from siblings by referencing 'remember' and 'forget' as counterparts. The purpose is unambiguous and well-scoped.

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 to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also indicates how to list keys by omitting the key argument and mentions scoping. However, it does not explicitly state when not to use this tool or list alternative retrieval tools, so it stops short of full exclusionary guidance.

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

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

Beyond the read-only and non-destructive annotations, the description adds valuable behavioral context: the returned payload structure (source, citation_uri, raw event), the mark_read side effect that affects subsequent calls, and that polling is safe. This enriches the agent's understanding beyond the structured hints.

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

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

Concise and front-loaded: the first sentence states the core action, followed by return details, filtering, mark_read, and a practical polling/HTTP alternative. Each sentence adds distinct value with no redundancy.

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

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

Despite no output schema, the description conveys the essential return fields, filtering options, and side-effect behavior. It also addresses a common use case (polling) and provides an alternative access path, making it complete for a read-only feed 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?

Input schema covers all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds an example filter value ("sec_8k") and clarifies the mark_read consequence ('next call only shows newer ones'), which goes slightly beyond the schema's terser wording.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource statement. It clearly differentiates from siblings like list_subscriptions or recent_changes by focusing on fired alerts with source, citation_uri, and raw payload.

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

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

Provides clear usage context: filtering by type and since, mark_read behavior for incremental polling, and even mentions an alternative HTTP endpoint for scripts and dashboards. However, it doesn't explicitly contrast with sibling tools like ask_pipeworx or recall, so it's a 4 rather than 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 (read-only, open-world, idempotent), the description discloses rich behavioral details: parallel fan-out to multiple APIs, fallback logic, soft-fail for USPTO, accepted `since` formats, and the structured return format with citation URIs. No contradictions with annotations.

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

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

The description is long but every sentence earns its place: example queries, source fan-out, fallback, parameter semantics, return structure, and alternative tool. It is front-loaded with concrete user intents and organized logically, making it highly 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 complex multi-source tool with no output schema, the description is remarkably complete. It covers data sources, fallback behavior, parameter formats, return shape (changes[], total_changes, citation URIs), and alternative tool guidance, leaving no significant gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining `since` formats (ISO or relative), recommending '30d' or '1m' for typical monitoring, and clarifying `value` can be ticker or CIK. This enriches the schema's dry definitions.

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

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

The description clearly states that `recent_changes` provides a change feed for a company over a time window, using example queries to convey intent. It distinguishes itself from sibling tools by explicitly naming `entity_profile` as the alternative for static profiles, 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 gives concrete usage context with example queries and explains when to use this tool versus `entity_profile`. It also details source fallback behavior (GDELT preferred, GNews on rate limits) and notes the USPTO soft-fail, providing clear guidance on expected behavior.

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 meaningful behavioral context beyond annotations: key-value storage scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. Annotations already cover idempotency and non-destructiveness, but the description doesn't specify overwrite behavior for existing keys, a minor gap.

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 with no redundancy. The purpose leads, followed by usage context, storage details, and companion tool references. 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 2-parameter tool, the description is thorough: covers persistence, scope, examples, and related tools. No output schema is needed for a save operation, and the description fully addresses the tool's role in the agent's workflow.

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

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

Schema coverage is 100% with both parameters well-documented. The description reinforces that this is a key-value pair and gives examples, but doesn't add substantial new meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with concrete examples. It distinguishes itself from siblings by explicitly naming recall and forget as companion tools for retrieval and 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also differentiates from recall and forget by explaining their complementary roles, giving the agent a clear decision framework.

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 rich behavioral context beyond the annotations: it discloses that each call cascades through multiple internal endpoints, replaces 2-3 manual lookups, returns specific fields (ticker+CIK+company_name, RxCUI+ingredient+brand), and provides citation URIs. This aligns with and supplements the readOnly/idempotent/openWorld 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 slightly long but well-structured: starts with real user queries, then states purpose, then breaks down supported types with specifics. No wasted sentences, but it could be tighter by trimming the example phrasings a bit. Overall every sentence contributes 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?

Given no output schema, the description compensates by fully describing return values for each type (ticker, 10-digit CIK, company_name, RxCUI, ingredient, brand, and citation URIs). It also explains the internal cascading behavior, making the tool's behavior predictable for an agent. This is complete for a lookup tool of this complexity.

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

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

Input schema covers both parameters fully, but the description adds significant meaning: for 'value', it explains that company accepts ticker, CIK, or name with auto-disambiguation; for 'drug', it specifies brand/generic names. It also clarifies what each type returns. This goes beyond the schema's basic enum/string descriptions, though some details like CIK formatting are not explicit.

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

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

The description states a clear, specific purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries and distinguishes from siblings by noting this is the tool to use when you have a name but need an ID, which differentiates it from entity_profile or compare_entities.

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

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

Gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types (company, drug), acceptable input formats (ticker, CIK, name; brand/generic name), and expected outputs. This clearly communicates when to use this tool over alternatives.

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

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

Annotations already assert readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds value by disclosing that it internally probes each entity with ai_visibility_check and ranks by score, plus specifies the output components (score, confidence, signal density). 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?

Three compact sentences: purpose, mechanism, and use case, plus a clear output description. Every sentence earns its place with no filler or repetition of schema fields.

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 explicitly states the return format (ranked list with score, confidence, signal density), which is essential for an agent to interpret results. It also explains the composite probe behavior and example use, making the tool's behavior complete for a read-only aggregation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-level semantics beyond the schema; it mentions 'your brand + N competitors' which mirrors the schema's note about first entry as subject. No extra param meaning is provided.

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+scope: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison, ranking, and surfacing most/least recognized, making its 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?

Provides a clear use case ('competitive AI-marketing audits') and a concrete example question. It does not explicitly state when not to use or name alternatives like compare_entities, but the context is strong enough for an agent to select this tool when a side-by-side comparison is needed.

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

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

Beyond the readOnly, openWorld, and idempotent annotations, the description discloses important behavioral details: it fans out to multiple services, may experience 5-30s delays on first bundlephobia measurement of a new version, and degrades gracefully with a sources_failed field. These are non-obvious insights that help the agent set expectations.

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

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

The description is dense but every sentence serves a purpose: the first defines the composite check, the second gives usage triggers, the third lists return fields, and the fourth covers ecosystem limits and failure behavior. It is front-loaded and contains no filler, making it highly 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?

Even though there is no output schema, the description enumerates the summary block fields (is_latest, license, published_at, advisory_count, etc.) and mentions per-advisory details, links, and alternative versions. It also addresses edge cases (NPM-only, timeouts) and explains that partial failures still return useful data, so the agent knows what to expect.

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

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

Schema description coverage is 100%: both the 'package' and 'version' parameters are already well-described in the input schema. The description adds no further parameter-level detail, so it meets the baseline for high schema coverage but does not exceed it.

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

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

The description clearly states it is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It specifies the exact verb (check) and resource (npm package), and the distinctive composite nature distinguishes it from sibling 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?

It explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear trigger conditions. It also states an exclusion: non-NPM ecosystems (PyPI, Maven, Cargo, Go) should go directly to deps.dev, not this tool.

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

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

The description goes well beyond the annotations by revealing specific behaviors: returns character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, has a 200K char cap with truncation flagged. No contradictions with readOnlyHint or idempotentHint.

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

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

Four dense sentences, each earning its place: purpose, use case, workflow pairing, and technical constraints. No filler; front-loaded with the core action.

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 specifies return values ('top-N passages with character offsets and similarity scores'), limitations ('cap is 200K chars; longer inputs truncated and flagged'), and integration context. This is complete for a search tool of this complexity.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaningful context: the text parameter is 'the text you already pulled' and query examples are reinforced. It also clarifies the limit's purpose and default range, slightly exceeding the schema's provided information.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by emphasizing it operates on already-fetched text and by explicitly pairing with ask_pipeworx_grounded for grounding over relevant passages.

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 an explicit when-to-use condition: 'Use when the record is too big to cram into the prompt.' It also names an alternative/workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear 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 reveals multiple behavioral details beyond annotations: anonymous/BYO cannot persist, feed is always on, email/SMS are optional with delivery limitations (phone verification, 10/day cap). This goes well beyond the readOnlyHint/idempotentHint annotations and clarifies important operational constraints.

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

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

The description is information-dense but well-organized. It front-loads the core purpose, then details types, requirements, and delivery options in a logical progression. No filler; every sentence contributes unique value.

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

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

For a tool with nested objects, an enum type, and no output schema, the description is remarkably complete. It covers auth requirements, type-specific parameter examples, delivery channels with limitations, and indicates the return value. The lack of an output schema is compensated by the explicit statement that the new subscription id is returned.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for each subscription type (e.g., issues:["5.02"] = officer change, params:{topic:"fed"}), which helps the agent construct correct parameter objects. It also clarifies delivery semantics (e.g., phone must be verified) 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 states a precise action: 'Create a proactive monitoring subscription to a live-data event stream' and names the return value ('Returns the new subscription id'). It clearly distinguishes the tool from siblings like list_subscriptions or unsubscribe by focusing on creation and event types.

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

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

The description provides clear context for when to use the tool: for proactive monitoring of specific event types (e.g., sec_8k, polymarket_edge). It mentions the requirement of an OAuth account, which serves as a precondition. It does not explicitly name alternatives but the context is strong enough.

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 provide safety signals (readOnly, openWorld, idempotent). The description adds behavioral context by explaining that the tool returns example questions with exact tool and argument shapes drawn from the live catalog, and describes the optional focus behavior. 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 a dense, single paragraph that packs in the query patterns, output structure, parameter usage, and positioning. It is front-loaded with common user phrasings and remains organized with em dashes, though it is slightly verbose and could be split into shorter sentences.

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 absence of an output schema, the description thoroughly explains return values (category-bucketed example questions with tool + argument shape) and covers both invocation modes. It also provides sufficient context for an agent to decide when to use this tool, making it 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?

The parameter schema already covers 'topic' with valid values and omission semantics, giving a baseline of 3. The description adds value by providing real-world examples ('finance', 'pharma', 'betting') and reinforcing the no-argument behavior, going beyond the schema without duplicating it.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, listing example queries and the exact output (category-bucketed example questions). It distinguishes from siblings by positioning itself as the 'use this FIRST' tool and naming meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear guidance on the tool's role in the overall workflow and differentiates it from more specific tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral context by explaining the 'auto' source default and that the detected source is returned when applicable. No contradiction with annotations.

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

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

Two concise sentences with no redundancy. The key behaviors (auto source, return value) are front-loaded efficiently.

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 translation tool with a rich schema and output schema, the description covers the essential behavior (auto-detection, return format) without needing to explain parameters or return values in detail.

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

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

Schema covers 100% of parameters with descriptions. The description only reiterates the 'auto' source behavior already in the schema, adding no new semantic information beyond what is structured.

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

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

Clear verb+resource: 'Translate text' immediately states the tool's function. It also notes auto-detection of source language and return value, distinguishing it from sibling tools like detect_language which only detects language.

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 for translation but does not explicitly contrast with related tools (e.g., detect_language) or state when not to use it. There is no exclusion or alternative mention, so guidance is 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 indicate non-readonly, idempotent, and non-destructive behavior. The description adds critical context beyond these: ownership restriction (only your own subscriptions) and the deactivation-not-deletion semantics that preserve history for 'recent_alerts'. This fully aligns with and enriches 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?

Two concise sentences deliver all necessary information: the action, the ownership constraint, and the post-effect. No wasted words; the most important fact ('Cancel a subscription by id') is front-loaded.

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

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

For a simple single-parameter cancellation tool with no output schema, the description covers the action, the prerequisite (ownership), and the downstream impact on historical data. It is self-contained and sufficient for an agent to correctly invoke the tool.

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

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

The schema fully covers the 'id' parameter with a clear description (uuid returned by subscribe). The description adds the ownership constraint that the id must reference your own subscription, providing extra semantic meaning beyond the schema's basic type/origin information.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. It also states the behavioral nuance (deactivation vs. deletion), making the tool's 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 provides clear context: use this tool to cancel your own subscription, with ownership enforcement explicitly noted. The mention that historical events remain available via 'recent_alerts' implies the appropriate use case. However, 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns a specific verdict set, uses SEC EDGAR/XBRL for financial claims, falls back to a grounded pipeline for other claims, and claims to replace 4–6 sequential calls. 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 relatively long but information-dense, covering trigger phrases, usage, routing logic, return values, and efficiency. Every sentence contributes useful information, though there is slight redundancy between the opening sentence and the 'Use whenever' clause. Overall, it is well-structured and front-loaded.

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

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

Given the tool has no output schema, the description compensates by specifying the return values (verdict types, actual value with citation, reasoning). It also explains the processing paths and parameter semantics, making the tool's behavior clear and 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?

While the schema already describes both parameters, the description significantly enriches their meaning. It provides concrete examples for 'claim' and explains 'tolerance_pct' in detail: valid range (0.5–50), override behavior, default derived from wording with a cap at 5, and guidance for hallucination detection. This far exceeds the schema's bare 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 purpose: natural-language claim verification with fact-checking trigger phrases. It specifies the scope (company-financial vs. other claims) and distinguishes it from generic ask tools by detailing the two processing paths and expected output.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides guidance on claim types (company-financial vs. other) and explains the fallback behavior. It does not explicitly name alternative tools, but the context is clear and adequate for an agent to know when to invoke this tool.

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