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 mark the tool readOnly, openWorld, and idempotent. The description adds genuinely useful behavior beyond those flags: it reveals this is a router that fills arguments across 5,706 tools, returns pipeworx:// citation URIs, makes one fast call, and already handles live-news queries. 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 front-loaded with the priority directive and dense with actionable routing guidance. Each section earns its place, though the example list could arguably be shortened without losing meaning.

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

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

With no output schema, the description still states the return format: structured answer with stable citation URIs. It covers scope, usage triggers, examples, performance characteristics, and explicit escalation alternatives, which is complete for a broadly targeted router tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the single meaningful parameter by showing the kind of natural-language inputs expected and giving multiple example questions. It does not add formatting syntax, but it clarifies intent beyond the alias list.

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

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

The description states the tool answers factual questions by routing to thousands of verified-source tools and returning structured cited answers. It also explicitly identifies itself as the default entry point, which separates it from ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research.

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

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

It explicitly says PREFER OVER WEB SEARCH, gives concrete trigger phrases like 'what is', 'look up', and 'get the latest', and lists examples. It also tells the agent exactly when to step up to ask_pipeworx_grounded or deep_research.

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, the description discloses experimental status, live candidate routing, current parity with the stable router, and the meaning of 'falls back to nothing' as a full working router. It also states that results are compared against the stable router, which is valuable behavioral context. No contradiction with annotations exists.

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

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

The description is compact and front-loaded with the essential beta identity, followed by current behavior and usage guidance. The date of the last retired candidate adds specificity but is slightly more detail than necessary; otherwise each sentence earns its place.

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

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

Given no output schema, the description nonetheless conveys the response-shape parity with ask_pipeworx, the experimental edge, the current no-candidate state, and the fact that it is a full router with no fallback. An agent has enough to invoke it correctly and set expectations.

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

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

Schema coverage is 100%, and the schema already documents the 'question' parameter and all its aliases. The description adds that the arguments match ask_pipeworx exactly, but offers no additional semantic detail about individual parameters. Baseline 3 is appropriate.

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

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

The description clearly identifies a specific resource ('identical universal router with same 5,706 tools') and the relationship to ask_pipeworx, distinguishing it as the beta variant with candidate routing improvements. It explicitly contrasts with the stabilized version, so an agent can tell what this tool does and how it differs from siblings.

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

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

The description provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also conveys the current state (no active candidate) and the experimental context. It does not exhaustively spell out when not to use it, but the contrast with stable ask_pipeworx is sufficient.

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

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

The description goes well beyond the annotations, detailing refusal behavior, refusal_reason enum values, and the guarantee to use only tool-result evidence. It also discloses the extra-LLM-call cost. Annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial operational context without contradicting them.

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

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

The description is dense but every sentence contributes: it states the mode, explains routing, defines output and refusal shapes, gives use cases, and contrasts with the cheaper sibling. The return format is front-loaded before the refusal format, and no filler is present.

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

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

Even without an output schema, the description fully specifies the success return object and all possible refusal_reason values. It also covers when to choose it vs ask_pipeworx and mentions the cost trade-off. For a one-required-parameter tool, nothing needed for correct invocation or expectation-setting is missing.

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

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

Schema description coverage is 100%, with each alias and the main question parameter explained. The description adds no additional semantic detail about the question parameter, but the schema carries full weight, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific behavior: a hallucination-resistant answer mode that extracts answers using only the tool result content. It differentiates itself from ask_pipeworx by naming it directly and highlighting the grounded extraction difference, so an agent can distinguish it without opening schemas.

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

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

It explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples like financial verdicts, legal claims, medical lookups, and public statements. It also gives an explicit exclusion: 'prefer ask_pipeworx for casual lookups,' plus a cost-based reason.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description vastly expands on behavior: decomposition, parallel routing, hop fields, citation URIs, contradictions, excerpting, and time expectations. No contradictions with annotations found.

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

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

The description is long but dense with information. While it repeats a few points (e.g., 'not open-web search', 'single lookup' appears twice), each sentence generally adds new detail. The structure is logical (account, alternatives, features, expectations), though slightly rambling; still effective.

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

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

No output schema exists, so the description fully explains the return format: findings packet with evidence, source, confidence, citations (citation_uri), contradictions, hop field, and excerpting behavior. It also covers latency expectations. No gaps remain for an agent to understand 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 covers both parameters with descriptions (question and depth enum). The description adds substantial meaning beyond the schema—especially for depth, detailing quick/standard/thorough differences (gap recovery, contradictions, parallel facets) and the default. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, with decomposition of broad/multi-part questions. It explicitly contrasts with sibling tools like ask_pipeworx (single lookups) and mentions it is not open-web search, providing strong 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?

Explicit usage guidance is provided: use for broad/multi-part questions over structured data, avoid for single lookups or breaking/colloquial news (prefer ask_pipeworx). It also explains depth levels, expected latency, and the default behavior, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that it returns ranked language candidates with confidence, which is useful behavioral information beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the core purpose and immediately followed by the key output detail. Every word earns its place with no redundancy.

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

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

For a simple one-parameter tool with an output schema and strong annotations, the description covers the essential what and return behavior. It could mention use cases but is not incomplete given the available structure.

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

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

Schema description coverage is 100% with 'Text to analyze' for the text parameter. The description adds no additional parameter details such as length limits or encoding, so it reaches the baseline but does not exceed it.

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

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

The description clearly states the tool detects the source language of text, using a specific verb and resource. It distinguishes itself from sibling tools like translate and list_languages, which serve different purposes.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it returns top-N results with full input schemas and curated examples, and explicitly states no second schema lookup is needed. This enriches understanding of the tool's output behavior.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is dense but every sentence adds value: trigger examples, core purpose, explicit preference guidance, fan-out targets, return field list with nuances, and parameter constraints. The list format for return fields is clear and front-loaded.

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

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

With no output schema, the description fully explains the return values and their structure (cik, filings, fundamentals, patents, news, LEI). It also covers important caveats like soft-fails, fallbacks, and unsupported names, making the tool fully understandable for invocation.

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

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

The input schema already covers both parameters fully, including the ticker/CIK examples and the unsupported name constraint. The description repeats this information verbatim, adding no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it creates a full cross-source profile of a US public company in one parallel call, with a specific verb ('profile') and resource. It also explicitly differentiates from sibling tools by preferring it over chaining single-pack lookups for holistic views.

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

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

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

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

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

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

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. No extraneous information or repetition of schema details.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, and relationship to sibling tools. The annotations cover safety aspects, so nothing essential is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states what the tool does, the input (URL), the process (fetches page, extracts title/description/key links), and the output format (standard llms.txt markdown). It also differentiates from siblings by mentioning 'auditing how an AI crawler would see a competitor,' which aligns with and distinguishes from tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use the tool. However, it does not explicitly name alternative tools or provide exclusions for when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context that the results depend on the 'configured LibreTranslate instance', indicating the list is dynamic rather than static. There is no contradiction with annotations.

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

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

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

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

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

Given the tool's low complexity, zero parameters, and the presence of an output schema, the description provides sufficient context for correct invocation. The annotations fill in safety and behavioral details, making the overall tool definition complete.

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

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

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

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

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

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

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

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

The description provides clear context: this tool retrieves the set of supported languages from the configured instance. While it does not explicitly name alternatives or state when not to use it, the tool's unique purpose among siblings makes the usage obvious and no exclusions are necessary.

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

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

Annotations already declare readOnlyHint and destructiveHint false, so the description only needs to add context. It adds the scope ('caller's' subscriptions) and lists return fields, which goes beyond basic annotation coverage and gives useful behavioral context without contradiction.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value: the first states what it does and what it returns, the second explains when to use it. No wasted words.

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

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

For a simple list tool with good annotations, the description covers purpose, scope, return fields, and use cases. The lack of an output schema is compensated by listing the returned fields in the description, making it complete for an agent to select and invoke correctly.

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

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

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

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and it distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing. It also enumerates the return fields, making the tool's purpose unambiguous.

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

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

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

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

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

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 establish read-only, idempotent, non-destructive behavior, so the description's job is to add behavioral nuance beyond that. It does so extensively: compatibility_warning and compatibility_codes can be non-empty even with matched_pairs>0; leg matching heuristics, skipped_unclassified and low_confidence_pairs handling, temporal_alignment semantics, and cross-type/cross-subtype drop reasons are all disclosed. This is exceptional transparency for a read-only analysis tool.

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

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

The description is long but highly structured: definition, modes, response shape, safety fields, codes, and caveats. It is front-loaded with purpose before behavioral detail. The main cost is density — the code list and repeated warnings make it feel longer than strictly necessary — but the underlying tool is genuinely complex and most sentences carry diagnostic 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?

With no output schema present, the description carries the full burden of explaining return semantics. It covers raw probabilities, top_spreads_pp with flags, compatibility warnings and codes, skipped/unclassified pairs, low-confidence inspection pairs, temporal alignment, and aggregate skip counters. An agent has enough information to interpret responses and decide whether a returned spread is trustworthy.

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

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

Schema description coverage is 100%, so the baseline is already 3. The description adds real semantic value by explaining that 'topic' is a pre-mapped macro shortcut list, that the explicit ticker/slug create a custom pairing for the other mode, and that explicit parameters override the topic-mapped side. The added value is meaningful but not enormous since the schema already documents each parameter's role.

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, informative statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the resource, the kind of computation, and the two input modes. It also distinguishes itself from same-venue sibling tools like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue, same-question comparison.

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 presents two mutually exclusive usage modes: pre-mapped 'topic' shortcuts versus explicit 'kalshi_event_ticker' + 'polymarket_event_slug' pairings. It also gives practical guidance about when to distrust the results ('pre-mapped ≠ tradeable', 'most pre-mapped topics return compatibility_warning today'), which functions as a clear when-not-to-rely-on-this-invocation warning.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return' and details about internal cascading. No contradictions with annotations. Slight deduction because it doesn't mention response format or pagination (though output schema is absent).

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 clear examples and guidance, but it is quite long and dense (4-5 sentences). Some sentences are packed with many details (e.g., company type) that could be streamlined. While effective, it is not as concise as it could be without losing clarity.

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 (2 required params, no output schema, 2 entity types), the description covers all necessary aspects: what it does, when to use, fallback behavior, supported identifiers, and examples. No output schema exists, but the description adequately describes return values implicitly (identifiers, unresolved list). Complete for its context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds marginal value by listing example inputs for each type (e.g., 'ticker (AAPL), CIK (0000320193), or name') and explaining how 'value' is interpreted. It doesn't add constraints or formatting details beyond the schema, so score remains at baseline.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, listing specific entity types (company, drug) and the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI). It distinguishes itself from sibling tools like 'entity_profile' or 'compare_entities' by focusing on name-to-ID resolution, and provides examples of user queries it handles.

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 tells the agent when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also explains what it replaces ('each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups'), guiding the agent away from chaining multiple 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 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.