Datacite

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

Annotations already mark it as readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral details: cost implications (free for Workers AI, BYO key for Anthropic), the scoring range, return structure (per-model {score, confidence, signals, raw_response} + combined view), and the API key handling. This exceeds what annotations provide.

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

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

The description is a single, efficient paragraph that front-loads the core purpose and then adds necessary details about defaults, costs, and return structure. Every sentence delivers useful information with no redundancy.

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

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

Despite no output schema, the description fully explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers inputs, defaults, optional parameters, and use cases. The tool is well-documented 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 has 100% description coverage, so baseline is 3. The description adds value by explaining the default model behavior, the necessity of '_apiKey' for Anthropic, and how 'context' aids disambiguation. This extra context improves parameter understanding.

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

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

The description explicitly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility from 0-100, naming the default model and optional Anthropic integration. This clearly distinguishes it from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence'.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it does not explicitly state when to avoid this tool, the use cases are well-defined and imply appropriate scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: the tool autonomously selects among thousands of tools, fills arguments, returns citation-bearing output, works on every tier, and is a single fast call. This goes beyond the annotations without contradiction.

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

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

The description is long but each sentence contributes: purpose, scope, examples, alternatives, and edge cases. It is front-loaded with the primary directive and remains focused, so the length is justified.

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, no output schema, and rich annotations, the description covers all necessary aspects: behavior, return format, alternatives, examples, and triggers. An agent can invoke it correctly and know when to defer to siblings.

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

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

The input schema covers all 6 parameters with 100% description coverage, including aliases. The description does not add parameter-level semantics beyond usage examples, but the schema already handles that. 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 routes natural-language questions to one of 5,621 verified tools, fills arguments, and returns a structured answer with citation URIs. It explicitly contrasts with sibling tools like ask_pipeworx_grounded and deep_research, making its distinct role unambiguous.

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

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

It provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE', lists trigger phrases ('what is', 'look up', etc.), gives concrete examples, and prescribes step-up conditions for ask_pipeworx_grounded (single hallucination-resistant answer) and deep_research (broad/multi-part queries). Also clarifies news behavior.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about its experimental nature: 'candidate routing improvements enabled live whenever one is under test' and clarifies it's a full working router, not a fallback. This goes beyond annotations by explaining the beta behavior and current state, though it doesn't add more granular behavioral detail.

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, well-structured paragraph with two substantial sentences. It is front-loaded with the core purpose (beta router) and then elaborates on usage and current state. Every sentence contributes meaning without redundancy, though it is slightly longer than strictly necessary.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description sufficiently explains its relationship to ask_pipeworx, the beta nature, and current behavior. It implicitly covers the response shape by referencing 'same response shape' as ask_pipeworx. No critical missing information for an agent to invoke it correctly.

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

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

The schema provides 100% coverage of the six parameters, all documented as aliases for 'question'. The description doesn't add any additional meaning about parameters beyond what the schema already states. With full schema coverage, the baseline of 3 is appropriate; no extra semantic value is added.

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

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

The description clearly states this is a beta version of ask_pipeworx, describing it as an identical universal router with the same 5,621 tools, arguments, and response shape. It explicitly differentiates itself from the stable ask_pipeworx by noting candidate routing improvements, making its purpose unambiguous. This is a specific verb (ask), resource (pipeworx), and scope (beta) with clear sibling distinction.

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 instructs when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that it's identical to ask_pipeworx when no candidate is active, providing clear context for when this is appropriate versus alternatives. It mentions results are compared to the stable router, giving reason for 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds substantial behavioral context: it EXTRACTS answers using only tool results, returns structured evidence and confidence, has a list of explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and incurs an extra LLM call. This is beyond what annotations provide and fully discloses behavior. No contradiction found.

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

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

The description is dense but every sentence carries load: it starts with the core purpose, explains routing and extraction, details it return shape, lists refusal reasons, gives concrete use cases, and notes the cost trade-off. There is no fluff or repetition; the length is justified by the tool's behavioral complexity. Front-loaded with the high-stakes qualifier.

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

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

There is no output schema, so the description must and does explain the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and the specific refusal reasons. It also covers cost, usage scenarios, and alternative. For a tool with six parameters that all map to one natural-language question, this is complete — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% — every parameter (including all 5 aliases) is documented with a semantic description, so the schema already tells the agent that all fields are aliases for the natural-language question. The description adds no additional meaning beyond 'question in natural language,' which is already in the schema. Baseline 3 is appropriate because 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 hallucination-resistant answer mode for high-stakes reads, with explicit behavior (extracts answer only from tool results, refuses on insufficient data). It also directly contrasts with sibling ask_pipeworx by highlighting the same routing but added extraction and refusal layer. This is a specific verb+resource+mode that strongly differentiates it from siblings.

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

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

The description explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives concrete domains (financial, legal, medical, public statements). It also tells when not to use it: 'prefer ask_pipeworx for casual lookups.' This is textbook guidance with an explicit alternative and selection condition.

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=true, idempotentHint=true, etc., and the description adds extensive behavior: fan-out process, response shapes, market match confidence levels, parent event extraction, news fallbacks, safety short-circuits, and resolution rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with headings and examples. Every sentence provides value for the tool's complexity. It is front-loaded with purpose and then details response shapes and edge cases.

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

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

Given the complexity of 3 parameters and no output schema, the description covers input format, processing details, response structure, edge cases (closed markets, low-confidence), and resolution rules comprehensively. It leaves little ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context for the market parameter (slug, URL, question) and explains depth and include_raw behaviors, but it does not significantly extend 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb (research), resource (Polymarket bet), and input formats. It distinguishes from sibling tools like polymarket_arbitrage, which focus on analysis rather than data 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?

The description tells when to use the tool: for questions like 'should I bet on X' or 'is there edge in Z'. It provides examples and warns about inspecting market_match_confidence before trusting analysis. However, it does not explicitly mention when NOT to use it or list alternative 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?

Beyond annotations (readOnly, idempotent, openWorld), the description reveals that for 'company' it pulls specific financial metrics (revenue, net income, cash, debt) with correct fiscal year handling, and for 'drug' it pulls adverse-event counts, approval counts, and trial counts. It also states results are sorted by primary metric and includes citation URIs, adding significant 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 concise and front-loaded with trigger phrases and imperative guidance. Every sentence provides necessary information without redundancy, making it efficient for an AI agent to parse and understand.

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 return values (paired data + pipeworx:// citation URIs) and covers both entity types comprehensively. It also estimates the efficiency gain (replaces 8-15 lookups), providing sufficient context for tool selection.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying 'values' uses tickers/CIKs for companies and drug names for drugs, and explicitly states the min/max limits (2-5) already in schema, but also explains the purpose of the 'type' enum, enhancing clarity beyond the schema.

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

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

Description uses specific verbs ('compare', 'side-by-side comparison') and clearly states the resource (2-5 companies or drugs) and action. It further specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and distinguishes from sequential lookups, 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?

Description explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides natural language triggers (e.g., 'compare X and Y', 'which is bigger'). It lacks explicit when-not-to-use scenarios, but the context is clear enough for most use cases.

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 it readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context beyond those: account requirement and paid tier for thorough, parallel routing across 5,621 tools, gaps[] for unanswered facets with a 'never invented' guarantee, fetchable citation_uri condition, hop field, contradictions[] for standard/thorough depths, semantic excerpting, and expected latency. No contradiction with annotations.

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

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

The description is long but front-loaded with the most critical gate (account requirement and fallback). Most sentences carry unique operational value (citation fetchability, semantic excerpting, timing). However, exact counts like '1472' and '5,621' are somewhat extraneous and could be trimmed without losing meaning, so it does not earn a 5 on 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?

With no output schema, the description fully explains the return value: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers auth, timing, depth behavior, and the alternative tool. Nothing an agent needs in order to call this correctly is missing.

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

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

The input schema has 100% coverage for both parameters (question, depth) with an enum on depth, so the baseline is 3. The description goes far beyond the schema by explaining how 'question' is decomposed into facets, and by giving operational meaning to each depth value: quick=3 single-hop, standard=3 with gap recovery+contradictions, thorough=6 with iterative hop. This is genuine added meaning, not schema repetition.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1472 STRUCTURED data sources' in one call, and explicitly says 'this is NOT open-web search'. It distinguishes from the sibling tool ask_pipeworx by naming it as the alternative for single lookups/breaking news. An agent can immediately tell what this tool does and how it differs from the listed siblings.

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

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

Explicitly provides when-to-use/when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It even gives a fallback instruction for signed-out users ('If you are not signed in, use ask_pipeworx instead'). This leaves no ambiguity about which tool to choose.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly'. 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 fairly long but well-structured, front-loading the core purpose, then listing domains, return behavior, and usage guidance. Each sentence adds value with minimal 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 6 parameters with full schema coverage and no output schema, the description adequately explains return values (top-N tools with schemas) and provides examples. No obvious gaps for this 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% with all parameters described. The description mentions aliases for query and provides usage examples, but adds no extra semantic detail 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?

The description states a specific verb 'Find tools by describing the data or task' and lists diverse domains (SEC filings, financials, etc.), clearly distinguishing it from sibling tools which are specific actions or data sources.

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 directs when to use: 'Call this FIRST when you have many tools available and want to see the option set'. It implies discovery before action, though it does not explicitly state when not to use.

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

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

Annotations confirm safe read-only behavior. Description adds beyond annotations: fans across multiple sources, returns specific data (CIK, filings, fundamentals, patents, news, LEI), mentions patents API sunset and soft-fail behavior, and notes news fallback. No contradictions.

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

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

Description packs substantial information into about 10 lines with clear structure (examples, bullet points, parenthetical notes). While dense, it is efficiently organized and front-loaded with purpose; minor redundancy could be trimmed but overall 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?

Despite lacking an output schema, the description fully explains the composite output: CIK, recent filings with URIs, fundamentals (sorted, latest), patents (with sunset note), news (with fallback), and LEI. Also covers limitations (name not supported, patents API sunset). Provides a complete picture for an agent.

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

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

Schema covers both parameters with descriptions (100% coverage). Description enhances by reiterating that value must be ticker or CIK, not name, and type currently only supports 'company' with planned expansion. Adds actionable context beyond schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It includes trigger phrases like 'Tell me about X' and distinguishes from siblings by specifying that names are not supported, directing to resolve_entity 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 instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Also states when not to use: when only a name is provided, then use resolve_entity. Provides clear guidance on input format (ticker or zero-padded CIK).

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

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

Annotations already declare destructiveHint=true; description adds the action 'delete' but no further behavioral details beyond the schema and 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, front-loaded with core action, zero 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage conditions, and relationship to sibling tools.

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 description mentions 'by key', but the schema already defines 'Memory key to delete', so no additional value beyond baseline.

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

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

Clearly states the tool deletes a memory by key, distinguishing it from siblings like 'remember' and 'recall'.

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

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

Explicitly specifies when to use (stale context, task done, clear sensitive data) and mentions companions, though no explicit 'when not to use'.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It adds context about output format and placement, enhancing transparency 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?

Three sentences, each earning its place: first states purpose and target, second describes the process, third lists use cases. No fluff, front-loaded, and efficiently 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?

Given the simple tool (2 params, no output schema), the description covers purpose, process, output format, and use cases. It lacks error handling or accessibility prerequisites, but for a generation tool, it's sufficiently complete. Annotations further cover safety 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?

Schema coverage is 100% with clear parameter descriptions. The description adds minimal new meaning: it mentions 'for any URL' and implies max_links controls link count. Since schema already explains parameters, the description doesn't significantly augment understanding.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb (generate), resource (llms.txt), and target (any URL). It also distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists specific use cases: getting a client's site indexed, drafting for own project, auditing competitor's AI view. While it doesn't explicitly exclude scenarios, the examples provide clear context. It could be improved by mentioning alternatives like scan_competitor_ai_presence for auditing.

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. Description adds detail on returned metadata fields, consistent 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: first states action, second lists return fields. No wasted words.

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

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

Given the simple tool with one parameter, output schema present, and comprehensive annotations, the description thoroughly covers purpose and returns.

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

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

Schema already describes the 'doi' parameter with an example. Description adds no additional semantic detail beyond the schema.

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

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

Clearly states it fetches a single DOI record and lists specific metadata returned, distinguishing it from 'search_dois' for multiple records.

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 describes fetching a single record, implying usage when a specific DOI is known, but does not explicitly contrast with sibling 'search_dois'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and behavioral profile. The description adds that repositories are DataCite-registered and support filtering, but no additional behaviors (e.g., pagination details, rate limits) are disclosed. The description adds value but does not significantly expand beyond annotations.

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

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

The description is extremely concise (two sentences), front-loaded with the main purpose, and includes an example and a use case. No unnecessary words; 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 the low complexity, full schema coverage, and presence of an output schema, the description is fairly complete. It provides examples and a clear use case. However, it could optionally mention pagination behavior (though schema covers defaults) and briefly note the response structure, but the output schema likely covers that. Minor gap.

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

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

Schema coverage is 100% with each parameter documented (page, query, page_size). The description only mentions 'filter by query' which is redundant with the schema. It adds no new semantics 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 lists DataCite-registered data repositories, provides concrete examples (Zenodo, Dryad, Figshare), and distinguishes itself from sibling tools which are unrelated to repositories. The verb 'list' and resource 'repositories' are specific.

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 it's useful for 'where do I deposit a dataset' lookups, giving a clear context of use. It does not mention alternatives or when not to use, but sibling tools do not compete, so this is a minor omission. The guidance is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds specific return fields and the scope 'active subscriptions,' but does not elaborate on queries or limits. Still, it complements annotations well.

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 action and output, second provides usage context. No wordiness, and key information 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?

Given one optional parameter, strong annotations, and no output schema, the description is nearly complete. It explains purpose, output fields, and usage. Minor omission: no mention of result ordering or limits, but not critical for this tool.

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

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

Schema coverage is 100%, so description need not repeat parameter details. The parameter 'include_inactive' is documented in the schema, and the description adds no extra semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It also distinguishes from sibling tools like subscribe and unsubscribe by providing use cases.

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 advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This guides the agent effectively, though alternatives are implicitly differentiated rather than named.

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 only provide basic hints, but the description goes far beyond: it discloses rate-limiting (5 per identifier/day), confirms no quota impact, explains the claim_token return and follow-up flow, and notes daily digest reading. 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?

Although long, every sentence earns its place: purpose, usage conditions, exclusions, claim_token workflow, SLA, rate limit, and cost. Front-loaded with intent and no filler or redundancy, making the length justified for this non-obvious tool.

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

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

Even without an output schema, the description explains what the tool returns (claim_token initially, status/changes later). It covers scope boundaries, invocation behavior, rate limits, quota cost, and the feedback lifecycle, making the tool fully understandable and safely usable in context.

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

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

Schema coverage is 100%, but the description adds real semantic value: it maps type values to concrete scenarios (bug, feature, data_gap, praise), explains how to use claim_token to read prior replies, and instructs users to reference Pipeworx tools/packs which aligns with the context object. This significantly enriches the bare schema.

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

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

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the verb+resource and unique purpose. It distinguishes itself from all sibling tools by focusing exclusively on feedback for Pipeworx-provided tools, with no overlap.

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 covers bug, feature/data_gap, and praise scenarios. It also provides strong when-not-to-use guidance for tools from other MCP servers, plus instructions on what to include (Pipeworx tools/packs) and how to follow up with claim_token.

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 false. Described adds no-PII, self-aggregating from CF analytics, caching (5min-1h). 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 paragraphs, no wasted words. Use cases are bulleted. Additional details (caching, no PII) are brief but informative. Perfectly 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 optional parameter and no output schema, the description fully covers return values (tools, packs, volume), data source, caching, and privacy. No gaps.

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

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

Only one parameter (window) with enum, schema description is 100% coverage. Description adds value by explaining trade-offs between short and long windows ('hot right now' vs 'steady-state demand').

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 returns top tools, top packs, and call volume over a recent window. The verb 'Returns' and resource 'trending data on Pipeworx' are specific. It distinguishes from siblings like discover_tools or ask_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?

Explicitly lists three concrete use cases (discovering hot data, confirming canonical tool, aligning use case). No explicit when-not-to-use, but context is clear. Window parameter effects are explained.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and idempotent. The description adds valuable behavioral context, such as the fill check mechanism that checks against live CLOB depth and warns when an opportunity is not realizable ('do not trade it'). It also explains semantic anchor and partition filter behaviors. 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 comprehensive but not overly verbose. It is well-structured: starts with the general purpose, then details each mode, and ends with response structure and fill check. Each sentence adds value. While it is relatively long, the density of information justifies the length. A slight trim could make it more concise, but it remains effective.

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

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

Given the complexity of the tool (two modes, fill check, response format), the description is very complete. It covers the input, behavior, and output (response: opportunities array, partition check). It explains edge cases like placeholders filtered and when to avoid trades. With no output schema, the description fully compensates by describing the return structure. It also references a sibling tool for customization.

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

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

The input schema provides 100% coverage with descriptions for both parameters. The description adds further semantics, explaining that 'event' expects a Polymarket event slug or URL, and 'topic' expects a seed question. It elaborates on the modes and what happens in each case, including details like 'walks child markets' and 'searches related events.' This adds significant meaning 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 the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with concrete examples, and the verb 'find' accurately captures the read-only nature. The purpose is specific and differentiated from siblings like 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: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It gives examples of event slugs and seed questions, and notes that event mode is preferred. It also directs users to polymarket_fill_risk for custom sizing, providing an alternative tool. This satisfies the 'when to use vs alternatives' requirement.

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 details behavioral aspects beyond annotations, including caching (1h at KV level), model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation (edge_pp_net after slippage), Kelly sizing (kelly_fraction capped at 0.25), 24h move warnings, and diagnostics. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is very long (multiple paragraphs) but well-structured with bold section headers for segments and knobs. It is front-loaded with the purpose. However, it could be more concise; some details (e.g., specific model parameters like alpha values) might be excessive for an AI agent's initial selection.

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

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

Given the complexity (9 parameters, no output schema, multiple model families), the description is thoroughly complete. It covers return segments (by_segment), diagnostics (_diagnostics with funnel counters), caching behavior, and exclusion notes (Fed bets). No gaps are apparent.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The tool description adds some context (e.g., explaining tradeable-edge knobs), but it does not significantly enhance parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets to find discrepancies between Pipeworx data and market prices, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection using multiple model families.

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 guidance on when to use (discovering opportunities without paging) and includes details on knobs for filtering (min_liquidity, max_spread_pp). However, it does not explicitly name alternative tools or state when not to use this tool, leaving some ambiguity for an AI agent.

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

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

The description goes beyond annotations by detailing behavior: it uses daily snapshots, computes trend and decay, returns tracked, expired, and snapshot_dates. It explains that decay is computed on the absolute edge_pp_net, signed by trade direction, and mentions limitations (60-day TTL, non-intraday data). 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 well-structured with clear sections (RESPONSE, LIMITS) and is concise given the amount of information. Every sentence adds value, though it could be slightly tighter.

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 return values (tracked, expired, snapshot_dates) with details on fields, trend, decay, and limitations. It explains the signed nature of edge_pp_net. Lacks explicit examples but is sufficient for an agent to understand tool usage and 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 description coverage is 100%, so the baseline is 3. The description adds context about default values and snapshot families ('1wk'), but does not significantly enhance understanding beyond the schema's parameter descriptions.

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

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

The description clearly identifies the tool's purpose: providing edge persistence and decay telemetry from polymarket_edges snapshots. It answers a specific question about edge duration and contrasts fresh vs. old edges, distinguishing it from siblings like polymarket_edges which likely provide current snapshots.

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

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

The description explains when to use the tool: to understand how long an edge has existed and if it is shrinking. It contrasts a fresh wide edge with a 3-week-old one, implying when not to rely on current edge data. Limitations about history depth and TTL are also provided. However, it does not explicitly name alternative tools for current edges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds detailed behavioral context (walks the ladder, returns verdict, warns about partial basket fills turning arb into directional position) 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 comprehensive but well-structured, with clear sections for single-market and basket modes. While lengthy, every sentence adds necessary detail. It could be slightly more concise, but the structure aids 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 complexity (two modes, many return fields) and the absence of an output schema, the description fully enumerates return values for both modes (top-of-book, VWAP, slippage, verdict, etc.) and warns about risks. No gaps identified.

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 significant value by explaining the dual modes (single-market vs. basket) for parameters like 'side', 'event', 'market', and 'size_usd', clarifying defaults and interpretation beyond the schema.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role.

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 provides when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial fills cause directional risk), making it easy for an agent to decide.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond annotations, including temporal alignment, skipped cross-type/subtype counters, and detailed explanations of compatibility_warning conditions. No contradictions are present, and the description greatly enhances 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?

The description is thorough but somewhat verbose. However, it front-loads the core purpose and uses clear structure (paragraphs for modes, response, safety fields). Every sentence adds value, so it earns a 4 despite length.

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

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

Given three optional parameters and no output schema, the description thoroughly explains the response fields (spread, compatibility_warning, temporal_alignment, counters) and edge cases. This ensures an agent can fully understand the tool's behavior and outputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by listing all topic shortcuts, describing explicit ticker examples, and explaining behavior across modes. This supplementary information justifies a score of 4.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymorph_arbitrage by focusing on comparative spreads and explicitly mentions two modes of operation. This specificity and differentiation earns the highest score.

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

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

The description provides explicit guidance on when to use the tool (comparing spreads across venues) and when not to, detailing compatibility_warning scenarios. It explains limitations of pre-mapped shortcuts and how to use explicit tickers. This comprehensive guidance ensures correct selection and invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about key listing behavior and scoping to an identifier, which adds value beyond the annotations.

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

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

Three concise sentences: first gives core function, second provides use cases and examples, third describes scope and companion tools. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description explains return behavior (value vs list of keys), usage context, scoping, and related tools. For a simple read-only tool with one optional parameter, it is fully complete.

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

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

Schema coverage is 100% and the schema description already explains the 'key' parameter. The description reiterates the dual behavior (retrieve vs list) but does not add new semantic information beyond the schema.

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

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

The description clearly states the verb 'retrieve' and the resource 'value previously saved via remember', and also lists all keys when omitted. It distinguishes itself from sibling tools by explicitly 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?

Explicitly states when to use ('look up context the agent stored earlier... without re-deriving it from scratch'), implies when not to use (save with remember, delete with forget), and names alternatives ('Pair with remember to save, 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: the mark_read flag modifies state (marking events read), and it explains the returned fields and filter capabilities, which go beyond the annotations.

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

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

The description is three sentences long, front-loaded with the main action, and efficiently covers purpose, return data, filtering, and mark_read behavior without any redundant or filler content.

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

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

Despite lacking an output schema, the description explains what each event carries. It covers all filter options, the mark_read side-effect, and even mentions an alternative access method. For a read-only tool with 5 optional parameters, this is complete.

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

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

The schema already provides descriptions for all 5 parameters (100% coverage). The description adds context for type (example 'sec_8k'), since (ISO timestamp), and the effect of mark_read, but these are minor improvements. Baseline 3 is appropriate.

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

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

The description clearly states it pulls fired events from a subscription feed. It specifies the return fields (source, citation_uri, raw payload) and distinguishes this tool from siblings like list_subscriptions and subscribe by focusing on reading alerts rather than managing subscriptions.

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

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

The description advises that polling works fine and mentions an alternative REST endpoint for scripts/dashboards, providing some usage context. However, it does not explicitly state when not to use this tool vs. sibling tools, though the context makes it clear it's for reading alerts.

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 it as read-only, open-world, idempotent, and non-destructive. Description adds fan-out behavior, source fallbacks, and soft-fail for USPTO patents.

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

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

Single paragraph is information-dense but well-organized with examples. Could be slightly more structured, but still concise for the amount of detail.

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, description explains return structure (changes grouped by source, total_changes count, citation URIs). Covers all key aspects for a 3-param 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 has 100% coverage. Description adds contextual examples for `since` (ISO/relative), explains `value` accepts ticker or CIK, and notes `type` is limited to 'company'.

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 provides a change feed for a company, listing SEC filings, news, and patents. Includes concrete query examples and distinguishes from sibling 'entity_profile'.

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

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

Explicitly tells when to use this tool vs. 'entity_profile', explains fallback from GDELT to GNews, and provides guidance on `since` parameter format.

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

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

Adds significant context beyond annotations: explains scoping by identifier, persistence differences between authenticated and anonymous users, and idempotent nature. No contradiction with annotations.

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

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

Four sentences, each serving a purpose: purpose, usage, scope/persistence, pairing. No wasted words, 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?

Simple tool with clear needs; description covers purpose, when to use, persistence, and relations to other tools. Complete 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 coverage is 100%, but description adds value by providing naming conventions (e.g., 'subject_property') and explaining value as 'any text'. Gives examples that aid 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?

Description clearly states 'Save data the agent will need to reuse later' with specific verb (save) and resource (key-value pair). It distinguishes from sibling tools by mentioning recall 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?

Explicitly states when to use: 'when you discover something worth carrying forward' with examples. Also provides pairing instructions and notes on persistence (authenticated vs anonymous sessions).

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, openWorld, and non-destructive behavior. The description adds substantial behavioral context: it cascades through multiple endpoints, degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), returns unresolved identifiers explicitly, and labels sources. 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 clear purpose and examples, but it is somewhat verbose, including detailed internal cascade and graceful degradation explanations. While every sentence adds value, the length could be trimmed slightly without losing essential information. Still 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?

Given the tool's complexity (two entity types, multiple data sources, cascading lookups, graceful degradation) and the absence of an output schema, the description covers all necessary aspects: it explains what identifiers are returned for each type, mentions unresolved identifiers, labels sources, and describes behavior when services are unavailable. This is comprehensive for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value beyond the schema by explaining what each type returns (company returns CIK, ticker, LEI, FIGI, etc.; drug returns RxCUI, ingredient, brand) and providing example inputs (ticker, CIK, ISIN, names). It also clarifies that ISIN resolves to the legal entity, which is not obvious from 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 resolves a user-spoken name to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID', positioning it as the primary name-to-ID tool among many research and entity 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?

The description provides explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives concrete query examples. However, it does not explicitly mention when NOT to use it or name alternative tools from the sibling list (e.g., entity_profile, compare_entities) for cases where more than an ID is needed.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it probes with ai_visibility_check, ranks, and returns score/confidence/signal density. 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?

Two sentences, front-loaded with action verb and resource, no wasted words.

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

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

No output schema, but description fully explains return structure. All parameters mentioned, references sibling tool, explains process (probe, rank, surface). Complete for its function.

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. Description adds value by clarifying first entity as 'subject' and explaining shared context disambiguates names, beyond 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?

Clearly states it compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, and ranks results. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 useful for competitive AI-marketing audits. Implies use when comparing multiple entities, but does not explicitly state when not to use or mention alternatives like single-entity check.

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 multiple behaviors: composite call, partial degradation with sources_failed list, and the 5-30 second delay for bundlephobia on new versions. The annotations already show readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description adds complementary context without contradiction.

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

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

The description is moderately sized but packed with essential information. It is front-loaded with the core purpose and covers alternatives, partial failures, and environment details. Minor redundancy exists but does not detract significantly.

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 thoroughly explains the return structure (summary block, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures and timeouts, making it nearly self-contained 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?

Both parameters are fully covered by the input schema (100% coverage). The description adds useful context: scoped packages accepted for 'package' and defaulting to latest for 'version'. This exceeds the baseline of 3 by providing extra semantic 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 specifies exactly what the tool does: a composite check for npm packages covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It clearly distinguishes from siblings by limiting to npm and mentioning alternative tools for other ecosystems.

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

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

Explicitly states when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies when not to use: for PyPI/Maven/Cargo/Go it should fall under deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds details on return fields and sort behavior, which is consistent and slightly extends 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?

Concise and well-structured: purpose first, then filters, sort examples, and return fields. 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 rich schema, annotations, and output schema, description covers all essential aspects completely. No gaps.

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

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

All 8 parameters are documented in schema with descriptions. Description adds concrete usage examples and explains sort options with real-world queries, going 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 clearly states it searches DataCite-registered DOIs for research outputs, listing specific filters and sort options. It distinguishes itself from sibling tools like 'get_doi'.

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 guidance on filtering (query, resource type, year, etc.) and sorting with examples. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare safety hints (readOnlyHint, idempotentHint). The description adds valuable behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping), cap (200K chars with truncation flag), and output structure (offsets and similarity scores). No contradiction with annotations.

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

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

The description is dense and informative, but slightly verbose as a single paragraph. It could be broken into shorter sentences for easier parsing. However, 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 has 3 parameters, no output schema, and full schema coverage, the description provides complete information: algorithm, constraints, and usage context. The agent will know exactly how and when to use it.

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

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

Schema coverage is 100%, but the description adds context beyond field descriptions: embedding algorithm, window size, character limit, and example queries. It explains how the search works internally, which the schema does not.

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 semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It distinguishes itself from siblings like ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 important behavioral traits such as requiring a Pipeworx OAuth account, SMS daily cap, webhook auto-disable after failures, and webhook signing. These go beyond the annotations (which indicate idempotent and non-destructive) and help the agent understand side effects and constraints.

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

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

The description is well-organized with clear sections for purpose, types, and delivery. It is somewhat long but every sentence adds value. Minor redundancy could be trimmed, but overall structure is effective.

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

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

The description covers all key aspects: core functionality, type-specific parameters, delivery channels with constraints, and authentication requirements. Given the complexity of the tool and lack of output schema, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial meaning with detailed examples, required fields, format constraints, and webhook details. It explains the meaning of each type and param far beyond the schema's basic 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 creates a subscription to a live-data event stream and returns the id. It lists specific supported types and examples, differentiating from siblings like list_subscriptions and unsubscribe.

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

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

The description implies when to use (to set up proactive monitoring) and provides context about required account type. It does not explicitly state when not to use or list alternatives, but the context is clear given the title and sibling tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, making the safety profile clear. The description adds that this is the 'onboarding entry point' and returns 'category-bucketed example questions', which provides useful 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?

The description is somewhat long but well-structured, starting with common user queries as triggers, then explaining the output and parameter usage. Every sentence adds value, though it could be slightly more concise without losing meaning.

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

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

Given the tool's role as an onboarding entry point and the rich annotations, the description covers purpose, usage, parameters, and output shape (category-bucketed examples with tool+argument shapes). No output schema exists, but the description adequately explains the return value.

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 description for the one optional parameter. The description adds nuance: topic values like 'finance', 'pharma', etc., and explains behavior when omitted ('cross-category spread'), going beyond the schema's basic description.

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

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

The description explicitly states the tool returns 'category-bucketed example questions' with exact tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists 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?

The description provides clear guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic vs no arguments, covering both use cases.

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 non-read-only, non-destructive, idempotent. Description adds ownership enforcement, deactivation (not deletion), and link to recent_alerts, providing full 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?

Two sentences, no unnecessary words, efficiently communicates key points.

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 parameter, no output schema, annotations present), the description covers all necessary context: ownership, side effects, and relation to other tools.

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 the single parameter 'id' fully with description. The description doesn't add additional parameter semantics 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' with the specific resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation not deletion, historical events remain via recent_alerts). It provides good context but doesn't explicitly mention when not to use or alternative tools.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds significant context by explaining the meaning of each verdict (especially the crucial distinction between could_not_verify and unsupported), the structured vs. grounded pipeline, and the presence of verification_error. Goes well beyond annotations and is not contradictory.

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?

Slightly verbose but well-structured: triggers, usage, pipeline, outputs, and important caveats. Every sentence contributes value, but the description could be trimmed without losing key information. Front-loaded with trigger phrases and clear purpose.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers the return verdict types, meaning, special error cases, citation format, and even explains the efficiency gain. It provides enough detail for an agent to know what to expect and how to interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances tolerance_pct by explaining it overrides implied tolerances and suggests specific values (1–2) for hallucination detection, adding practical guidance beyond the schema. Claim parameter is inherently clear from the schema and description.

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

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

The description explicitly states the tool's function with verbs like 'validate', 'fact check', 'verify' and a clear resource ('natural-language claim'). It distinguishes itself from siblings by explaining it performs end-to-end claim verification and replaces 4–6 sequential calls, setting it apart from simpler search or ask tools.

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

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

Provides explicit guidance on when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and describes the routing behavior for financial vs. other claims, plus important semantics for verdicts. It effectively communicates usage context and differentiation from alternative tools.

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