Bioregistry

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. Description adds that default model is Workers AI Llama-3.3-70b (free) and Anthropic requires a BYO API key, plus it outlines the return structure (per-model score, confidence, signals, raw_response) and combined view. No contradictions with annotations.

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

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

Three sentences efficiently cover purpose, usage details, and return format. Front-loaded with key action and score range, no redundant information.

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

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

Given 4 parameters with full schema coverage and no output schema, the description adequately explains return structure and use cases. Could mention potential errors or rate limits, but overall 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%, but description adds context beyond parameter descriptions: default model, that _apiKey is passed straight through, and that context helps disambiguate. This adds meaningful value for agent selection.

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 states tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It specifies the default model and optional Anthropic integration, distinguishing it from siblings like scan_competitor_ai_presence which likely focus on competitive analysis rather than general visibility.

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 use cases are given (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, no explicit mention of when not to use or alternatives like scan_competitor_ai_presence, which could be relevant for competitive analysis specifically.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it routes across many sources, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a fast single call. It does not discuss failure modes or rate limits, but the added context is meaningful.

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 most important instruction ('PREFER OVER WEB SEARCH') followed by the core routing behavior. The list of examples and escalation guidance is somewhat long but each part serves a distinct purpose: specifying inputs, illustrating coverage, and differentiating from alternatives. Deliberately repetitive phrasing like 'START HERE' reinforces priority without being wasteful.

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 broad router nature and the absence of an output schema, the description is remarkably complete. It covers the supported domains, the expected behavior (rerouting, argument filling, citation URIs), the relationship to sibling tools, and real-world example queries. The agent receives enough context to know exactly when and how to invoke this tool.

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

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

The input schema covers all six parameters with descriptions and aliases, so schema description coverage is 100%. The description adds example queries and states that the parameter is a natural-language question, but does not introduce new parameter-level semantics beyond what the schema already provides. This matches the baseline for high schema coverage.

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

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

The description clearly states that ask_pipeworx routes factual questions to the appropriate tool from 5,529 tools and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default, faster entry point.

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

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

The description gives explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'find'), and explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE'. It also names concrete alternatives and when to step up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions), making the escalation path 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 provide read-only, idempotent, open-world hints. The description adds crucial context: candidate routing improvements may be enabled live, no candidate is currently active (retired on 2026-07-26), and despite being experimental, it is a full working router with no fallback. 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 slightly long but every sentence carries useful information: status, usage, comparison with stable, and reassurance. It is well-structured and front-loaded with the core purpose.

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 annotations and schema, plus the mention of identical response shape to ask_pipeworx, the description is fairly complete. It explains current experimental status, usage, and fallback behavior. A minor gap is the lack of explicit response format, but referencing the sibling fills that.

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

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

Schema description coverage is 100%, with each of the six parameters explicitly described as an alias for 'question'. The description does not need to add parameter details; the schema fully handles it, so the baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, functioning as an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by being an experimental edge, making its purpose unambiguous.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It also notes that currently no candidate is active, so it matches ask_pipeworx exactly, giving clear when-to-use guidance.

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

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

The description discloses detailed behavioral traits beyond annotations: returns evidence as verbatim quotes, provides structured refusal reasons, limits answer extraction to tool result content, and costs an extra LLM call. This adds significant context that annotations (readOnlyHint, openWorldHint, idempotentHint) 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 well-structured and front-loaded with the core purpose. Every sentence adds value: purpose, routing/process, return format, refusal format, use cases, and cost comparison. Despite length, it is efficient and packed with necessary details.

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

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

Given no output schema and complex behavior, the description fully explains return values, refusal reasons, and the grounded extraction constraint. It covers routing details, source count, and operational trade-offs, making it self-sufficient without needing to reference external documentation.

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% (all parameter aliases documented). The description does not add parameter-specific semantics beyond the schema; it focuses on overall tool behavior. Since the schema already explains parameters, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies the process (routing, fetching, extracting from tool result only) and distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusal 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?

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on, and when facts must not be invented. It also notes cost trade-off and explicitly say to prefer ask_pipeworx for casual lookups, naming the 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, idempotent), the description discloses extensive behavioral traits: market resolution, classification, fan-out to data packs, safety checks (low-confidence short-circuit, closed markets, illiquid spread), response shapes, and error handling. Adds significant context.

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

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

The description is verbose but front-loaded with the basic purpose and all paragraphs add necessary detail. Could be slightly more concise, but no redundancy.

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

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

Without an output schema, the description extensively details the output structure (market, analysis, evidence, resolver contract, news fields). Covers safety, edge cases, and error states. Highly complete for a complex 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 meaning beyond schema by explaining the depth parameter's default, include_raw's recommendation, and the market parameter's acceptable formats. Provides actionable context beyond enum descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output structure (evidence packet + comparison). The purpose is specific and distinct from sibling tools 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?

The description explicitly says 'Use for "should I bet on X"...' providing clear usage guidance. It does not explicitly mention when not to use or alternatives, but the context of sibling tools implies differentiation.

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=true, openWorldHint=true, and idempotentHint=true. The description adds significant behavioral context: data sources (SEC EDGAR for company financials, FAERS for drug metrics), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). It does not discuss error handling or rate limits, but the added detail exceeds 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 front-loaded with a block of example queries that quickly communicate the tool's purpose. Every subsequent sentence adds value (sources, sorting, output format). It is relatively dense but not bloated; minor redundancy exists (e.g., 'side-by-side' and 'ONE parallel call' could be tighter). Overall well-structured and economical.

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

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

The description covers entity types, data sources, sorting, and output format sufficiently for an AI agent to select and invoke the tool correctly. It does not mention pagination, time range for FAERS data, or potential limits (e.g., max 5 entities). However, given the tool's moderate complexity and the presence of annotations, the description is nearly complete—missing only minor operational details.

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 enums and constraints. The description adds rich semantics: for 'type=company' it specifies the exact data points pulled (revenue, net income, cash, long-term debt) and notes correct fiscal-year handling; for 'type=drug' it lists adverse-event counts, FDA approvals, and active trials. Examples like 'AAPL', 'MSFT' and 'ozempic', 'mounjaro' clarify valid values. This fully compensates for any schema minimalism.

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

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

The description opens with concrete example queries ('compare X and Y', 'X vs Y') and clearly states the core function: 'side-by-side comparison of 2-5 companies or drugs in ONE parallel call'. It distinguishes from sequential lookups, making the purpose unmistakable and differentiated from siblings.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also gives example patterns ('which is bigger', 'rank these companies') and contrasts with sequential lookups, leaving no ambiguity about the tool's intended use case.

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. The description goes far beyond by disclosing the account/paid-plan requirement, latency (15-60s, up to 90s), the decomposition and parallel-tool-routing behavior, the return packet structure (evidence, confidence, gaps[], contradictions[], hop field, citation_uri), and the 'never invented' policy. It also notes exact conditions for gap results. This is rich 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 the most critical operational context (account requirement and alternative tool). Every section adds value, but it is long and could potentially be tightened. It is appropriately sized for the tool's complexity, but slightly over-explains some details that could be condensed.

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 takes on the full burden of describing the return value: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx citation, gaps[], contradictions[], hop field, and citation_uri. It also explains failure modes (empty gaps when topic not in catalog), record excerpting, and expected latency. Nothing critical is missing.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds meaning beyond the schema: it explains depth levels in terms of facet counts, paid status for 'thorough', and the gap-recovery/iteration behavior. It also gives examples and notes that broad/multi-part questions are acceptable. This enhances but does not drastically exceed the schema's adequate 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 clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call', and explicitly distinguishes it from open-web search and from the ask_pipeworx sibling. It uses a specific verb ('research') with a clear resource (structured data sources) and differentiates itself from alternatives.

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 provides usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. These are clear when-to-use and when-not-to-use instructions with named 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?

Description adds behavioral context beyond annotations: returns top-N tools with full schemas and curated examples, no second lookup needed. Annotations already indicate read-only, idempotent, non-destructive.

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 concise sentences with no redundancy: core action, example domains, return value, usage advice. Front-loaded with the key action.

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

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

Covers purpose, return value, and when to use. Lacks details on edge cases (empty query) but sufficient for most scenarios given the tool's 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?

Schema has 100% description coverage; description mentions query aliases but does not add new semantic 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?

Clearly states verb ('Find tools by describing the data or task') and distinguishes from siblings by focusing on discovery vs. direct answers. Lists specific domains, making it easy to understand the tool's 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?

Explicitly says 'Call this FIRST' and contrasts with getting a single answer. Provides when-not guidance implicitly by focusing on browsing rather than direct actions.

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

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

Annotations already indicate readOnly and idempotent hints. The description adds behavioral details: the tool fans out across multiple sources, mentions the USPTO API sunset soft-fail, and lists specific return fields, enhancing transparency beyond annotations.

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

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

The description is front-loaded with purpose and examples. It packs substantial information without being overly verbose. Minor room for structuring with bullet points, but overall each sentence earns its place.

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

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

Given the tool's complexity (multiple sources, fallbacks, return fields) and lack of output schema, the description thoroughly explains what the tool returns (CIK, filings, fundamentals, patents, news, LEI). No gaps in understanding what to expect.

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

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

Schema coverage is 100%, but the description reinforces and extends it by explaining parameter meaning with examples (e.g., ticker or CIK) and explicitly stating that names are not supported. This adds significant value for correct parameter usage.

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 in ONE parallel call.' It provides example queries and specifies the resources it covers, distinguishing it from sibling tools like resolve_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 explicitly advises preference over chaining single-pack lookups for holistic views and warns that names are not supported, directing users to resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Description includes usage rationale (clearing stale/sensitive data) beyond annotations. Annotations already mark destructiveHint=true, description confirms but adds context. No contradictions.

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

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

Two sentences: one for action, one for usage guidance. No wasted words, efficiently conveys all necessary 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?

Simple tool with one required parameter; description explains purpose, usage context, and connections to sibling tools. Fully 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?

Schema coverage is 100% with clear description of 'key' parameter. Description does not add extra meaning beyond what schema provides.

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

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

Clearly states 'Delete a previously stored memory by key.' Uses specific verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember and recall' as 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, idempotentHint, and destructiveHint false, indicating safe, non-destructive behavior. The description adds behavioral details: fetches the page, extracts title/description/key links, emits standard llms.txt markdown. It does not contradict annotations and provides valuable process context.

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

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

Description is concise: a single paragraph with front-loaded main purpose, followed by process summary and use cases. Every sentence adds value, no fluff. It efficiently covers what, how, and why.

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 simplicity (2 params, no output schema), the description covers core functionality: input URL, optional max_links, extraction process, output format and location. It does not address error cases or rate limits but is complete enough for typical 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%, so baseline is 3. The description does not add parameter details beyond what the schema provides, but the overall context helps. Since the schema already describes both parameters well, the description adds no extra semantic value.

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 states the tool generates a production-ready llms.txt file for any URL, specifying verb (generate), resource (llms.txt file), and scope (for any URL). It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on the llms.txt file generation.

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?

Description provides explicit use cases: indexing a client's site, drafting for own project, auditing competitor. It implicitly tells when to use it but does not explicitly state when not to use or compare to alternatives. However, the context is clear and the use cases are well-defined.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds the return fields and the option to include inactive subscriptions, providing complementary context without contradiction.

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

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

Two sentences, front-loaded with the main purpose, no wasted words. Every sentence adds value.

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

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

Covers purpose, usage, return fields, and parameter option. Lacks mention of pagination or ordering, but given the tool's simplicity, the description is mostly 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%. The description does not add further meaning to the 'include_inactive' parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe by mentioning usage context.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses several behavioral traits beyond the annotations: returns a claim_token when filing without an account, can be used later with claim_token to read status, rate-limited to 5 per day, free, doesn't count against quota, and team reads digests daily. Annotations only provide hints (all false), so the description carries the full burden and does so admirably.

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

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

The description is a single dense paragraph, but every sentence carries unique information. It is front-loaded with the core purpose and then expands into usage rules, mechanics, and constraints. While long, it avoids fluff; the structure could be tightened with bullets but remains highly scannable.

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

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

Given the lack of an output schema, the description thoroughly explains what happens after filing (claim_token, later status reads) and covers edge cases (other servers, unsure identification). It also details the freedom from quota and daily digest processing. This is complete for a feedback submission tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics on top: explains the claim_token round-trip usage, advises not to paste end-user prompts, and contextualizes the type field with real-world examples. It doesn't rehash schema definitions but supplements them, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes it from sibling tools like ask_pipeworx (which asks questions) and discover_tools (which lists tools). The purpose is 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?

Explicitly states when to use (bug, feature/data_gap, praise) and when NOT to use (if the tool came from a different MCP server, file it there instead). Even provides a heuristic for disambiguation: 'Pipeworx tool names are the ones this connection lists.' This is textbook usage guidance with 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: data source ('CF analytics-engine'), no PII, caching behavior ('5min-1h depending on window'). 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 concise (three sentences) and front-loaded with the primary result, followed by use cases and technical details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully covers return values, use cases, data source, and caching. No gaps in context.

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

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

Schema coverage is 100% with an enum parameter described. The description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the schema's enum descriptions.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' using a specific verb 'Returns' and specifies the resource ('what other AI agents are calling on Pipeworx right now'). It is unambiguous and distinct from siblings.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tool, checking alignment). It does not explicitly mention when not to use it or alternatives, but the provided use cases are clear and actionable.

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

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

Discloses behavioral traits beyond annotations: Jaccard similarity threshold (≥0.30), placeholder fraction filter (>20% → null), fill check against live CLOB depth, and output structure. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is thorough but slightly verbose. Every sentence adds value, and it is well-structured with sections for modes, semantic anchor, partition filter, fill check. Could be tightened slightly, but no unnecessary 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 no output schema, the description details the response fields (opportunities[], partition_check, fill check results). Covers edge cases like skipped_low_similarity, placeholder filtering, and references related tool for custom sizing. Highly complete for a complex 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 two parameters. Description adds extensive meaning: explains modes, example slugs, internal processing (walks child markets, partition checks, semantic anchor), and cross-event behavior. Complements schema effectively.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique mechanism and modes (event and topic). Examples of usage are provided.

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 guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event for strongest partition check. Also warns when not to trade (realizable_edge_pp ≤ 0) and points to polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnly and idempotent. The description adds extensive behavioral context: caching (1h at KV level), response structure with diagnostics, and details on each segment's logic (e.g., placeholder-slug filters, Fed bets note). 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 well-structured with bullet points and clear sections. Every sentence adds value, though it could be slightly condensed without losing meaning.

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

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

Given the complexity (9 parameters, no output schema, nested response), the description is extremely thorough. It explains all three segments, diagnostics, Fed bets note, caching, and parameter behavior, making it self-contained.

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 detailed descriptions. The main description adds rationale for parameters like 'tradeable-edge knobs' and explains concepts like min_kelly and min_partition_leg_kelly, enhancing understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies three model families and segments, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 is built for 'what should I bet on today' and mentions agents can discover opportunities without paging hundreds of markets. It provides clear context but does not explicitly compare to sibling tools or state when not to use.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds rich behavioral context: reads from daily snapshots, provides time-series, trend, decay, expired opportunities, and snapshot availability. Discloses limitations (TTL, decay computation). No contradictions.

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

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

Description is detailed but well-structured: starting with a one-sentence summary, followed by response fields and limitations. Every sentence adds value, though slightly verbose. Could be tightened, but remains clear and front-loaded.

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

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

Given no output schema, the description fully explains the three response arrays (tracked, expired, snapshot_dates) and their fields. Covers limits (TTL, decay computation). Adequate for a complex time-series tool, though error cases are not mentioned.

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 described. Description adds meaning: clarifies default and max for days, lists window options (24hr, 1wk, 1mo) and explains they are snapshot families. Provides context on how parameters affect the response.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' Distinguishes itself from sibling polymarket_edges by focusing on time-series analysis rather than raw edge data.

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

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

Explains when to use (to differentiate between a fresh wide edge and an old wide edge) and lists limitations (60-day TTL, decay from daily closes). Lacks explicit alternatives among siblings, but context is sufficient for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructiveHint, so the safety profile is covered. The description adds significant behavioral context beyond this: it walks the order book ladder, returns specific fields like slippage, and highlights the risk of forced directional risk in basket mode. It also explains the interpretation of size_usd differently for buys vs sells. This is comprehensive but the annotation coverage reduces the burden somewhat.

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 well-structured with clear sections for single-market and basket modes, and a concluding usage note. It's front-loaded with the core purpose. However, it is somewhat verbose; some details (like default values) could be left to the schema. The length is justified by the tool's complexity, but it could be trimmed slightly without losing meaning.

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

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

Given no output schema, the description comprehensively lists all return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It explains the verdict categories and the risks of partial fills. The description is complete for the tool's complexity (4 parameters, two modes), with no apparent gaps. It even includes domain-specific guidance about the dominant loss mode in arb-bot P&L.

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

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

Schema description coverage is 100%, but the description adds important semantic details: it explains how side defaults differ between single-market and basket modes, and how size_usd is interpreted (spend vs proceeds vs settlement notional). For the event parameter, it clarifies it triggers basket mode and checks every leg. This goes beyond the schema descriptions, making the parameters clearer.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, stating when to use this tool (before acting on those signals) and when not to (small trades).

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

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

The description provides explicit usage conditions: 'REQUIRES one of market or event', and explains the two modes. It gives clear guidance on when to use the tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and warns against partial fills converting arb into unhedged positions, effectively stating when not to use. This provides excellent context for agent decision-making.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds detailed behavioral context: two modes, response fields (leg-by-leg prices, top spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains when spreads are meaningful vs not. No contradictions with annotations.

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

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

The description is relatively long but well-structured with section headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads key information. Every sentence adds value, though some redundancy (e.g., repeated warnings) could be trimmed without loss.

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 venues, two modes, safety fields, no output schema), the description is highly complete: it explains modes, response format, safety fields, temporal alignment, and edge cases like non-equivalent bet shapes. It even warns about the rarity of real spreads, providing comprehensive context.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining override behavior (explicit parameters override topic-mapped sides) and listing allowed topic values with usage context, which aids correct 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 clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the response structure, making the purpose specific and well-defined.

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

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

The description provides explicit guidance on when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility warnings, setting accurate expectations for the agent about when real spreads exist.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context about what metadata is returned (canonical URI pattern, synonyms, homepage, cross-registry mappings), which goes 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?

Single sentence, no filler, includes key details upfront. Every word adds value, making it efficient and easy to parse.

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

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

Given the single parameter, rich annotations, and presence of an output schema, the description covers all essential aspects. No gaps in explaining what the tool does or returns.

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 well-described string parameter and examples. The description adds the biological database context but no additional syntax or format details beyond the schema, meeting the baseline for high-coverage schemas.

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 states the action ('Fetch'), the resource ('full Bioregistry metadata for a biological database prefix'), and provides two concrete examples. This distinguishes it from the sibling tool 'prefixes' which likely returns a list, making 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?

Implicitly differentiates from sibling 'prefixes' by focusing on a single prefix. No explicit when-not or alternatives, but the context is clear enough for an AI agent to infer the right scenario.

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

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

Annotations already indicate safety (readOnlyHint, destructiveHint) and idempotency. The description adds that it returns full records and requires pagination, which is valuable context beyond annotations.

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

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

Two concise sentences: first states purpose and content, second explains usage. No fluff, front-loaded with key information.

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

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

Given the tool is a paginated list with an output schema that likely describes the record structure, the description provides sufficient context (scope, content, pagination mechanism). Number of entries (2,000+) sets expectations.

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

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

Schema coverage is 0%, so the burden falls on the description. It mentions limit/offset for pagination but lacks details like default values or behavior. Examples in schema provide some guidance, but the description could be more explicit.

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

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

The description clearly states the tool paginates over all registered Bioregistry prefixes (2,000+) and returns full prefix records, distinguishing it from the sibling tool 'prefix' which likely fetches a single entry.

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 using limit/offset for pagination, and the sibling 'prefix' implies when a single prefix is needed. Lacks an explicit when-not-to-use statement, but the context is 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 indicate this is a safe, read-only, idempotent operation. The description adds behavioral details: 'Scoped to your identifier' and 'omit the key argument to list all keys', which complements the annotations without contradiction.

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

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

The description is two sentences long, front-loads the core purpose, and contains no unnecessary words. Every sentence adds value.

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

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

For a simple retrieval tool with one optional parameter and comprehensive annotations, the description covers purpose, usage, scoping, and pairing with siblings. It does not detail return format, but no output schema exists, so this is acceptable.

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 is fully documented (100% coverage), so baseline is 3. The description adds value by explaining that omitting the key lists all keys, which is not fully captured by the schema's 'optional' indication.

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: retrieve a saved value or list all keys. It uses specific verbs like 'retrieve' and 'list', and clearly distinguishes from sibling tools 'remember' and 'forget' by mentioning them.

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 specifies when to use the tool ('to look up context the agent stored earlier') and mentions scoping and pairing with 'remember' and 'forget'. It does not explicitly state when not to use it or list alternatives, but the context is 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 mark it read-only, but the description discloses that mark_read can mutate read state—a critical behavior beyond annotations. No contradictions, but the description adds needed context.

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

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

The description is a single paragraph of four sentences, front-loading key information. The alternative endpoint mention is slightly extraneous but doesn't harm 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 no output schema, the description covers return fields (source, citation_uri, payload) and filter options. It doesn't explain limit or unread_only in text, but schema covers them. Overall sufficiently 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?

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining mark_read semantics (flagging events as read), which isn't fully captured in the schema, and reinforces filter usage.

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 pulls fired events from a subscription feed, specifying the resource (alerts) and action (return). It distinguishes from siblings like list_subscriptions and recent_changes by focusing on alert events with filter options.

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 filter usage (type, since), explains mark_read behavior, and notes polling safety. It lacks explicit when-not advice but implies alternatives via the REST endpoint mention.

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 significant context beyond annotations: fans out to multiple sources, explains fallback logic, soft-fail for USPTO, and return structure with citation URIs. Annotations already indicate read-only, idempotent, non-destructive.

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?

Dense but well-organized with examples, fallback details, and return structure. Every sentence adds value; no wasted text.

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?

Completely describes the tool's multi-source aggregation, fallback behaviors, soft-fail, and return format (changes grouped by source, total_changes count, pipeworx:// URIs) despite no output schema.

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 descriptions are present for all parameters (100% coverage). Description reinforces 'since' with examples and typical usage value ('30d' or '1m'). Adds clarity but schema already does 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 it provides a change feed for a company, covering SEC filings, news, and patents, grouped by source. It explicitly distinguishes from sibling tool entity_profile for static profiles.

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 examples of when to use (e.g., 'what's new with X', 'latest on Y') and when not to (use entity_profile instead). Also mentions fallback behavior (GDELT→GNews).

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 (idempotent, not destructive), the description adds behavioral context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Concise, well-structured. Front-loaded with purpose, followed by usage guidance, behavioral notes, and pairing instructions. Every sentence serves a purpose.

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 simple input schema (2 strings), no output schema, and annotations covering idempotent and non-destructive nature, the description fully contextualizes the tool: what it stores, how long, how to retrieve/delete.

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 clear descriptions. The description adds value by suggesting key naming conventions (e.g., 'subject_property') and specifying value types (findings, addresses).

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 reuse across conversations or sessions, with specific examples of what to store (ticker, address, preference). It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning pairing with them.

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 guidance on when to use ('when you discover something worth carrying forward') and context about persistence (authenticated vs anonymous). It suggests pair tools (recall, forget), making usage 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the output is a provider URL, which is useful context beyond the annotations. No contradictions.

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

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

A single, front-loaded sentence that is succinct and contains no unnecessary words. Every word earns its place.

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

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

For a simple tool with one parameter, rich annotations, and an output schema, the description provides sufficient context. It clearly states the action and result, leaving no gaps.

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

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

Schema coverage is 100% with parameter description providing an example. The description adds meaning by specifying 'prefix:id' format and 'provider URL' output, enhancing understanding beyond the schema.

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

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

The description clearly states the verb 'resolve' and the resource 'CURIE (prefix:id) to a provider URL'. It is specific and distinguishes from siblings like 'resolve_entity' which likely resolves to an entity rather than a URL.

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 on when to use this tool versus alternatives (e.g., 'resolve_entity', 'prefix', 'prefixes'). The description does not mention exclusions or context, leaving the agent to infer usage from the tool 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 already indicate safe read-only, idempotent behavior, but the description adds substantial behavioral context: identifiers are labeled with their source, unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and enrichment from GLEIF/OpenFIGI degrades gracefully so EDGAR results still return. This goes well 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 longer than average, but it is well-structured with examples first, then a core directive, then detailed breakdown by type. Each sentence provides value (supported types, fallback behavior, output composition), though some details could arguably be trimmed. It remains front-loaded and purposeful.

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 describing return values. It does so thoroughly: for companies, it enumerates CIK, ticker, company_name, LEI, FIGI, ownership info, and unresolved identifiers; for drugs, RxCUI, ingredient, brand, and citation. It also covers failure modes (graceful degradation), making it complete for a complex tool.

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

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

The input schema already provides full parameter descriptions for both 'type' and 'value', achieving 100% coverage. The description reinforces and explains the accepted values, but does not add significant extra syntactic details beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'resolve' and the resource: user-spoken NAME to canonical/official identifiers. It explicitly distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID' and provides specific identifier types (CIK, LEI, FIGI, RxCUI) and supported entity types (company, drug), setting it apart from sibling tools like entity_profile or search.

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 on when to use the tool ('Use FIRST whenever you have a name but need an ID') and even mentions it replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or name alternative tools for comparison, 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?

The description explicitly states internal behavior: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' It also describes the output: 'Returns ranked list with score, confidence, signal density per entity.' This adds value beyond the annotations, which already indicate readOnly and idempotent behavior.

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

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

The description is two sentences: first covers purpose and process, second provides a use case and output details. It is front-loaded with the main action and avoids unnecessary words. Every sentence serves a purpose.

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 (4 parameters, no output schema, but comprehensive annotations), the description covers purpose, usage, behavioral details, parameter roles, and output format. It is fully complete for an agent to understand 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 description adds significant meaning beyond the schema: 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the 'entities' parameter's semantics. The schema has 100% coverage, but the description enriches understanding. No parameter is left ambiguous.

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 specifies the verbs (compare, probes, ranks) and the resource (AI visibility). It distinguishes from sibling tools like ai_visibility_check by emphasizing multiple entities and competitive analysis.

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 a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use but does not explicitly list when not to use or compare with alternatives. However, the context is sufficient for an agent to decide.

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?

Describes composite behavior, partial failures, timing for bundlephobia, and return structure, adding value beyond annotations which already declare readOnly and idempotent.

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?

Well-structured and front-loaded, though slightly long; every sentence adds value.

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

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

Covers ecosystem scope, composite nature, return structure, limitations (timing), and graceful degradation; no output schema but description compensates.

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 description adds context like scoped packages accepted and version defaults, providing meaningful extra guidance.

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

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

Clearly states it's a composite check for npm packages, distinguishing from siblings by specifying ecosystem and mentioning alternatives for other ecosystems.

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

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

Explicitly says when to use (questions about safety/popularity/size/cost), and notes NPM-only scope with fallbacks.

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

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

Annotations already indicate readonly, idempotent, and non-destructive behavior. The description adds that results are limited by the 'limit' parameter, but does not elaborate on ordering, error handling, or other behavioral traits.

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, front-loading the core functionality and an example. There is no 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?

Given the output schema exists (not shown) and the tool is relatively simple, the description adequately covers input behavior and result limits. It could mention case sensitivity or absence of results, but is largely 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?

With 0% schema description coverage, the description must compensate but only minimally addresses the 'limit' parameter ('Returns up to `limit` matching prefix records'). The 'query' parameter is not explicitly described beyond the overall purpose, and no details on format or defaults are given.

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

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

The description clearly states that the tool searches Bioregistry for prefixes by substring match against name, title, or description, with an example. However, it does not explicitly differentiate from sibling tools like 'prefix' or 'prefixes' which might have overlapping functionality.

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 (searching for database prefixes), but lacks guidance on when not to use it or mentions of alternative tools among the siblings.

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

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

Discloses embedding model (BGE-base-en), window size (500-char overlapping), truncation behavior (200K cap with flag), and consistency with idempotent/readOnly 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?

A single, front-loaded paragraph with every sentence adding value: purpose, use case, output, technical details, and limitations. No redundancy.

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

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

Despite no output schema, the description sufficiently explains return format (passages with offsets and scores), truncation behavior, and pairing context.

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

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

Adds concrete examples (SEC 10-K, article, supply-chain risk) beyond the already descriptive schema, enhancing agent comprehension of parameter usage.

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 ('search') and resource ('inside a fetched record'), and differentiates from siblings by specifying it operates on already-fetched text and mentioning pairing with ask_pipeworx_grounded.

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 tells when to use (when record is too big for prompt) and what not to use (avoid cramming full text), and provides an alternative pairing suggestion.

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

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

The description adds significant behavioral context beyond the annotations. It discloses that creation requires an authenticated account, details the idempotent behavior (though not explicit, the annotation is supported by the subscription nature), and specifies constraints like the SMS daily cap and webhook auto-disable after failures. No contradictions with annotations are observed.

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 and return value, then detailing types and delivery. It packs a lot of information into one paragraph, which could benefit from bullet points for readability, but it remains clear without wasting words.

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

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

Given the tool's complexity (3 parameters, nested objects, many enums, no output schema), the description is remarkably complete. It covers all subscription types, their parameters, delivery channels with constraints, account requirements, and the return value (new subscription id). No important aspect is missing.

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

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

With 100% schema coverage, the schema already documents all parameters. The description enriches this by providing type-specific examples for params (e.g., sec_8k requires ticker and items) and detailed delivery options (e.g., webhook requires HTTPS and HMAC verification). This adds practical meaning beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (Create), resource (subscription to event stream), and provides examples of supported types, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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 explains when to use the tool (requires a Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions) and details the supported subscription types and their specific parameters. It also outlines delivery channel constraints (SMS cap, webhook auto-disable). Some guidance on alternatives (e.g., using recent_alerts for the feed) could be more explicit, but overall it provides clear usage 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?

Annotations already indicate safe, idempotent read. Description adds that it returns category-bucketed examples with exact tool/argument shapes, and explains no-arg vs topic behavior. No contradiction.

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

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

Description is moderately long but front-loaded with trigger phrases and all sentences add value. Some redundancy but maintains focus.

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, but description explains return format thoroughly (category-bucketed examples with tool+argument shapes). Covers all needed context for an onboarding 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% (one optional string). Description adds example values and explains usage like 'pass `topic` (e.g. finance, pharma) to focus', enriching beyond 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 returns categorized example questions showing what Pipeworx can do, listing trigger phrases and output format. It distinguishes itself as the onboarding entry point among siblings.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' That is clear guidance on when to use it.

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

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

Beyond annotations (which indicate idempotent and non-destructive), the description adds key behavioral details: ownership enforcement and row deactivation (not deletion). This fully informs the agent of the tool's side effects.

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, with the purpose stated first and no unnecessary words. Every sentence provides essential information.

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

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

Given the single required parameter, no output schema, and no enums or nested objects, the description fully explains the tool's behavior (ownership, deactivation) and parameter origin. No gaps remain for agent uncertainty.

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

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

The schema covers 100% of parameters. The description adds value by specifying that the id is 'returned by subscribe,' providing provenance context beyond the schema's type description.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb (cancel) and resource (subscription). It distinguishes from sibling tools like 'subscribe' (which creates) and 'list_subscriptions' (which lists).

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 specifies ownership enforcement ('only cancel your own subscriptions') and explains the effect (deactivation, not deletion). This provides clear when-to-use context, though it does not explicitly mention when not to use 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?

Even with strong annotations (readOnly, idempotent), the description adds significant behavioral nuance: it explains the meaning of 'could_not_verify' (check did not happen, not evidence), distinguishes 'unsupported' from 'refuted,' and describes the routing logic for company-financial vs. other claims. It also discloses the return structure (verdict, actual value, citation, reasoning). This goes well 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 long, but nearly every sentence adds value—trigger phrases, routing rules, return types, and error semantics. It is front-loaded with the most searchable phrases. It could be tightened by removing a few redundant clauses (e.g., 'against authoritative sources' appears twice), but overall it is well-structured for an AI agent.

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

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

With no output schema and only two parameters, the description carries the burden of explaining the full behavioral contract. It covers the verdict values, the type of evidence returned, the meaning of error states, and the fallback pipeline. The description is sufficiently complete for an agent to understand what happens and what to do with 'could_not_verify' results.

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

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

The input schema already provides 100% parameter documentation with helpful descriptions for both 'claim' and 'tolerance_pct'. The description enriches the 'tolerance_pct' parameter by explaining that the default is 'implied by wording, capped at 5' and notes the use case for hallucination detection with 1–2%. This adds meaning beyond the schema, meriting a score above baseline.

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

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

The description begins with explicit trigger phrases ('Is it true that…' / 'fact check' / 'verify the claim that…') and states a specific verb–resource pair: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from sibling tools by focusing solely on claim verification and even differentiates its behavior for company-financial vs. other claims.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear directive. It also hints at alternatives by saying it 'Replaces 4–6 sequential calls,' implying the alternative is a multi-step manual pipeline. However, it does not explicitly name sibling tools or provide when-not-to-use cases, so it stops 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.