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?

Annotations already cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), so the bar is lower, but the description adds substantial behavioral context beyond them: the tool acts as a router/aggregator that fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and can dispatch to live news sources. This is exactly the kind of meta-behavior an agent needs to know and cannot infer from annotations or the schema. No contradiction with annotations.

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

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

The description is long but nearly every sentence earns its place: the prefer-over-web-search directive is front-loaded, followed by domain coverage, mechanism, trigger phrases, examples, and alternative routing. Minor redundancy exists ('even if web search could also answer it' restates the opening directive, and the domain list overlaps with the trigger phrases), but the density of useful guidance 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 simple one-required-parameter gateway tool with no output schema, the description is nearly complete: it explains the return shape (structured answer with pipeworx:// citation URIs), when to use it, when not to, and gives worked examples. Minor gaps remain — no mention of failure modes, handling of non-English queries, or how the agent should present citations — but these are edge concerns for a conceptually simple QA router.

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

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

Schema description coverage is 100% — the question parameter and all five aliases (q, text, input, query, prompt) are fully documented with example inputs in the schema. The description reinforces the parameter's intent with example queries and trigger phrases, but adds no new syntactic or formatting semantics beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the full weight.

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 function with strong specificity: it routes questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with citation URIs. It is explicitly differentiated from web search and from the sibling deep_research tool, with concrete example queries that anchor what the tool handles. The phrasing 'PREFER OVER WEB SEARCH' and the domain list make the resource 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?

Outstanding when-to-use guidance: it explicitly says to prefer this over web search, enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and names the alternative (deep_research) with the exact condition that should select it ('multi-part question that should fan out across many sources'). It even clarifies that breaking news is already routed internally, preempting a likely misrouting. No exclusions are left to inference.

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 idempotent annotations, the description discloses that candidate routing changes may be live, that none are active right now, that it currently matches ask_pipeworx exactly, and that results are compared against the stable router. It also clarifies that this is a full working router with no fallback, adding meaningful behavioral context.

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

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

The description is dense but well-organized, front-loading the beta nature and equivalence to ask_pipeworx. A few phrases repeat the same idea, but each sentence contributes context about current status, usage intent, or experimental behavior.

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 references ask_pipeworx for response shape and arguments, covers current experimental status, and clarifies its full functionality. Since there is no output schema, the reference to ask_pipeworx's response shape helps fill that gap, though more detail about routing behavior could improve completeness further.

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

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

The schema covers 100% of parameters and clearly documents aliases for the required question argument. The description points out that arguments match ask_pipeworx but adds no additional parameter-level meaning, so the schema carries the load.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental routing edge and live candidate improvements.

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 wanting the newest routing, which provides clear usage context. It does not go as far as listing exclusions or comparing with other sibling routing tools like ask_pipeworx_grounded, but the guidance is sufficient for an agent.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description reveals key behaviors: the answer is extracted only from the tool result, refusals are explicit with a defined refusal_reason enum, evidence is a verbatim quote, and an extra LLM call is incurred. This gives the agent accurate expectations about failure modes and result structure.

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 every sentence earns its place: purpose, mechanism, return contract, refusal contract, usage guidance, and cost tradeoff. The most important differentiator ('hallucination-resistant... high-stakes reads') is front-loaded, and the detailed refusal reasons are justified by the need for transparency in failure cases.

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

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

Despite having no output schema, the description fully documents the return shape and failure modes. The parameter surface is simple and fully covered by the schema, and the description supplies the routing behavior, usage boundaries, and cost comparison. Nothing essential is missing for an agent to decide when to invoke this tool and 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?

The schema already provides 100% description coverage for all parameters, including the alias chain leading to 'question.' The description adds only high-level context that the tool 'fills arguments' internally, but it does not add per-parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that routes through the same tool-selection pipeline as ask_pipeworx, fetches data, and grounds its answer strictly in tool results. It specifies the exact output contract — answer, evidence, confidence, source — and the refusal contract, which distinguishes it sharply from sibling tools like ask_pipeworx and ask_pipeworx_beta.

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 usage direction: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx), identifies the tradeoff (one extra LLM call), and lists concrete high-stakes domains like financial verdicts and legal claims.

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?

Beyond readOnly/openWorld/idempotent annotations, the description discloses the parallel decomposition behavior (5,767 tools in parallel), return packet shape (verbatim evidence + confidence + source + fetched_at + citations + gaps[]), the gap behavior ('never invented'), hop behavior per depth, contradiction[] scanning, semantic excerpting of large records, citation resolvability guarantees, and latency expectations (15–60s, thorough ~90s). It also exposes the paid-plan gate for thorough. This is rich behavioral disclosure that materially helps an agent set expectations and handle results.

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

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

The description is long, but nearly every sentence earns its place by disclosing non-obvious behavior (account requirement, non-open-web, parallel decomposition, gaps[], hop semantics, latency, excerpting). It front-loads the critical account/signup gate and the alternative tool. It is dense rather than padded; only minor trimming could improve scannability, but the density is justified for a complex tool.

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

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

Given a complex 2-param tool with no output schema, the description fully compensates: it explains the return packet (findings with evidence/confidence/source/fetched_at/citations), gaps[], contradictions[], hop field, semantic excerpting, latency, and auth/plan constraints. There is no output schema, so this behavioral return-format detail is essential and present. The description is complete for selecting and invoking the tool correctly.

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

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

Schema coverage is 100% and both parameters are already well documented in the schema. The description adds crucial real-world semantics: the depth enum gets operational meaning (quick=3 facets/hop, standard=3 with gap-recovery plus contradictions, thorough=6 paid with iterative hop), and the question parameter's meaning is expanded ('Broad/multi-part is fine — decomposition is the point'). The description also gives concrete example questions. This exceeds the baseline significantly.

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

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

The description names a specific verb+resource (deep multi-source research over Pipeworx's structured data sources) and sharply distinguishes it from open-web search and from the sibling ask_pipeworx/ask_pipeworx_grounded tools. It clearly identifies the tool's target use case (broad/multi-part questions over structured data) and its non-use case (single lookup, breaking/current news), so an agent can select it among 30+ siblings.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), explicit when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'), and explicit exclusion ('this is NOT open-web search'). It also names the fallback alternative when not signed in ('use ask_pipeworx instead') and routes current-news topics to ask_pipeworx. This is exemplary routing guidance.

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

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

Annotations already 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 readOnlyHint/idempotentHint annotations, the description discloses important behaviors: fan-out across sources, USPTO soft-fail, GDELT→GNews fallback, empty sections as real no-data signals, private-company resolved:false with notes, and sources_used/sources_failed reporting. This is rich behavioral context the annotations alone do not 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 extremely dense and front-loaded with examples and the prefer directive, but it is a single sprawling paragraph with long semicolon chains and some redundancy with schema text. It would be more effective broken into clear behavioral sections, though no sentence is purely filler.

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

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

Despite lacking an output schema, the description enumerates each return section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed), explains edge cases like FDA-empty results and private companies, and includes file URI examples. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates the accepted values and examples, adds little beyond the schema, and mostly reinforces what is already structured, so a baseline score of 3 is appropriate.

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

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

Description states a specific verb-resource pair: produce a full cross-source profile of a US public company in one parallel call. It includes varied example queries and explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, making the tool's scope clear and distinguishable.

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 when to prefer this tool over alternatives: ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view. It also specifies accepted input shapes (ticker, CIK, company name) and explains expected behavior for private companies, giving agents clear decision criteria.

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

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

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?

Annotations are all false hints, so the description carries the transparency burden. It discloses the claim_token flow for later re-checking, the daily rate limit (5 per identifier), that it's free and not quota-counting, and that digests are read daily. This adds behavioral context well beyond the sparse annotations, though it doesn't describe the exact return payload.

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

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

The description is dense but every sentence earns its place: it covers scope, exclusions, token mechanics, rate limits, and cost. It's a single long paragraph, which hurts scannability slightly, but it is front-loaded with the main action and contains zero fluff.

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

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

Given four parameters (one nested), no output schema, and a non-trivial claim_token lifecycle, the description covers all critical context: when to use, when not to use, how the token works, rate limiting, and cost. Even without an output schema, the token re-check flow gives the agent enough to understand what to expect on first and subsequent calls.

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 extra semantics for claim_token (exact usage syntax 'pipeworx_feedback({claim_token:"pwfb_…"})' and the purpose of reading resolution status) and guides the message parameter to be specific to Pipeworx tools/packs rather than pasting user prompts.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') naming the resource (Pipeworx tools/packs). It clearly distinguishes this from sibling research/query tools by focusing on feedback submission rather than information retrieval.

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

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

Explicitly lists when to use for bug, feature/data_gap, and praise, and explicitly excludes tools from other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). It also provides a test for confusion ('Pipeworx tool names are the ones this connection lists').

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?

Annotations already mark the tool read-only, idempotent, and non-destructive, so the bar is lower, but the description still adds substantial behavioral context: compatibility_codes semantics, gross-vs-net fee disclosure, skipped_unclassified and low_confidence_pairs handling, and the meaning of null temporal_alignment. It also warns that unverified pairings are returned in either mode, which is exactly the kind of behavior an agent needs to know.

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

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

The description is long, but it is front-loaded with the core purpose and modes, then organized by response, safety fields, and fee/disclosure notes. The length is largely justified because there is no output schema to carry return-value documentation, though some points like temporal alignment are repeated and could be tightened.

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

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

Given three optional parameters, no output schema, and no nested object definitions, the description is remarkably complete: it documents output fields (leg-by-leg prices, top_spreads_pp, compatibility_codes, temporal_alignment), safety codes, skipped-pair counters, fee treatment, and interpretation caveats. An agent has enough context to invoke it correctly and interpret results.

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

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

Although the schema already documents all three parameters and has 100% coverage, the description adds meaning beyond the schema: topic is a fixed enumerated shortcut list, kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and both modes run the identical token-overlap matcher. This enables correct selection and combination of parameters.

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

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

The description opens with a precise verb and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further distinguishes the tool from sibling market tools by detailing two modes, topic shortcuts and explicit ticker/slug pairings, and by stating what the output represents (spread_pp = Kalshi − Polymarket).

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 usage paths for both modes, including when to use topic shortcuts versus custom kalshi_event_ticker/polymarket_event_slug pairs, and cautions that most pre-mapped topics currently return compatibility warnings. It does not explicitly name sibling alternatives or state when not to use this tool, though the mode guidance and caveats give clear context.

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

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

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI unavailable), the `unresolved` field for failed resolutions, `figi_candidates` for ambiguous matches, and the cascading internal lookup behavior. This is rich behavioral context.

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

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

The description is long but information-dense, covering multiple entity types, edge cases, and fallback behavior. Every sentence earns its place, though it could be slightly tighter for faster parsing. The front-loaded use-case list aids quick understanding.

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 two params, no output schema, and this complexity, the description fully covers input semantics, return behavior, edge cases, and limitations. An agent has all the information needed to call it correctly, including how to handle ambiguous matches and partial resolution.

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 detail: for `value` it explains entity name only, bond issuer formatting, and gives concrete examples (AAPL, 0000320193, ozempic). It also explains the meaning of `type` with supported enumeration contexts.

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 ('resolve') and resource ('canonical/official identifiers'), and enumerates the exact use cases (ticker, CIK, LEI, RxCUI) that distinguish it from sibling tools like entity_profile or compare_entities. It clearly states it converts names to IDs needed by other tools.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' It details when to use for company vs drug, explains supported input types, and even clarifies what not to pass (full noun phrases for bonds), providing both positive and negative 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 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses internal routing logic, the special meaning of could_not_verify (with verification_error{stage,detail}), and warns callers not to treat it as evidence. It also clarifies unsupported means no source exists. This is rich behavioral context beyond structured fields.

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

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

The description is dense but well-organized: triggers, purpose, routing, return values, error handling. Every sentence adds operational value; no filler. It front-loads purpose and usage while later sections provide necessary caveats, making it easy to scan and digest.

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 covers all essential return elements: verdicts, actual value with citation, reasoning, and validation_error object. It explains the two special verdicts to prevent misuse. Given the tool's multi-pipeline complexity, this description is complete enough 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%, but the description adds significant meaning to tolerance_pct: it overrides implied tolerance, defaults to 5% cap, and recommends 1–2% for hallucination detection. It also ties the parameter to 'exact percent-delta math,' which the schema alone 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 opens with natural-language trigger examples and states the exact function: 'natural-language claim verification against authoritative sources.' It distinguishes from siblings by noting it 'Replaces 4–6 sequential calls' and routes claim types via distinct pipelines (SEC EDGAR vs grounded). This is a specific verb+resource with clear differentiation.

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 the agent needs to check whether something a user said is factually correct,' and provides context for company-financial vs other claims, plus error semantics. However, it does not explicitly name alternative tools or state when not to use it, so it misses the full 'when-not/alternatives' criterion for a 5.

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