Elife

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

The description adds significant value beyond annotations. It explains the default free model (Workers AI Llama-3.3-70b), the BYO key model for Anthropic, the scoring mechanism, and the return structure (per-model score, confidence, signals, raw_response + combined view). This fully discloses behavior without contradicting 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, consisting of a few well-structured sentences. It front-loads the main purpose and provides all necessary details without fluff. 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?

Given the tool's complexity (4 parameters, no output schema), the description fully covers what it does, how to use it, and what it returns. It specifies the return shape (per-model object with score, confidence, signals, raw_response + combined view), leaving no major gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: specific default model for 'models', 'passes straight through to api.anthropic.com' for '_apiKey', and 'disambiguate common names' for 'context'. This goes beyond the schema 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 it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It uses specific verb 'probe' and resource 'LLMs', making it distinct. However, it does not explicitly differentiate from similar sibling tools like 'scan_competitor_ai_presence', leaving some ambiguity.

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

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

The description provides context by listing use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass '_apiKey' to probe Anthropic. It does not offer when-not-to-use guidance or compare directly with alternatives, but the context is clear enough for basic selection.

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

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

Annotations already cover read-only and non-destructive behavior, and the description adds substantial behavioral context: it explains the routing mechanism, that arguments are auto-filled, the return format includes pipeworx:// citation URIs, and that it works on every tier with one fast call. It also clarifies limitations (not halluncination-resistant, not for broad fan-out) without contradicting the annotations.

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

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

The description is longer than average but well-structured: it opens with a strong directive, lists data sources, gives examples, and concludes with alternatives. Every sentence adds value, though a few phrases like 'works on every tier, one fast call' are slightly promotional. It is organized and front-loaded with key usage guidance.

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

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

With no output schema, the description compensates by explicitly stating the return type ('structured answer with pipeworx:// citation URIs') and providing a comprehensive decision framework. It covers when to use, when to step up, examples, and the tool's role as a default. No critical contextual gaps remain.

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

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

Schema coverage is 100% with a clear description for 'question' and aliases. The description adds example questions but does not introduce new parameter semantics beyond what the schema already states. The baseline of 3 applies; the examples are illustrative but not required for understanding the parameter.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and distinguishes itself from siblings by framing itself as the default entry point (START HERE) versus ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for specific data types, 'Use whenever the user asks...' with trigger phrases, and 'START HERE for most questions'. It also names clear alternatives for step-up scenarios: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. This goes beyond mere context and directly addresses when not to use this tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool's routing may change when a candidate is under test, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. It also clarifies that it does not fall back to anything—it is fully functional, which adds behavioral context.

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

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

The description is compact and front-loaded, with each sentence contributing essential information: beta identity, current status, usage instruction, comparison purpose, and fallback clarification. There is no redundancy or filler.

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

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

The description covers purpose, usage, behavioral state, and fallback, making it fairly complete for a beta router. It does not explicitly describe the return value, but 'same response shape' and 'universal router' provide sufficient context, and the schema already defines the input.

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 with descriptions, including all aliases for 'question'. The description only says 'same arguments' without adding semantic detail beyond the schema, so the baseline of 3 applies since the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, explicitly stating it is an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements and the experimental edge.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router to decide merges. It also names the alternative (ask_pipeworx) and explains that this is not a fallback but a full working router.

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?

While annotations already declare readOnly/openWorld/idempotent, the description adds substantial context: the exact return shape with evidence and refusal reasons, the constraint of using only tool result content, and the cost overhead. It fully discloses refusal behavior and does not contradict any annotations.

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

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

The description is dense but every sentence serves a purpose: purpose, process, return contract, usage guidance, and cost tradeoff. It is front-loaded with the key concept and wastes no 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 and the absence of an output schema, the description fully specifies both success and refusal response structures, use cases, limitations, and the relationship to a sibling tool. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds no new parameter-specific semantics beyond the overall purpose, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that routes to tools and extracts answers only from tool results, explicitly distinguishing it from ask_pipeworx. The verb 'extracts' and the specific return contract make the purpose unambiguous.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of one extra LLM call. This is clear, actionable guidance with a named 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?

The description extensively discloses behaviors beyond annotations: fan-out by category, resolver contract with match confidence tiers, parent event extraction for partition bets, news fallback handling, safety short-circuits for low confidence or closed markets, wide-spread warning, and cancellation rule parsing. It adds significant context over the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint 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 very long and dense, but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). While verbose, it front-loads the main purpose and uses clear headers. However, it could be more concise without losing key details.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers usage, response shapes (including nested fields like market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and critical behavioral notes (resolution-rule risk, fallback mechanisms). It provides all necessary contextual information for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the default for depth and its implications (quick vs. thorough), and for include_raw explains the trade-off between summary and full payloads. This goes beyond the schema's minimal 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, with specific inputs (slug, URL, question text) and process (resolve, classify, fan-out, return evidence+comparison). It effectively distinguishes from siblings like polymarket_edges by focusing on comprehensive evidence gathering.

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

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

It explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This is clear, but lacks explicit 'when not to use' compared to sibling tools like polymarket_edges. Overall, strong guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/clinical trials for drugs), how fiscal years are handled, sorting by primary metric, and return format with citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and key advice. While it is somewhat long, every sentence adds value (purpose, data sources, formatting, sorting, comparison benefit). A slight reordering or trimming could improve conciseness, but it is well-structured for readability.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers purpose, usage, data sources, parameter semantics, and expected behavior. It explains return format (paired data + citation URIs) and sorting, which compensates for lack of output schema. However, it could mention any limitations or error conditions.

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 provides rich additional meaning: explains what data each 'type' fetches (e.g., 'company' pulls revenue, net income, cash, long-term debt), how to format values (tickers/CIKs for company, drug names for drug), and constraints (2-5 items). This goes well beyond the schema's minimal 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 performs side-by-side comparisons of 2-5 companies or drugs in a single call, using verbs like 'compare', 'rank', and specifying the resource (entities). It distinguishes itself from potential siblings like 'entity_profile' by emphasizing parallel vs sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance. It also notes it replaces 8-15 sequential lookups, implying efficiency. However, it does not explicitly list when NOT to use it or mention specific sibling tools 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?

Beyond the annotations, the description discloses latency (15-60s, up to ~90s for thorough), the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] behavior ('never invented'), contradictions[] for standard/thorough, semantic excerpting, and citation resolvability. This is far richer than the annotations alone.

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

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

The description is lengthy but every sentence earns its place: account requirement, alternative, output format, depth semantics, and performance expectations. It front-loads the account prerequisite and main alternative, then packs in dense, non-redundant behavior details. No filler.

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

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

For a complex tool with no output schema, the description covers inputs, outputs, constraints, alternatives, and error behavior. It explains the findings packet fields, gaps[] behavior, contradictions[], depth tiers, and citation_uri condition, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning for the depth enum: quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 with iterative hop and contradictions. It also clarifies that broad/multi-part questions are appropriate for the question parameter, going beyond the schema's 'natural language' note.

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 provides a specific verb-resource pairing: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly differentiates from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

The description offers explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and the fallback if not signed in.

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

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

The description reveals key behavioral traits beyond annotations: returns top-N most relevant tools with 'names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This aligns with readOnlyHint and idempotentHint, and adds no contradiction.

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

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

The description is fairly concise but packed with information. It front-loads the core purpose and use cases. Slightly longer than ideal due to extensive examples, but every sentence earns its place.

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

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

Given 6 parameters and no output schema, the description adequately explains what the tool returns: top-N tools with schemas and examples. It covers the input, behavior, and output sufficiently, leaving no critical gaps for the agent.

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

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

Schema coverage is 100%, but the description adds value by explaining that 'query' accepts natural language and lists aliases (task, q, description, search). It also specifies default and max for limit, providing context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific use cases (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools by focusing on discovery and browsing rather than direct execution.

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

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

Provides explicit when-to-use guidance: 'Call this FIRST when you have many tools available and want to see the option set.' Also specifies use cases like browsing, searching, and discovering tools, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: patents API sunset May 2025 with soft-fail, fan-out across multiple sources, and return format details. No contradiction with annotations.

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

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

The description is lengthy but well-structured, starting with example queries and a preference statement. Every sentence adds value, though some internal details could be more concise.

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 fully explains return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their formats. It is comprehensive for a profiling 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%, and the description adds meaning: type is only 'company', value can be ticker or zero-padded CIK, names not supported. This clarifies parameter usage 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 specifies the tool's purpose: providing a full cross-source profile of a US public company. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs, distinguishing it from siblings like resolve_entity and compare_entities.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and provides example queries. It also notes when to use resolve_entity for name inputs, giving clear usage guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's mention of deletion is consistent. The description adds context about clearing sensitive data but does not elaborate on idempotency (idempotentHint=true) or behavior for missing keys. Moderate added value.

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 with no fluff. Front-loaded with the action verb and resource. Concise and well-structured.

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 required parameter and no output schema, the description covers usage context, pairing strategies, and intent. Complete and actionable.

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 the 'key' parameter described as 'Memory key to delete'. The description does not add further semantics beyond what the schema provides, so baseline 3.

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 deletes a memory by key, using the specific verb 'Delete' and resource 'memory'. It distinguishes from siblings 'remember' (store) and 'recall' (retrieve).

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

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

The description provides explicit guidance on when to use the tool: when context is stale, task is done, or to clear sensitive data. It also recommends pairing with 'remember' and 'recall'.

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 key behaviors: fetching an external URL, extracting title/description/links, emitting a standard format. Annotations (readOnlyHint, openWorldHint, idempotentHint) confirm safety and idempotency, and the description adds context like output format and deployment location.

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 plus a short list, front-loading the core purpose and output format. 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 no output schema, the description adequately explains the output (a single text blob in llms.txt markdown format ready for deployment). It covers the core functionality and parameter context without 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 both parameters (url and max_links) described in the schema. The description does not add additional meaning or constraints beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, detailing the process (fetch, extract, emit) and the output format. It distinguishes itself from sibling tools by focusing on generating the specific llms.txt file for AI crawlers.

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

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

The description provides explicit use cases (getting clients indexed, drafting for own project, auditing competitors) but does not mention when not to use the tool or suggest alternative tools for related tasks.

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-destructive behavior. The description adds that it returns specific fields and mentions 'Keyless' (likely no authentication required), adding value beyond annotations. No contradiction with annotations.

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

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

Two sentences with no wasted words. The purpose is front-loaded, followed by return fields and a note about keyless access. Every sentence earns its place.

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

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

No output schema exists, so the description compensates by listing return fields (title, DOI, type, etc.). It does not mention error conditions or format, but for a simple read tool with comprehensive annotations, this is reasonably complete.

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

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

Schema coverage is 100%, so the schema already documents the single 'id' parameter. The description adds an example value but no additional semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('article metadata and abstract'), specifies the identifier format with an example, and lists return fields. It clearly distinguishes from sibling tools like 'search_articles' (search) and 'latest_articles' (list).

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 implicitly indicates usage when you have a specific article id, and provides an example. However, it lacks explicit guidance on when not to use this tool versus alternatives, which would be helpful given the number of sibling tools.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds value by confirming keyless access, ordering (newest first), and exact return fields, providing 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?

Three focused sentences: action and ordering, journal context, return fields and keyless. No redundancy, well front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, ordering, return values, auth status. Annotations handle safety/hints.

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?

Only one parameter (limit) with schema describing default and max. Description does not add additional semantics. Given 100% schema coverage, 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 lists most recently published eLife articles newest first, specifies return fields (id, title, type, DOI, publication date, authors), and notes keyless access. It distinguishes from siblings like get_article or search_articles.

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?

Implied use is for simple listing of recent articles. However, no explicit guidance on when not to use (e.g., when search is better) or comparison with siblings like search_articles or get_article.

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 read-only, non-destructive, idempotent behavior via annotations and adds details on returned fields (id, type, params, timestamps, fire_count), enhancing transparency.

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 well-structured sentences: first defines purpose and output, second gives usage guidance. No unnecessary 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 simple tool (one optional param, no output schema), the description plus annotations cover all essential context: what it does, return fields, safety, and when to 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?

Only one parameter with full schema coverage; description adds no extra meaning beyond what the schema already 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 it lists active subscriptions and specifies return fields. Distinguishes from siblings by naming subscribe/unsubscribe as 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?

Explicitly says to use it to review monitoring before adding more or to find an ID to cancel, giving direct 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?

Even though annotations are all false, the description discloses substantial behavior: returns a claim_token for non-account filings, supports later status checks via pipeworx_feedback({claim_token:...}), rate limit of 5/day, free and not counted against quota, and team reading cadence with roadmap impact. It also warns against pasting prompts, which is a valuable behavioral constraint.

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

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

The description is lengthy (~200 words) but each sentence contributes distinct information: purpose, use cases, scope boundaries, token flow, rate limit, and cost. It is front-loaded with the verb and immediate when-to-use. The verbosity is justified by the tool's nuanced rules, though it is not as minimal as the best two-sentence examples.

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 adequately covers return behavior (claim_token and later status retrieval), limitations (rate limit, scope), and the human impact (team reads digests, roadmap influence). It provides all necessary context for an agent to correctly invoke the tool and understand its side effects.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra semantics beyond the schema: how to use claim_token (pass back as pipeworx_feedback({claim_token:'pwfb_…'})), and guidance to describe issues in terms of Pipeworx tools/packs rather than user prompts. These augment the parameter descriptions meaningfully.

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 phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool as a feedback-reporting mechanism. It distinguishes itself from sibling research/query tools by enumerating feedback types (bug, feature, data_gap, praise), making the purpose unambiguous.

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

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

Provides explicit 'Use when' clauses for bug, feature, data_gap, and praise, and a clear when-not for feedback about tools from other MCP servers: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This gives the agent precise decision rules for tool selection.

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 operation (readOnlyHint, idempotentHint, destructiveHint false). Description adds caching behavior ('Cached 5min-1h depending on window'), data source ('CF analytics-engine'), and privacy guarantee ('no PII'). 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 plus a bulleted list of use cases. Front-loaded with the core purpose. 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?

Despite lacking output schema, description covers return values (top tools, top packs, total call volume), caching, and data source. Sufficient for a single-optional-param read tool, though exact format could be clearer.

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?

Single parameter window is fully described in schema with enum and explanation. Description reinforces the semantic difference between window lengths ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), adding value 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?

Description starts with 'What other AI agents are calling on Pipeworx right now' then clearly lists returns: top tools, top packs, and call volume. It is a specific verb+resource combination that distinguishes this trending tool from sibling search/research tools.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). Does not directly contrast with siblings but provides clear context for 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?

The description discloses numerous behavioral traits beyond the annotations: semantic anchor (Jaccard similarity ≥ 0.30), partition filter (drops placeholders), fill check (realizable edge vs theoretical edge), and mentions that outputs may vary (open world). It also explains limitations like skipped_low_similarity and placeholder fraction. No contradiction with annotations (readOnly, 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?

The description is long but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). The first sentence front-loads the purpose. While it is dense, every sentence adds value for a complex tool. Minor deduction for length; could be more concise but justified by the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description covers input modes, algorithms, filters, and fill check. However, it doesn't fully specify the output format for the no-args 'trending_scan' mode, and the output fields (gap_pp, suggested_trade, etc.) are described only in passing. Some error conditions or default behavior could be added. Still, it provides sufficient context for an agent to understand most aspects.

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 input schema. For the event parameter, it details 'walks child markets, checks date-axis / threshold-axis ordering AND computes partition_check.' For topic, it explains 'searches related events across the platform, flattens markets, runs the comparator on the union.' Schema descriptions are present but the tool description provides the operational logic and algorithm, which is essential for correct use.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This specific verb+resource combination, along with details about monotonicity and partition checks, distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 each parameter: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event for specific markets and explains cross-event mode catches patterns single-event misses. Additionally, it directs to polymarket_fill_risk for custom sizing, showing clear 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 declare the tool as read-only and idempotent. Beyond that, the description adds rich behavioral context: caching duration and keying, Fed bet exclusion rationale, the fact that partition_overround parent-level kelly_fraction_half is always 0, and diagnostic output for empty segments. There are 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 thorough but lengthy (multiple paragraphs). It is well-structured with segments and bullet points, but could be more concise. Every sentence adds value, but the overall length makes it less ideal for quick scanning.

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 (9 parameters, 3 model families, diagnostic feedback) and lack of output schema, the description is remarkably complete. It explains top-level response structure (by_segment, diagnostics, fed_candidates), edge calculation details, and filtering knobs. All important aspects are covered.

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 mentions 'tradeable-edge knobs' collectively but does not add parameter-specific meaning beyond what the schema already provides. No new semantics for individual parameters.

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

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

The description clearly states the tool's verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the 'what should I bet on today' use case, distinguishing it from generic market listing tools. Though sibling differentiation could be more explicit, the unique methodology (three segments, edge calculation) makes its role unmistakable.

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

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

The description provides clear usage context: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It includes practical guidance like 'Fed bets excluded from ranking' and notes caching behavior ('Cached 1h at the KV level'). It does not explicitly state when not to use it or compare with siblings, but the context is sufficiently 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 readOnly, idempotent, non-destructive. Description adds details on snapshot-based data, decay computation from daily closes, and potential gaps in snapshot dates. 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?

Front-loaded with purpose and key output details. Some redundancy (e.g., limitations section), but overall efficient for the complexity. Could trim minor redundancy.

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

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

With no output schema, description adequately details return fields (tracked, expired, snapshot_dates) and their meanings. Annotations cover safety. Communicates complex temporal analysis well.

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

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

Input schema covers both parameters with descriptions. Description adds value by explaining defaults, max for days, and window as snapshot family. Schema coverage is 100%, so baseline is 3; extra context justifies 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?

Description clearly states the tool answers how long an edge has existed and whether it is shrinking, and details the output structure (tracked, expired, snapshot_dates). It distinguishes from sibling tools like polymarket_edges by focusing on temporal persistence.

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 context on when to use this tool (e.g., comparing fresh vs. old edges) and includes limitations (60-day TTL, decay from daily closes). However, it does not explicitly mention when not to use or list 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds value by explaining the live CLOB check, ladder walking, and warning about partial fills converting arb to unhedged positions. No contradiction with annotations.

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

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

The description is longer but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value. Slightly verbose but justified by the tool's complexity.

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

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

No output schema exists, but the description comprehensively covers return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs). It also includes warnings about directional risk and max fillable amounts. 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%, baseline 3. The description adds significant meaning: explains two modes (single-market vs basket), defaults for `side`, interpretation of `size_usd` in each mode, and details on return values. This goes well 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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and lists specific return fields. It is specific and differentiates 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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills cause directional risk). Also clarifies that one of `market` or `event` is required.

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 thoroughly explains behavioral traits beyond annotations, including compatibility_warning conditions, temporal alignment, skipped leg comparisons, and the meaning of response fields. It discloses that real spreads are rarer than shortcuts suggest, which aligns with readOnlyHint and idempotentHint 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 front-loaded with the purpose and well-structured with clear sections (modes, response, safety fields). However, it is somewhat verbose and could be trimmed without losing 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 no output schema, the description fully explains return fields (raw probabilities, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases. It provides sufficient context for the agent to interpret results correctly.

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

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

The input schema already covers all three parameters with descriptions (100% coverage). The description adds value by explaining the usage context of each parameter (topic is a shortcut, kalshi_event_ticker and polymarket_event_slug override) and enumerating the valid topic values, enhancing the agent's 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, describing two modes (topic shortcuts and explicit tickers). It distinguishes this tool from siblings by specifying its unique function of comparing prices across venues.

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 when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and warns that many pre-mapped topics are not yet tradeable due to compatibility issues, guiding the agent to use explicit tickers for reliable spreads.

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, destructiveHint=false, idempotentHint=true. Description adds scoping detail ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and behavior when key is omitted (list all keys). 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: first states core purpose, second provides use cases, scoping, and pairings. No wasted words, efficient and clear.

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 1 optional parameter, no output schema, and informative annotations, the description adequately covers retrieval, listing, scoping, and paired tools. No gaps for agent decision-making.

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 1 parameter (key) with description 'Memory key to retrieve (omit to list all keys)' and 100% coverage. Description echoes this behavior but adds no new semantic detail beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the action (retrieve/list) and resource (saved values/keys), and distinguishes from siblings by mentioning 'remember' and 'forget'.

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

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

Provides explicit use cases: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' Implicitly suggests when to use (already saved) and not to use (if not saved), but lacks explicit when-not-to-use or alternatives beyond pairing with remember/forget.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds valuable behavioral details: mark_read flags events read, polling works fine, and return fields are listed. 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?

Four sentences, each serving a purpose: main function, return fields, filtering, and mark_read behavior. No redundant or vague language. Front-loaded with the core action.

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

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

Given no output schema, the description explains return fields and usage. It covers filtering options, mark_read side effects, polling suitability, and an alternative access method. Complete for a read-only tool with clear usage.

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

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

Schema coverage is 100%, so parameters are already described. The description adds context beyond schema, e.g., example type 'sec_8k', ISO timestamp format for 'since', and the effect of mark_read. This provides meaningful additional 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?

The description clearly states the tool pulls fired events from the subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and supports filtering. This distinguishes it from siblings like list_subscriptions or recall, though not explicitly named.

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

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

Provides clear context: filter by type/since, mark_read behavior, and even an alternative URL for scripts. Lacks explicit when-not-to-use or comparison to other tools, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds rich behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), describes fallback logic, and specifies the return format (structured changes[] grouped by source, total_changes count, citation URIs).

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

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

The description is a single paragraph but efficiently packs all necessary information. It could benefit from slight restructuring for readability, but it is not overly verbose.

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

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

Given the tool's complexity (multiple data sources, fallbacks, parameter options), the description covers all important aspects thoroughly. No output schema exists, but the description explains the return format adequately.

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 descriptions. The description adds value by explaining relative shorthand (e.g., '7d', '30d') and suggesting typical values, which goes 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 returns a 'change feed for a company in the last N days/weeks/months' with example queries. It also distinguishes from sibling 'entity_profile' by specifying when to use that instead.

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 this tool vs 'entity_profile' and provides usage tips like 'Use "30d" or "1m" for typical monitoring.'

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context: scoped by agent identifier, persistence difference between authenticated users (permanent) and anonymous sessions (24 hours). 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?

Three sentences, front-loaded with purpose, every sentence adds necessary information. No fluff.

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

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

For a simple key-value pair tool with no output schema, the description covers purpose, usage, behavior, persistence, and relationships to sibling tools. Complete for its complexity.

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

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

The input schema already describes both parameters with 100% coverage. The description adds context like example key formats and the scoping by identifier, which adds value beyond the schema.

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

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

The description starts with 'Save data the agent will need to reuse later' which uses a specific verb and resource. It also distinguishes from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and notes alternatives ('Pair with recall to retrieve later, forget to delete').

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, and idempotent. The description adds significant behavioral depth: it cascades through multiple endpoints, gracefully degrades if GLEIF/OpenFIGI are unavailable, explicitly reports unresolved identifiers under `unresolved`, and labels identifiers by source. These go well beyond the annotation hints.

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

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

The description is long but every part is informative. It is structured with 'SUPPORTED TYPES' and examples, yet the single-paragraph format makes it less scannable than ideal. Still, it is not wasteful; it condenses a complex tool's behavior into one paragraph.

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

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

Even without an output schema, the description covers what identifiers are returned for each type, source labeling, unresolved handling, graceful degradation, and acceptable inputs. This is highly complete for a complex tool with two modes and multiple backend lookups.

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% for both parameters, so baseline is 3. The description largely repeats the accepted formats and examples already in the schema (e.g., ticker/CIK/name for company, brand/generic for drug). It adds output/enrichment context, but not substantial new input semantics.

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 core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and distinguishes itself by being the ID-resolution step, positioning it against sibling tools that consume identifiers.

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

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

Explicitly instructs when to use: 'Use FIRST whenever you have a name but need an ID.' It also lists trigger phrases and describes the internal cascading, which supports its role as a primary lookup tool. This is clear usage guidance.

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

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

The description details internal behavior: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It adds context beyond annotations (e.g., first entity treated as subject). No contradiction with annotations.

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

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

The description is three sentences, each serving a distinct purpose: main function, how it works, and use case. No redundant words; front-loaded with core action.

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

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

Given no output schema, the description fully explains return values (ranked list with score/confidence/density) and constraints (2-8 entities, model choices, API key requirement). All aspects of usage are covered.

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 description coverage, the description still adds significant value: it specifies the entity array length (2-8), treats first entry as subject, clarifies default model (workers-ai) and Anthropic requirement, and explains the context 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 compares AI visibility across multiple entities, using a specific verb ('compare') and resource ('AI visibility'). It differentiates from the sibling tool 'ai_visibility_check' by noting it probes multiple entities side-by-side and ranks 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 provides a clear use case: competitive AI-marketing audits. It implies that for single-entity checks, one should use 'ai_visibility_check', thus giving when-to-use and when-not-to-use guidance, though explicit exclusions are absent.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds substantial behavioral context: fans out across two services, return structure (summary block, per-advisory detail, links, alternative versions), partial failures with sources_failed field, and timing note for bundlephobia first measurement (5-30s). No contradiction with annotations.

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

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

The description is front-loaded with purpose and outcome. It is relatively long but every sentence adds value. Minor conciseness improvement possible, but still efficient given the tool's composite nature.

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

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

No output schema exists, but description fully explains return values (summary block fields, per-advisory details, links, alternative versions) and handles partial failures. Covers ecosystem scope, timing, and graceful degradation. Complete for a complex composite tool.

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

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

Schema description coverage is 100%. Description adds beyond schema: for package, it specifies scoped packages like '@types/node' are accepted; for version, it states defaults to latest when omitted.

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

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

The description uses specific verbs ('fans out', 'Returns') and clearly identifies the resource (npm package check) and the composite nature (license, advisories, bundle size). It distinguishes itself from siblings by explicitly stating NPM-only scope and mentioning other ecosystems are handled via deps.dev directly.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states when not to use (non-npm ecosystems). Covers fallback behavior and partial failures.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explicitly stating 'Keyless' (no authentication required). This is a useful behavioral trait beyond annotations. No other behavioral details (e.g., pagination, error handling) are provided, but the keyless info is relevant.

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, no fluff. The first sentence efficiently conveys the core purpose and return values; the second adds a key behavioral note ('Keyless'). 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 search tool with no output schema and only two parameters, the description is nearly complete. It specifies what is returned (id, title, etc.) and notes keyless access. The schema covers limits and defaults. Minor omission: no default limit stated in description, but it's in 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?

The input schema has 100% description coverage: both parameters (limit, query) are described. The description does not add additional semantics beyond restating that search is by keyword. Thus, it meets the baseline without enhancement.

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

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

The description clearly states the action ('Search'), the resource ('eLife articles'), and the purpose ('for articles by keyword'). It specifies the return fields (id, title, type, DOI, etc.), distinguishing it from sibling tools like get_article or latest_articles.

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

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

The description implies usage via examples and notes 'Keyless' accessibility, but does not explicitly state when to use this tool over siblings (e.g., get_article for a specific article, latest_articles for recent ones). No exclusions or alternatives are mentioned.

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 not destructive. The description adds technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' No contradiction.

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

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

The description is a single paragraph, efficiently covering purpose, usage, behavior, and technical details. It is front-loaded with the main purpose and contains no unnecessary 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?

Despite no output schema, the description explains return values: 'top-N passages with character offsets and similarity scores.' It also mentions the 200K char cap and truncation behavior. This is complete for an agent to understand the tool's output.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining that 'text' is document text, 'query' is natural-language (with examples), and 'limit' is max passages. This adds value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the action: takes text and query, returns passages with offsets and scores. It distinguishes from sibling tools by specifying when to use it (when record is too large) 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?

The description explicitly provides usage guidance: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded for grounding over passages. This gives clear context and alternatives.

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

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

Beyond annotations (idempotent, non-destructive, open world), the description adds substantial behavior: requires OAuth, returns subscription id, feed always on, email/SMS/webhook delivery with constraints (sms 10/day cap, webhook auto-disable after 10 failures). No contradiction with annotations.

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

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

The description is informative and front-loaded with the main purpose, but it is somewhat lengthy. While every sentence adds value, it could be slightly more structured. Still, it does not waste space.

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 omits two subscription types from the schema ('patent_grant' and 'clinical_trial'), which are listed in the enum. This is a notable gap. Otherwise, it covers prerequisites, types, and delivery well.

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

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

Although schema coverage is 100%, the description enriches parameters with concrete examples and explanations: e.g., sec_8k item codes, polymarket_edge topic, delivery webhook signing details. This goes well beyond the schema 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb 'create' and resource 'subscription' are specific, and the tool is distinguished from siblings like 'list_subscriptions' and 'unsubscribe' by its action.

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 context by requiring a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It also describes supported types and delivery channels. However, it does not explicitly state when not to use this tool or compare it to other query tools.

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

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

The description adds significant behavioral context beyond annotations: it highlights that the tool returns category-bucketed example questions drawn from the live catalog, and that it is an onboarding/discovery tool, not a regular query tool. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, which are consistent.

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 somewhat long but front-loaded with example questions and structured with categories and usage instructions. Every sentence adds value, though a slightly tighter edit could improve conciseness.

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

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

Given the tool's onboarding purpose, no output schema, and a single optional parameter, the description is fully complete. It tells the agent exactly when to use it, what to expect (category-bucketed examples with tool+argument shapes), and how to call it (no args or with topic).

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 has one optional parameter `topic` with a description listing focus areas. The description adds meaning by explaining what happens when omitted (full spread) and when passed (focus), and enumerates possible values. Schema coverage is 100%, but the description still adds 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?

The description clearly states the tool's purpose as an onboarding entry point that returns example questions and the exact tool+argument shape to answer them. It distinguishes itself from sibling tools like ask_pipeworx, entity_profile, etc., by being the 'first' tool to use when unfamiliar with Pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains both the no-argument call and the optional `topic` parameter. It provides clear context and alternatives, such as learning how to call meta-tools.

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

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

The description exceeds annotations by revealing that the row is deactivated (not deleted) and historical events remain via recent_alerts. It also specifies ownership enforcement. Annotations indicate idempotent and non-destructive, which the description aligns with and enriches.

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 tight sentences with no wasted words. First sentence states action, second adds constraint, third explains effect. Well-structured and front-loaded.

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

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

For a simple tool with one required parameter, no output schema, and annotations covering idempotency and destructiveness, the description fully explains behavior, ownership, and tie-in with recent_alerts. Complete and sufficient.

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

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

Schema covers 100% of the single 'id' parameter with description. The main description adds that the id comes from subscribe and mentions ownership, but does not provide additional parameter details 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 action 'cancel a subscription' by id, identifies the resource, and distinguishes from siblings like subscribe (create), list_subscriptions (list), and recent_alerts (view historical events).

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 (cancel subscription by id) and mentions ownership enforcement, implying only for own subscriptions. It also hints at the alternative of using recent_alerts for historical data. However, it does not explicitly list when not to use or name alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description goes well beyond that. It discloses the verdict taxonomy (including 'inconclusive' and 'could_not_verify'), explains critical semantic distinctions (could_not_verify vs unsupported), and reveals the verification_error{stage,detail} payload. This is rich behavioral context that helps the agent interpret results correctly and avoid misusing failure modes.

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

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

The description is dense but well-organized: trigger phrases, usage directive, two-path explanation, output details, caveats, and efficiency claim—each sentence earns its place. It is long enough to cover necessary complexity without bloat, and the most critical usage trigger is front-loaded.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases, and it succeeds. It specifies the verdict list, the evidence format (grounded value with pipeworx:// citation), and reasoning. It also clarifies failure semantics and distinguishes 'unsupported' (no source covers it) from 'could_not_verify' (check didn't happen). For a 2-parameter tool, this is exceptionally complete.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds substantial meaning. For 'claim' it provides real examples; for 'tolerance_pct' it explains how it overrides the claim's implied tolerance, gives the default behavior (capped at 5), and offers a concrete use case (set 1–2 for hallucination detection). This is actionable guidance beyond the schema's mere type and presence.

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 trigger phrases, then states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly differentiates from sibling research/Q&A tools by emphasizing deterministic verdicts and the two-pathway approach (SEC EDGAR vs grounded pipeline). It also positions itself as a replacement for 4–6 sequential calls, distinguishing it from generic lookup tools.

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

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

Explicit when-to-use guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (company-financial vs. any other claim). However, it does not explicitly state when not to use it or name a specific alternative sibling tool, though it implies the alternative is the sequential pipeline it replaces.

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