Deepl

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

With strong annotations (readOnly, openWorld, idempotent) already covering safety, the description adds important behavioral context: the default model is free, bypassing an Anthropic key is optional and routes direct payment to Anthropic, and it discloses the return shape ({score, confidence, signals, raw_response}). This goes 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?

Three sentences efficiently cover function, default/cost behavior, return format, and use cases. No filler or redundancy; every clause adds value.

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

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

The description fully compensates for the lack of an output schema by detailing the per-model return structure and combined view. It also covers defaults, costs, and use cases, making it self-sufficient for a 4-parameter tool.

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

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

Schema description coverage is 100%, so all parameters are already well-explained. The description reinforces the relationship between _apiKey and models (BYO key) but adds no substantive semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Probe') and clearly states the resource (LLMs) and the output (visibility score 0-100 per model). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on what LLMs know about any entity, not just competitors.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which gives clear context. However, it does not mention alternatives or when not to use the tool, falling short of a full 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavioral context: routes to one of 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and is 'one fast call'. This goes well beyond the minimum and contradicts nothing.

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?

Though long, every sentence earns its place: it front-loads the directive ('PREFER OVER WEB SEARCH'), gives concrete examples, and then distinguishes sibling tools. The structure is logical and scannable, not padded.

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

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

Without an output schema, the description explains return format (structured answer with citation URIs) and covers scope, performance, and fallback options. For a tool covering 5,529 sources, this is a complete orientation.

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 clearly documents 'question' plus five aliases, so the description needn't add parameter details. The description doesn't provide additional semantics, but the schema already does the heavy lifting, making the baseline 3 appropriate.

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

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

The description explicitly states this tool answers factual questions by routing to authoritative structured data, with a clear verb+resource ('ask Pipeworx'). It also distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as different entry points for different needs.

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' (default start for most factual questions) and 'when not to use' (step up to grounded/deep_research for specific needs). It even gives example queries and names alternatives, satisfying the highest bar for usage guidance.

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

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

The description discloses the beta nature, the live enabling of candidate routing improvements, the current state of no active candidate, and that it falls back to nothing but is a full working router. This goes beyond annotations by explaining the experimental status and behavior, which is valuable for an agent deciding whether to use it.

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, starting with the core identity and then providing necessary details about current state and usage. Every sentence serves a purpose—clarifying what it is, its experimental nature, when to use it, and reassuring it is fully functional—without any redundancy.

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

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

Given this is a beta variant of an existing tool with no output schema, the description covers all essential aspects: the exact scope of the router, how it differs from the stable version, current activation status, and usage guidance. No critical information is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% with all six parameters being aliases for 'question', so the description adds little beyond what the schema already states. The mention of 'same arguments' as ask_pipeworx provides a cross-reference but no new semantic detail.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router handling 5,529 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by positioning itself as the experimental edge, 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?

It explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also mentions that results are compared against the stable router to decide merges, implying the stable alternative is ask_pipeworx. This provides clear usage context and an alternative.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that the tool extracts answers only from tool results, returns explicit refusals with specific reason codes, and costs an extra LLM call. This adds significant behavioral context that annotations do not cover.

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

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

The description is front-loaded with the core purpose and then provides structured details in a logical flow. While it is longer than average, each sentence adds value (routing, return format, usage policy, cost), and it remains readable.

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

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

Despite having no output schema, the description fully specifies the success and refusal return shapes, including fields and refusal reasons. It also covers performance cost and use cases, making it complete 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 describes the question parameter and aliases with 100% coverage, so the baseline is 3. The description adds overall context about how the question is used but does not provide additional parameter-specific semantics beyond what the schema offers.

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 leads with a specific verb phrase ('Hallucination-resistant answer mode') and explains the routing and extraction behavior, clearly distinguishing it from sibling ask_pipeworx by emphasizing groundedness and high-stakes use. It explicitly states the tool's role and differentiates from casual lookups.

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

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

The description explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and provides exclusions, recommending ask_pipeworx for casual lookups. It also names the cost trade-off (one extra LLM call), giving clear decision 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 read-only, non-destructive behavior, but the description adds extensive operational detail: fan-out patterns, resolver contracts, parent-event extraction, news fallback flags, low-confidence blocking, closed-market handling, and cancellation-rule risks. This far exceeds 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 very long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY) and front-loads the core purpose. Some redundancy exists, such as closed-market behavior being described in two places, but the density of actionable information 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 complex tool with no output schema, the description explains input variations, fan-out categories, response shapes, resolver confidence levels, safety statuses, tradeability warnings, and cancellation rules. It even covers edge cases like GDELT rate-limit fallbacks and void settlement mechanics, leaving no major 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?

Input schema has 100% coverage with clear descriptions for all three parameters, including market formats and enum options. The description largely echoes the market param format and adds little semantic value beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly identifies the action: research a Polymarket bet by aggregating Pipeworx data into an evidence packet and market-vs-model comparison. It specifies the resource (Polymarket markets), input formats, and concrete use cases like 'should I bet on X', distinguishing it from generic research tools.

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

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

Provides explicit use-case phrasing and practical guidance on when to trust results, including safety statuses and cancellation-rule caveats. It does not explicitly name alternative sibling tools or state when not to use this tool, so it falls just 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?

Despite annotations covering read-only/idempotent/non-destructive traits, the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), correct off-calendar fiscal year handling, sorting by primary metric, and returning paired data with citation URIs. No contradiction with annotations.

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

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

The description is dense and front-loaded with trigger phrases, but it is somewhat long with multiple examples and detailed notes. Each sentence provides value, though slightly verbose compared to the minimal ideal.

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

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

With no output schema, the description compensates by describing the return format (paired data + citation URIs), sorting behavior, and edge-case handling (fiscal years). It fully addresses the tool's complexity and expected usage.

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

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

While schema coverage is 100%, the description significantly enriches parameter meaning by detailing exactly what metrics are pulled for company vs. drug, how values are interpreted, and that results are sorted by primary metric. This goes well beyond the schema's enum and examples.

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: side-by-side comparison of 2–5 companies or drugs in one call, with specific trigger phrases. It distinguishes from siblings by emphasizing parallel comparison over sequential lookups and specifying the two entity 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?

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing direct when-to-use guidance. It also explains what each type pulls and notes it replaces 8–15 sequential lookups, making alternatives clear.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description adds substantial context: account/plan requirements, parallel decomposition into 5,529 tools, gap[] semantics with explicit 'never invented', expectation of 15-90s latency, citation_uri fetchability, and semantic excerpting. 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?

Though long, the description is dense and well-structured: every sentence adds behavioral detail, account requirements, alternatives, depth semantics, output format, and latency expectations without fluff. It is front-loaded with the most critical constraint (account required) and organized by topic.

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

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

With no output schema, the description fully describes the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop, citation_uri). It also covers limitations, use cases, fallback behavior, and performance expectations, making it complete for a complex research 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%, but the description adds significant meaning: it explains the depth=standard/thorough behavior (gap recovery, contradiction scanning, lead chasing), provides example questions for the question parameter, and clarifies that broad/multi-part questions are acceptable. This far exceeds the schema's enum text.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and clearly distinguishes itself from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and current-news topics. It also gives concrete examples of suitable vs unsuitable questions.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and uses ask_pipeworx if not signed in, leaving no ambiguity about alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond this: returns top-N tools with full schemas and curated examples, ready to call directly without a second schema lookup. This helps the agent understand the output and follow-up behavior without overstepping.

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 structured with an opening purpose statement, a usage-context sentence, and a return-behavior sentence. The long list of domains is somewhat verbose but directly aids the agent in deciding whether the tool applies to its task, so it 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 and a moderate number of parameters, the description covers the key contextual aspects: when to use, what it returns (top-N tools with schemas and examples), and how results are directly callable. It does not describe failure modes or missing result handling, but is otherwise sufficiently complete for this discovery tool.

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

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

Schema coverage is 100%, with clear descriptions for all six parameters including aliases and limits. The description adds no additional parameter-specific semantics, so it relies on the schema, which is the baseline. It does mention 'top-N' which aligns with the limit parameter, but without extra detail.

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 'Find tools by describing the data or task', clearly identifying a specific verb and resource. It distinguishes this meta-tool from its siblings by positioning it as the first step for browsing the available option set, and lists concrete example domains to reinforce its scope.

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

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

The description provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This makes it clear when to use this tool versus going directly to a specific sibling 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 read-only, open-world, idempotent, non-destructive. The description goes further by disclosing the parallel fan-out across multiple sources, the patent API sunset/soft-fail behavior, the GDELT→GNews fallback, and the exact return fields. This adds meaningful behavioral context beyond the annotations.

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

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

The description is dense and front-loaded with examples and the key "ALWAYS PREFER" instruction. It contains some redundancy (e.g., "full cross-source profile" and "fans out across" convey similar ideas) and is one long paragraph, but it remains information-dense with clear output structure.

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 enumerates all return components (cik, filings, fundamentals, patents, news, LEI) and their sources, including fallbacks and limitations. For a tool of this complexity, this is remarkably complete and leaves little ambiguity about what the agent will receive.

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

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

The schema already covers both parameters at 100% with descriptions, so baseline is 3. The description adds concrete examples ("AAPL", "0000320193"), reiterates the zero-padded CIK requirement, and clarifies the name limitation. These examples add practical value beyond the schema.

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

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

The description clearly states the tool's purpose: "full cross-source profile of a US public company" and provides multiple concrete invocation examples. It also differentiates from siblings by explicitly preferring over chaining single-pack lookups and pointing to resolve_entity for name-only queries.

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

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

Usage guidance is explicit: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also specifies what inputs are acceptable (ticker or CIK), that names are not supported, and directs users to resolve_entity as an alternative. This is strong when-to-use and 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 destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds 'previously stored' and the sensitive-data use case, but no additional behavioral details like error handling or confirmation output. With annotation coverage, this meets baseline but adds limited new info.

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 concise sentences: the first states the action, the second gives usage contexts, and the third references related tools. No fluffy or redundant content.

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

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

For a simple single-parameter delete tool with no output schema, the description covers purpose, usage contexts, and related tools. Annotations cover destructive and idempotent behavior, making it fully sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a clear parameter description ('Memory key to delete'). The description's 'by key' does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Delete' with a clear resource ('previously stored memory') and scope ('by key'), which distinguishes it from sibling tools like remember (store) and recall (retrieve).

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 the tool ('context is stale, the task is done, or clear sensitive data') and names companion tools ('Pair with remember and recall'), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral detail by explaining the workflow ('Fetches the page, extracts title/description/key links') and output format ('single text blob'), providing transparency beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded: the first sentence states the core action, the second explains the mechanism and output, and the final list gives practical use cases. No wasted words; every sentence contributes 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?

For a two-parameter tool with no output schema, the description fully covers what the agent needs: input URL, optional max_links, the process, output format, and practical scenarios. It avoids over-explaining and provides enough to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' well-documented. The description adds minimal new parameter semantics; it indirectly references URL and link count but does not elaborate beyond schema. Baseline of 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It further specifies the process (fetches, extracts, emits) and the output format, distinguishing it from generic tools. The use cases provided (client indexing, drafting, auditing competitors) reinforce its unique purpose.

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

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

The description gives clear context with three 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.' However, it does not explicitly mention alternatives or when not to use it, stopping short of a full when/when-not distinction.

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 safety is clear. The description adds only the word 'supported', implying a constraint, but does not disclose whether it returns all pairs or how pairs are structured. It neither contradicts nor significantly 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?

The description is extremely concise, using only five words. It avoids waste and is easy to parse, though it is arguably too terse to convey full 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?

Despite having an output schema and strong annotations, the description provides almost no context. It does not clarify the tool's role in glossary management, what a 'pair' means, or how it relates to sibling tools, leaving the agent without enough information to confidently select it.

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

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

The tool has zero parameters, so the description carries no parameter burden. Baseline 4 is appropriate for parameterless tools, even though the description adds no parameter-specific 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 names the resource 'glossary language pairs' but lacks an explicit verb like 'list' or 'return', making the action ambiguous. It does not distinguish itself from sibling tools such as source_languages or target_languages.

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. It does not mention use cases, context, or relationship to similar tools like source_languages or target_languages.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lowered. The description adds useful context beyond annotations by stating the return fields and that subscriptions are scoped to the caller. 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 two sentences, front-loaded with the core purpose, followed by return fields and usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose, returned fields, and use case. Complete enough for an agent to select and invoke it correctly without additional information.

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

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

The input schema fully covers the one parameter (include_inactive) with a clear description. The tool description does not add additional parameter-level meaning, but given the 100% schema coverage, 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 opens with a specific verb+resource ('List the caller's active subscriptions'), immediately distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates the returned fields, making the tool's purpose unmistakable.

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

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

The description provides clear context on when to use the tool: 'before adding more or to find an id to cancel.' This implicitly contrasts with subscribe/unsubscribe, though it does not explicitly name those alternatives. It offers strong situational guidance without formal exclusion conditions.

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 indicate write semantics (readOnlyHint=false) but description adds crucial behavioral context: claim_token return process for anonymous users, rate limiting (5/day), no quota impact, and the 'don't paste end-user prompts' instruction. This is exactly the kind of context beyond annotations that helps the agent.

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?

Front-loaded with purpose and usage, then structured details. Slightly long due to the necessary exclusions and token explanation, but every sentence contributes; no fluff.

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

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

Covers return behavior (claim_token), constraints (rate limit, quota), scope boundaries (only Pipeworx tools), and expected content (don't paste prompts). For a write-only feedback tool with no output schema, this is fully 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?

Despite 100% schema coverage, the description elevates parameter understanding by explaining claim_token usage with an explicit example (pipeworx_feedback({claim_token:'pwfb_…'})), and guiding context fields with 'describe in terms of Pipeworx tools/packs.' This adds real 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?

Description opens with a clear verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist'), immediately distinguishing it from sibling tools. It also enumerates feedback categories (bug, feature/data_gap, praise), leaving no ambiguity about the tool's function.

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 (bug, feature/data_gap, praise), when not to use (different MCP server), and provides fallback guidance for uncertainty. It even tells the agent to file with the other server, making exclusions precise.

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

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

Annotations already declare read-only/idempotent hints. The description adds behavioral context: self-aggregating signal derived from CF analytics-engine, no PII, cache freshness (5min-1h). This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with a list and a cache note; it is front-loaded with the main purpose and each clause contributes. It is slightly longer than necessary but well-structured and 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 simple read-only tool with one optional parameter and no output schema, the description covers return contents (top tools, top packs, total call volume), window choices, use cases, data source, privacy, and cache behavior. It is sufficiently complete for an agent to decide 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 provides 100% coverage for the single 'window' parameter with enum and a description of 24h/7d/30d semantics. The tool description only mentions the window options without adding meaning beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Returns') and identifies the resource (top tools, top packs, total call volume) with a time window, clearly distinguishing this from siblings like discover_tools or usage. It states exactly what the tool does without ambiguity.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs), giving clear context for when to invoke. It does not explicitly name alternatives or when-not-to-use, so it falls short of a 5.

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

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

Adds rich context beyond readOnlyHint/idempotentHint: explains the algorithm (monotonicity, partition checks), semantic similarity threshold (Jaccard ≥0.30), placeholder filter (>20% → null), and fill check vs live CLOB depth. 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?

Long but structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded mode guidance. Each paragraph earns its place, though it is dense; a slightly tighter draft could 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?

With no output schema, the description fully specifies response fields (opportunities[], partition_check) and trading caveats (thin legs, realizable vs theoretical edge). Covers edge cases like placeholder slugs and low similarity, making it self-sufficient.

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 describes both event and topic generically, but the description adds purpose-specific meaning: event walks child markets and checks ordering + partition sums; topic searches related events and flattens markets. Also clarifies the no-arg default behavior (trending_scan), which schema doesn't mention.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' clearly stating a specific verb, resource, and method. It distinguishes itself from siblings by detailing modes (trending_scan, event, topic) that tie to Polymarket's unique market structure.

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

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

Explicitly instructs when to call with no args vs event vs topic, recommending `event` for a specific market and `topic` for cross-event scanning. Names an alternative tool, polymarket_fill_risk, for custom sizing, and warns against trading when realizable_edge_pp ≤ 0.

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 readOnly/openWorld/idempotent, and the description goes well beyond them: 1-hour KV caching, diagnostics for empty segments, placeholder-slug filtering, Fed-signal unreliability, and the 24h-move warning. 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 long but exceptionally structured: SCREAMING CAPS group concepts, numbered families and segments organize complexity, and the purpose is front-loaded. It earns its length, though the density is slightly overwhelming for quick scanning, so not a 5.

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 the full burden of explaining responses. It enumerates top-level keys (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields, and why a segment might be empty—fully equipping an agent to understand return values and edge cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, especially the 'tradeable-edge knobs' paragraph explaining how min_liquidity/max_spread_pp drop opportunities and the nuance that min_kelly does not filter partition arbs because parent-level kelly is 0 by design.

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 and resource ('Scan top Polymarket markets') and clearly defines the tool's purpose: surfacing opportunities where Pipeworx data disagrees with market price. It then enumerates three distinct opportunity segments, distinguishing itself from broader market scan tools and siblings like polymarket_arbitrage.

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

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

It gives clear intended usage ('what should I bet on today') and explains that agents get opportunities without paging hundreds of markets. However, it never explicitly names sibling alternatives or states when not to use this tool, so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond the annotations, such as the 60-day snapshot TTL, the cache-miss behavior ('snapshots are written when polymarket_edges runs on a cache-miss'), and the distinction that decay numbers are based on daily closes, not intraday. It also explains the meaning of gaps in snapshot_dates. This is rich, non-obvious information that the annotations do not convey.

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

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

The description is dense but well-structured, starting with the core purpose, then the response format, and finally limitations. It is longer than average, but every sentence adds important context given the tool's complexity and lack of an output schema. A slight trim could make it more concise, but the structure is 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?

Since there is no output schema, the description takes on the full burden of explaining the return values. It thoroughly describes the response fields (tracked[], expired[], snapshot_dates[]), their meanings, and the limitations (TTL, gaps, non-intraday decay). This makes the description complete for practical use.

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

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

Schema description coverage is 100%, with both 'days' and 'window' already described in the input schema. The description's mention of 'Args: days (lookback, default 14, max 30), window (snapshot family, default "1wk")' essentially restates the schema's information without adding new semantic value. No additional meaning is provided beyond what the schema already contains.

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 with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges by focusing on time-series edge behavior.

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 on when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' This implies using the tool to check edge age and decay before trading. However, it does not explicitly name alternative tools or state exclusions, so it stops short of full 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?

Despite annotations indicating readOnly and idempotent behavior, the description adds crucial operational details: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and discloses the risk that partial basket fills convert an arb into an unhedged directional position. 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. It is well-structured with clear mode breakdowns (SINGLE-MARKET vs BASKET), explicit return-value lists, and a final usage directive. The format is dense yet scannable, with important warnings prominently stated.

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

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

Given the tool's complexity (two modes, no output schema), the description is remarkably complete. It lists all return fields for both modes, explains the real-world trading context (overround, underround, thin legs, forced directional risk), and provides actionable thresholds. There is no output schema, so this detailed narrative is essential and well-supplied.

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

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

Schema coverage is 100% with all 4 parameters described, but the description adds significant nuance beyond the schema: explains how size_usd is interpreted differently in single-market vs basket mode (max spend vs target proceeds vs settlement notional), details the default side behavior (auto from partition sum), and clarifies the range clamps. This is valuable semantic enrichment.

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: a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making its unique 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the difference between market and event modes, including default behaviors and when each is appropriate, and warns against theoretical overround on thin books.

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

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

The description goes far beyond the readOnly, idempotent, and non-destructive annotations by detailing compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the response structure. It explicitly cautions that pre-mapped topics are not necessarily tradeable, which is critical behavioral context for the agent.

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 and dense, but it is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence contributes substantive information, though some trimming could improve readability without losing critical 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?

Despite lacking an output schema, the description thoroughly explains the response format, including leg-by-leg prices, top_spreads_pp, and safety fields like compatibility_warning and temporal_alignment. It covers all three optional parameters and their interactions, making it complete for a complex cross-venue comparison 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?

With 100% schema coverage, the baseline is 3, but the description adds meaningful context by explaining the two operational modes and how explicit kalshi_event_ticker and polymarket_event_slug override topic mappings. It also clarifies the topic shortcut list and auto-fetch behavior, enhancing parameter semantics beyond the raw schema.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb and clear resource. It distinguishes itself from sibling tools by explicitly naming both venues and emphasizing equivalence of bet shapes, even describing when the spread is not a real signal.

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

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

The description clearly explains when to use the tool: to compare prices for the same question across Kalshi and Polymarket, and details two invocation modes (topic shortcuts vs explicit tickers/slugs). It also warns that most pre-mapped topics currently return compatibility warnings, which is useful guidance, though it does not explicitly name alternative tools or state 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?

Even though annotations already indicate read-only and idempotent, the description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the listing behavior when key is omitted. This goes beyond what annotations provide.

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

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

The description is three sentences and every sentence earns its place: purpose, usage context, and scope/relations. It is front-loaded with the main action, and there is no filler or repetition.

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

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

For a simple tool with one optional parameter and rich annotations, the description covers retrieval, listing, scoping, and sibling tool relationships. The return types are implied ('retrieve a value', 'list all saved keys'), making it sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples of key content (ticker, address, notes) which clarifies the semantics of the 'key' parameter beyond the schema's generic 'Memory key to retrieve'. It also restates the omission behavior, reinforcing the schema 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 uses a specific verb ('Retrieve') and resource ('value previously saved via remember'), and also describes the alternative behavior of listing all keys. It clearly distinguishes the tool from siblings by referencing remember and forget.

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 the tool: 'to look up context the agent stored earlier' and gives concrete examples (target ticker, address, notes). It also names the sibling tools to pair with ('Pair with remember to save, forget to delete'), providing clear alternatives.

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

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

The description explicitly describes mark_read:true as 'flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the annotations readOnlyHint=true and idempotentHint=true. Because the description contradicts the structured metadata, it earns a 1 and an annotation contradiction flag.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence adds useful information (return payload, filtering, mark_read behavior, polling, and alternative URL) without fluff or redundancy.

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

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

With no output schema, the description responsibly names the key return fields (source, citation_uri, raw payload). It also covers all important parameters (type, since, mark_read) and notes the alternate feed URL. It omits limit/unread_only, but those are fully documented in the input schema, so the description is nearly complete 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?

Schema coverage is 100%, so baseline is 3. The description adds extra value by giving a concrete example for type ('sec_8k') and explaining the behavioral effect of mark_read (next call only shows newer ones), which goes beyond the schema's parameter descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' giving a specific verb and resource. It clarifies it returns recent alerts written to the persisted feed, and the field list (source, citation_uri, raw payload) distinguishes it from sibling tools like recent_changes or list_subscriptions.

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

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

The description provides clear usage context: it's for retrieving subscription feed alerts, supports filtering, and notes that polling works fine. It also mentions an alternative HTTP endpoint for scripts/dashboards, but doesn't explicitly compare to sibling MCP tools or state when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds significant behavioral context: parallel execution, source fallback logic, PatentsView sunset soft-fail, and output structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is dense but every clause earns its place: use-case phrases, source fan-out, fallback behavior, parameter shorthand, return shape, and alternative tool. It is front-loaded with the primary purpose and gives operational details without fluff.

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

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

Despite having no output schema, the description explains what is returned (structured changes by source, total count, citation URIs) and the data sources involved. It covers limitations (USPTO soft-fail), parameter examples, and a sibling alternative, making the tool's behavior fully understandable.

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 describes all parameters thoroughly (including ISO/relative shorthand and examples). The description repeats this information without adding new parameter-level semantics beyond the broader context of the tool's behavior, so baseline 3 is appropriate.

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

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

The description clearly defines the tool as a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT→GNews, and USPTO in one parallel call. It includes concrete user intents and explicitly distinguishes itself from entity_profile, which provides a static profile.

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

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

Provides explicit when-to-use guidance via natural language examples ('What's new with X' etc.) and states the alternative 'Use entity_profile instead when you want the static profile'. It also explains fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and soft-fail conditions for USPTO, giving clear context.

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

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

The annotations already indicate this is a write (readOnlyHint=false) and idempotent tool. The description adds valuable context beyond annotations, including scoping by identifier, persistent vs. 24-hour retention for authenticated vs. anonymous sessions. It does not contradict the annotations and provides useful behavioral details, though some aspects (e.g., overwrite behavior) are not explicitly stated.

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

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

The description is concise and well-structured, front-loaded with the main purpose followed by usage context, storage details, and related tools. Every sentence adds value without redundancy, and the length is appropriate for the tool's simplicity.

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 two-parameter set operation, the description is fairly complete: it explains what, when, how, and persistence. It does not explain return values, but that is acceptable given no output schema and the tool's basic nature. Minor omissions like key size limits or overwrite semantics are not critical for a tool of this simplicity.

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 covers both parameters (key and value) with descriptive text and examples, achieving 100% coverage. The description adds little beyond the schema, merely restating that it stores a key-value pair. Per the rubric, high schema coverage warrants a baseline score of 3, and the description does not significantly enhance 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 saves data for later reuse, with a specific verb ('Save') and resource ('data'), and provides concrete examples (resolved ticker, target address). It distinguishes itself from sibling tools by mentioning the key-value pair mechanism and explicitly pairing with recall/forget, making its purpose unambiguous.

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

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

The description gives explicit guidance on when to use the tool ('Use when you discover something worth carrying forward... so you don't have to look it up again') and mentions the companion tools recall and forget. However, it does not explicitly state when not to use it or provide exclusions, so it stops short of 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses important behavioral traits: identifiers are labeled with their source, unresolved identifiers are explicitly stated under 'unresolved,' LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. This adds meaningful context beyond the annotations without contradicting them.

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

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

The description is long but well-structured and front-loaded with natural-language examples that immediately convey usage. Each section (examples, supported types, enrichment/degradation) earns its place, though the company-type detail is dense and could be tightened slightly. It remains appropriately sized for the tool's complexity.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. It adequately covers this by describing labeled identifiers, explicit unresolved items, and fallback behavior. For a two-parameter tool with rich domain logic, this is sufficient, though an explicit note about output shape (e.g., JSON format) would make it fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the richer semantics of each type: for 'company' it details the cross-source identity spine (CIK, ticker, LEI, FIGI) and for 'drug' it specifies RxCUI/ingredient/brand output. This goes beyond the schema's simple enum and value descriptions.

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

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

The description opens with concrete user queries and clearly states the tool 'resolv[es] a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes itself from siblings by naming the two supported types and noting it replaces manual lookups, 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 explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists supported input forms and types, providing clear context. However, it does not explicitly state when not to use it or name alternatives (e.g., entity_profile for richer details), 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it calls ai_visibility_check per entity, ranks results, and returns a structured list with score, confidence, and signal density. It does not disclose potential API costs or rate limits for the optional Anthropic model, but this is a minor gap given the annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, then explains the mechanism and output. Every sentence earns its place with no fluff or redundancy. It is concise yet information-dense.

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 (multi-entity probing, optional models, context disambiguation), the description covers the main purpose, behavior, and output format. It lacks an explicit output schema but compensates by describing the returned data ('ranked list with score, confidence, signal density per entity'). It could mention the optional Anthropic API key constraints, but the schema covers that, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description itself does not add meaningful parameter semantics beyond what the schema provides (e.g., it does not mention that the first entity is treated as the subject, though the schema says this). It mentions 'entities' implicitly but adds no extra detail. Therefore, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It then specifies the mechanism ('Probes each entity... with ai_visibility_check, ranks by score') and outputs ('Returns ranked list with score, confidence, signal density per entity'). This distinguishes it from the sibling tool ai_visibility_check, which presumably checks a single entity.

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 a specific use case ('competitive AI-marketing audits') and an example question, making it clear when to use this tool. It implies that this tool is for multi-entity comparison, while ai_visibility_check is for a single entity, but it does not explicitly state 'when not to use' or name alternative tools for single-entity checks. Thus it provides strong guidance but stops short of explicit 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 meaningful behavioral context: it fans out to external services, may take 5-30s for first bundlephobia measurement, and degrades gracefully with partial failures via the sources_failed field. This adds substantial value beyond the structured annotations.

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

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

The description is long but every sentence carries information: purpose, sources, use cases, return fields, ecosystem limitation, and failure behavior. It is well-structured and front-loaded, though slightly dense; a 4 reflects that it earns its length without being overly verbose.

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

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

With no output schema, the description fully explains return values (summary block, per-advisory detail, links, alternative versions) and covers latency, partial failures, and ecosystem scope. This is complete for the tool's complexity, leaving no major gaps for an agent to infer.

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

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

The schema already covers both parameters with clear descriptions (package name, version defaulting to latest). The description reinforces the npm ecosystem but does not add substantial new parameter semantics. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check combining deps.dev and bundlephobia data. It specifies the exact sources (deps.dev, bundlephobia) and the output fields, making it distinct 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states when NOT to use it (non-NPM packages fall under deps.dev directly), giving clear exclusions and alternative paths.

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 signal read-only, idempotent, non-destructive behavior, but the description adds concrete behavioral details: character offsets and similarity scores, BGE-base-en embeddings with cosine over 500-char overlapping windows, and the 200K char cap with truncation flag. 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?

Four sentences with front-loaded purpose, then usage, sibling pairing, and technical constraints. Every sentence earns its place; no filler or redundant restating of annotations.

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

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

For a tool with no output schema, the description fully explains return contents (passages, offsets, similarity scores), constraints (500-char windows, 200K cap), and its role in the grounded-QA pipeline. Combined with the rich annotations, the context is complete.

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

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

Schema covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces the semantics ('text you already pulled', 'natural-language query') and provides examples, but does not add new parameter-level meaning beyond what the schema already documents.

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

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

The description names a specific verb ('semantic search INSIDE a fetched record'), identifies the resource (the text the user passes in), and distinguishes itself from siblings by contrasting with ask_pipeworx_grounded and focusing on returning passages rather than whole-document Q&A.

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 when the record is too big to cram into the prompt'), explains the benefit (saves context, returns only passages that matter), and names the alternative workflow (pairs with ask_pipeworx_grounded). This gives clear, actionable usage guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety traits. The description adds minimal behavioral context ('supported' implies a canonical set), but does not disclose any additional traits such as pagination, static vs dynamic data, or relationship to other tools. With annotations present, the bar is lower, and this meets a baseline level.

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 an extremely short, front-loaded phrase with no wasted words. Every word contributes to the meaning, making it a model of conciseness.

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

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

Given the tool's simplicity (0 params, output schema present, annotations present), the description is minimally adequate. However, it lacks any mention of how this tool relates to 'target_languages' or 'translate', and does not clarify whether the list is static or dynamic. An agent might need more context to confidently select it.

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

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

The tool has zero parameters, so there is no parameter documentation burden. According to the rubric, a baseline of 4 is appropriate when there are no parameters, as the description cannot add value beyond that point.

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 'Supported source languages' is a noun phrase rather than a sentence with a verb, making it vague about what the tool does (list? get? set?). It adds the word 'supported' to the title, which slightly clarifies that it returns a set of allowable languages, but it does not explicitly state an operation or differentiate itself from the sibling tool 'target_languages' beyond the word 'source'.

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 no guidance on when to use this tool versus alternatives like 'target_languages' or 'translate'. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.

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 supply safety hints (readOnly=false, openWorld=true, idempotent=true, destructive=false), but the description adds substantial behavioral depth: OAuth account requirement, always-on feed, SMS 10/day cap, phone verification, webhook signing secret returned once, and auto-disabling after 10 consecutive failures. This goes far beyond the annotations without contradicting them.

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

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

The description is long but densely informative, with clear internal structure ('Supported types:' and 'Delivery channels:'). The length is justified by the complexity of five subscription types and three delivery channels, though the delivery section partially repeats schema descriptions. Front-loading the core purpose and prerequisites makes it efficient 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?

Given the tool's complexity (3 params, nested objects, 5 types, 3 delivery options), the description is highly complete: it covers prerequisites, return value, per-type parameters, delivery behavior, limits, verification steps, webhook signing, and failure handling. The absence of an output schema is compensated by explicitly stating the returned subscription id.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema: concrete examples for each subscription type, item code semantics (e.g., '5.02' = officer change), minimum spread example for polymarket_edge, sponsor/condition requirements for clinical_trial, and delivery-channel caveats like phone verification and webhook signing secret. This is a high-value addition, not mere repetition.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the return value (new subscription id) and differentiates from siblings like list_subscriptions, unsubscribe, and recent_alerts by emphasizing proactive, persistent subscription creation.

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 this tool: when persistent, proactive alerting is needed, and it explicitly states a prerequisite (Pipeworx OAuth account required; anonymous/BYO cannot persist). It does not explicitly name alternative tools or state when not to use it, but the proactive vs. reactive distinction is strongly implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds meaningful behavioral context beyond annotations: it describes the return structure (category-bucketed example questions with tool + argument shape), the effect of the topic parameter, and its role as a live catalog lookup. 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 longer than typical but well-structured: it opens with user-intent phrases, then states purpose, return content, and usage. Every sentence adds value, though some repetition of schema information slightly reduces conciseness.

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

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

Given no output schema, the description explains return values (category-bucketed example questions with tool+argument shapes) and distinguishes between no-arg and topic-arg behavior. It also situates the tool correctly relative to siblings. Minor omissions like error handling or exact category list are not critical for its purpose.

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

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

Schema description coverage is 100% for the only parameter, topic, which already lists valid values and the omit behavior. The description reinforces this with examples but adds no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that suggests example questions, category-bucketed, each paired with the exact tool and argument shape. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying its role as a suggestion/discovery tool.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives (meta-tools). It also explains how to invoke it with or without the topic parameter. It does not explicitly state when not to use it, but the 'FIRST' directive and mention of meta-tools provide strong contextual 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the annotations—it does not disclose what the tool returns, whether the list is dynamic, or what format the output takes. No contradiction exists.

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

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

At three words, the description is technically concise but severely under-specified. It is a fragment rather than a functional sentence, sacrificing substance for brevity. This is under-specification, not effective conciseness.

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

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

Despite having an output schema and read-only annotations, the tool requires at least a semantic hint about what 'target languages' means (e.g., languages that can be translated into). The description provides no such context, leaving the agent to guess the tool's purpose and expected output.

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, and the schema's properties are empty. With no parameters to explain, the baseline is 4. The description adds no param semantics, but none are needed.

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 'Supported target languages' is essentially a restatement of the tool name with the adjective 'supported' added. It lacks a verb or explicit action (e.g., 'List' or 'Get'), making the purpose vague and not clearly differentiated from sibling tools like source_languages.

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 provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The description is a bare noun phrase, leaving the agent without any direction on invocation.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, which covers the safety profile. The description adds return value details and parameter behaviors, but does not disclose additional traits like rate limits or error handling. This is acceptable but not exceptionally transparent.

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

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

The description is concise, with two sentences each earning their place. It front-loads the main function and then packs requirements and options 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?

Given 12 parameters and low schema coverage, the description handles the core workflow well but omits several optional parameters. The output schema covers return values, so that aspect is complete, but the full parameter space is not fully explained.

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

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

With 8% schema coverage, the description compensates by explaining core parameters (text, target_lang, formality, etc.) and providing examples. However, many advanced parameters (ignore_tags, splitting_tags, preserve_formatting) are left undocumented, creating a gap for agents.

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 specifies the action ('Translate') and the resource ('one or more text strings using DeepL'), distinguishing it from sibling tools like source_languages/target_languages which list languages rather than translate. It is specific and unambiguous.

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

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

The description provides clear context for when to use the tool (translating text) and outlines required and optional parameters. However, it does not offer explicit alternatives or when-not-to-use guidance, so it stops short of a 5.

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

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

The description goes beyond annotations by explaining the exact behavioral effects: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This adds context about data preservation that the annotations alone do not convey, and it aligns with the idempotent and non-destructive 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 two sentences long and front-loaded with the core action. Every sentence provides value: the first states the operation, the second explains constraints and side effects. No filler or unnecessary information.

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

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

For a simple tool with one parameter and annotations, the description covers the essential aspects: purpose, ownership, and the deactivation behavior. It does not mention return values or error scenarios, but these are less critical given the clarity and the existing schema/annotations. It is adequately complete for its complexity.

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

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

The input schema already fully describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' with 100% coverage. The description only repeats 'by id' without adding new semantics. The schema carries the load, so the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It is specific with a verb and resource, and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by the cancel action. The title also reinforces the purpose.

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

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

The description provides clear context for usage, including ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive nature compared to deletion. It implicitly tells the user they should have a subscription first, but does not explicitly mention alternatives like 'list_subscriptions' to find the id. Still, it offers enough guidance for selecting 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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the temporal scope (current month) and the fact that limits are included, but it does not disclose any further behavioral traits such as rate limits, authentication requirements, or what 'usage' refers to. Given the strong annotation coverage, this is acceptable but minimal.

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 exceptionally concise, consisting of a single fragment 'Current month's usage + limits.' It contains no filler or redundant information, and it is directly front-loaded. Every word carries 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?

Given the tool has no parameters and an output schema exists, the description does not need to explain return values. However, it lacks context about what resource the usage applies to (e.g., API calls, storage, subscription limits). It is minimally viable but could be clearer by stating the domain or user scope.

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 baseline is 4. The description does not need to explain parameter semantics, and the schema (empty properties) fully covers the input side. No additional description is necessary.

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 'Current month's usage + limits.' clearly identifies the tool's subject matter (usage and limits for the current month) without a verb, but it conveys the resource and scope. It is clear enough to distinguish itself from tools like 'list_subscriptions' or 'discover_tools', though it does not explicitly name the resource type it covers.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or alternative tools. The intended usage is vaguely implied by the name and description, but there is no explicit direction.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses critical behavior: the SEC/XBRL fast path vs grounded fallback, the exact verdict list, the meaning of could_not_verify (not evidence) vs unsupported, and the tolerance override logic. This is far more transparent than annotations alone.

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?

Though long, every sentence earns its place: trigger examples, routing, return values, error semantics, and usage guidance. The structure is front-loaded with purpose and examples, and the IMPORTANT callout for could_not_verify is clearly separated.

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 carries full responsibility for explaining return values. It does this thoroughly: verdict list, actual value with citation, reasoning, and edge cases (could_not_verify, unsupported). This is complete for a complex tool with two distinct pipelines.

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 adds practical guidance on tolerance_pct (set 1–2 for hallucination detection, default capped at 5), which goes beyond the schema's static description and is genuinely useful for invocation.

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

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

The description explicitly states the tool's function: natural-language claim verification against authoritative sources, with concrete trigger phrases. It clearly distinguishes from siblings by focusing on fact-checking, and details the two routing paths (SEC/XBRL for company-financial claims vs grounded pipeline for any other claim).

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains this tool replaces 4–6 sequential calls, giving an alternative approach. It further instructs how to interpret could_not_verify vs unsupported, preventing misuse.

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