The Guardian

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

Annotations (readOnlyHint, idempotentHint) are consistent. The description adds behavioral details: default model, BYO key for Anthropic, billing implications, return structure (score, confidence, signals, raw_response). This adds 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 two sentences, front-loaded with key action, and contains no superfluous words. It efficiently conveys purpose, behavior, and use 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 no output schema, the description adequately explains return fields and use cases. It lacks details on error handling or rate limits but is sufficient 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%, but the description enhances parameter understanding: it explains 'entity' as the thing to ask about, 'models' as model selection with defaults, '_apiKey' as optional pass-through, and 'context' for disambiguation. This adds value 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?

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility. It uses specific verbs ('probe', 'score') and resources (LLMs, entity), and distinguishes from siblings like 'ask_pipeworx' which are for general Q&A.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the API key for Anthropic. It implicitly differentiates from sibling tools but does not explicitly list when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond this: it routes to 5,529 tools, fills arguments, returns citation URIs, works on every tier, and is a single fast call. No contradiction with annotations; the added detail about stable citations and default entry point enriches 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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and remains well-structured throughout. It is longer than average due to many examples and alternative comparisons, but nearly every sentence earns its place by conveying scope, usage, or exclusions. Only minor trimming could be done 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?

Despite lacking an output schema, the description fully equips the agent: it specifies the tool's broad scope, how to phrase questions, when to escalate to alternatives, and even mentions limitations ('what's the world saying about X' is handled by routing to live news). Given the tool's complexity and all available structured metadata, the description is complete for effective selection and invocation.

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

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

The input schema is fully described (100% coverage) with the main 'question' parameter and aliases. The description adds value by providing numerous concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and clarifying that the tool accepts 'query, q, prompt, text, input as aliases.' It also mentions the tool 'fills arguments,' which helps the agent understand the parameter's role, though specific syntax details remain in the schema.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It also positions itself as the default entry point ('START HERE') and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research by describing their different roles.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data...' and lists trigger phrases like 'what is', 'look up', 'find'. It also provides when-not-to-use and alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is exemplary usage differentiation.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the beta nature, live candidate routing improvements, the current inactive candidate status, and the fact that results are compared against the stable router. It also clarifies that it is a full working router with no fallback, 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?

Three sentences, each carrying essential information: beta identity, current state, and usage guidance. Front-loaded with the key distinction from the stable version, and no filler or redundancy.

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

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

Given the simple input schema, absence of output schema, and strong annotations, the description fully covers the beta status, current behavior, and comparison purpose. It mentions same response shape, which addresses return semantics, and explains the experimental nature completely.

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

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

The schema already covers all 6 parameters with 100% description coverage, including aliases for 'question.' The description adds only 'same arguments' as ask_pipeworx, which adds no new 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 identifies ask_pipeworx_beta as a beta version of ask_pipeworx with identical functionality (same tools, arguments, response shape) and explains its experimental routing role. It distinguishes from siblings by explicitly naming ask_pipeworx as the stable counterpart and noting this tool is the experimental edge.

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

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

The description gives explicit when: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable router as an alternative, but does not explicitly state when NOT to use it (e.g., 'if you need stability, use ask_pipeworx'). The current no-candidate state is mentioned, which further clarifies usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, but the description adds substantial context: the tool returns an explicit refusal with specific refusal_reason values (not_in_source, no_tool_match, etc.) when data doesn't answer, and it includes verbatim evidence quoting. It also discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it covers the core purpose, the internal routing mechanism, the structured output and refusal format, explicit usage examples, and cost trade-off. It is front-loaded with the key phrase 'hallucination-resistant answer mode' and remains tight despite its 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?

Since there is no output schema, the description fully specifies the return value shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and enumerates all possible refusal reasons. It also covers when to use, when not to use, and the alternative tool, making it self-sufficient for an agent to invoke correctly.

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

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

The input schema has 100% description coverage for all six parameters (all aliases for 'question'), so the schema already explains the parameter semantics. The description does not add parameter-specific detail beyond stating that the tool accepts a natural language question, which is consistent with the schema. Baseline of 3 applies.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and specifies the exact behavior: it routes like ask_pipeworx, picks a tool, fetches data, and extracts answers using only the tool result. It distinguishes from sibling ask_pipeworx by emphasizing the grounded extraction and refusal mechanism, 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?

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims, medical lookups). It also provides a clear exclusion: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off of one extra LLM call, giving the agent actionable decision criteria.

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

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

The description reveals numerous behavioral details beyond the simple annotations, including response shapes, resolver contract, fallback mechanisms, cancellation rule parsing, and safety short-circuits. It even warns about potential edge cases like wide spreads and resolution rules. Annotations confirm read-only, idempotent, open-world behavior, and the description aligns perfectly without 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?

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds value, covering necessary intricacies. However, it could benefit from slight trimming to improve readability while retaining critical details.

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

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

Given the complexity (3 parameters, no output schema), the description provides comprehensive context on usage, expected outcomes, edge cases, and safety measures. It covers resolver contract, parent event extraction, fallback handling, and resolution rules, leaving no major gaps for an agent to understand how to invoke and 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 the baseline is 3. The description does not add significant meaning beyond the schema's own descriptions for the three parameters. While the extensive context indirectly informs usage, no additional parameter-level details are provided in the description text beyond what is already in the schema.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question) and output types (evidence packet, comparison), making the purpose unmistakable. While sibling tools like polymarket_edges exist, the unique scope and integration details differentiate it effectively.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive examples covering different bet categories. It also includes blocking conditions (low-confidence match, closed markets). However, it does not explicitly contrast with sibling tools or state when not to use it, leaving some ambiguity for tool selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; description adds orthogonal behavioral details: parallel execution, correct handling of off-calendar fiscal years, sorted results, and citation URIs. 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?

Every sentence adds value. Front-loaded with examples and core purpose. Despite length, each clause earns its place—no filler or repetition.

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

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

Despite no output schema, description fully covers return structure: paired data, sorted by primary metric, citation URIs per entity. Adequately compensates for missing output schema. Tool is simple (2 params) and description covers all necessary 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 description adds significant meaning: explains mapped data sources for each 'type' enum (company→SEC XBRL, drug→FAERS/FDA) and value formats (tickers/CIKs vs drug names). Goes well 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?

Describes a specific verb+resource: side-by-side comparison of 2-5 companies or drugs. Distinguishes from sibling tool 'entity_profile' by emphasizing parallelism and data types (SEC data vs FAERS/FDA data).

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

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

Provides explicit context: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example queries. Does not explicitly state when not to use (e.g., single entity), but context strongly implies it.

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

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

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: account requirements, paid plan, expected latency (15-60s, up to ~90s), that it never invents gaps, returns citations only when fetchable, how depth affects recovery passes, contradictions[] availability, semantic excerpting, and hop fields. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place—covering prerequisites, alternatives, use cases, return format, citation guarantees, and timing. It is front-loaded with the most critical caveat (account required) and alternative. Structure is logical, flowing from purpose to exceptions to details, making a long text navigable.

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 payload: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', gaps[], contradictions[], hop field, and excerpting behavior. It also covers prerequisites, pricing, and expected response times. For a complex tool, this is complete and self-sufficient.

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

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

Schema coverage is 100%, but description goes further by explaining the depth parameter's behavioral impact ('quick=3 (single hop)... standard=5... thorough=8') and clarifying that the question parameter supports 'broad/multi-part' queries because decomposition is the point. It also explains the gap-recovery and contradiction-scanning semantics of depth values.

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

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

The description clearly states the tool conducts 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with a specific verb and resource. It explicitly distinguishes from siblings (e.g., 'this is NOT open-web search', 'For a single lookup use ask_pipeworx') and names the exact use case: broad/multi-part questions over structured data.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even handles the not-signed-in alternative. It also provides depth-specific recommendations (standard vs thorough).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradiction.

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

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

The description is informative and well-structured: it starts with the core purpose, lists supported domains, explains the return format, and ends with usage advice. While slightly verbose, every sentence adds value, so a 4 is appropriate.

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 6 parameters (100% schema coverage), no output schema, and no nested objects, the description covers purpose, usage, return format, and examples adequately. It mentions 'top-N' and the limit parameter is in schema. Complete 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 description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema, only mentioning 'natural language description' and aliases. The schema itself provides examples, but the description adds little extra.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explicitly differentiates from siblings by advising 'Call this FIRST when you have many tools available.'

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and provides strong guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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. The description adds that it returns edition IDs and hostnames, which is useful but not rich. No contradiction.

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

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

The description is two concise sentences that efficiently convey purpose, output, and usage. 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 output schema exists and the tool is simple, the description covers purpose and usage adequately. However, it omits explanation of the 'q' parameter, leaving a gap in completeness.

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

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

The schema has one parameter 'q' with 0% description coverage. The description does not mention 'q' at all, failing to explain its purpose (filtering?) as suggested by the example. The description should compensate for the missing schema docs but 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 verb 'List', the resource 'The Guardian's geographic editions', and lists specific editions. It also mentions returns edition IDs and hostnames, which distinguishes it from sibling tools like 'sections'.

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: 'Use to discover edition-specific content streams before filtering search() by edition.' This provides clear context. No exclusions are needed given the simplicity.

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 behavior, but the description adds substantial detail: fans out across multiple sources, returns specific fields (cik, filings with URIs, fundamentals sorted, patents sunset note, news fallback), exceeding the annotation baseline.

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 front-loaded with examples. While lengthy, every sentence serves a purpose; minor structural improvements could enhance readability, 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 tool's complexity and lack of output schema, the description comprehensively details return fields, source behavior, soft-fail mechanisms, and cross-references to sibling 'resolve_entity', fully preparing the agent.

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

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

With 100% schema coverage, baseline is 3. The description adds practical examples for values ('AAPL', '0000320193') and clarifies type support ('Only "company" supported today'), slightly improving usability.

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

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

The description uses numerous example queries like 'Tell me about X' and explicitly states 'full cross-source profile of a US public company in ONE parallel call,' clearly defining the tool's purpose and distinguishing it from siblings like 'resolve_entity' and chain lookups.

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

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

Explicit guidance to 'ALWAYS PREFER over chaining single-pack... lookups' for holistic views, and clear indication that names are not supported ('use resolve_entity first'), providing when-to-use and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. It adds usage context but no additional behavioral traits beyond what annotations convey.

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

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

The description is two concise sentences, front-loading the purpose and following with usage guidance and sibling references. No information is repeated or wasted.

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 deletion tool with one parameter and no output schema, the description covers purpose and usage. However, it omits expected return behavior (e.g., success/failure) and error cases, which would enhance completeness.

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 'Memory key to delete.' The description says 'by key' but adds no extra semantic detail beyond the schema's definition.

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 'Delete a previously stored memory by key,' which precisely identifies the action (delete) and resource (memory). It distinguishes from siblings like 'remember' and 'recall' by including 'Pair with 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?

The description provides clear guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names alternatives (remember, recall) for context.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds detail about fetching, extracting, and emitting markdown. It enhances 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?

The description is a well-structured paragraph that efficiently conveys purpose, output, and use cases. It is informative without being overly verbose, though a bit more conciseness could improve it.

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 (2 params, no output schema, no similar siblings), the description fully covers purpose, parameters, output format, and practical applications. No gaps remain.

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

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

Schema descriptions cover both parameters (100% coverage). The description adds context on max_links default/max values and the nature of the URL parameter. It provides meaningful addition 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 generates a llms.txt file for a URL, specifying the output format and use cases. It effectively distinguishes itself from siblings as no other tool performs this specific function.

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

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

The description gives explicit use cases (indexing a client's site, drafting own llms.txt, auditing competitor) but does not provide when-not-to-use or alternatives. The guidelines are clear and contextual.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by detailing what is returned (full body text, tags, related elements, references), which is not in the schema. No contradictions.

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

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

Two sentences, front-loaded with action and parameter, then usage context. No extraneous words, every sentence provides value.

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

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

With an output schema present, return value details are less critical. Annotations cover safety. However, the description fails to explain four optional parameters, which is a significant gap. Completeness is adequate for a simple fetch tool but not fully informative.

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 0%, so the description must explain parameters. It only mentions 'content ID' in text, leaving show_tags, show_blocks, show_fields, and show_references unexplained. The schema examples provide some context, but the description doesn't compensate for the lack of schema descriptions. Agent would not know the meaning or values of optional parameters.

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

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

The description clearly states it fetches a single article by content ID and lists returned data (full body text, tags, etc.). It distinguishes from sibling 'search' by specifying usage after a search. Very clear verb+resource+scope.

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

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

Explicitly says 'Use after search returns an article you want the full text of', providing clear context. No explicit when-not or alternatives beyond search, but enough guidance for typical use.

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

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

Annotations already cover safe read behavior (readOnlyHint, idempotentHint, destructiveHint). Description adds return fields but not much beyond annotations.

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

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

Two sentences, front-loaded with main purpose. No fluff. Efficient and clear.

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

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

Simple tool with one optional boolean param, no output schema. Description covers purpose, return fields, and usage context. Annotations cover safety. Complete.

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

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

Schema covers parameter description at 100%. Description does not add additional semantics beyond what schema provides.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields. Distinguishes from siblings like subscribe/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?

Provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' No explicit alternatives but sibling context suffices.

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 give four negative hints (not read-only, not idempotent, etc.), so description carries the burden. It discloses the claim_token workflow, rate limit (5/day), that it's free, and that digests are read daily — all beyond what annotations provide. A 4 is fair because it doesn't explicitly state that filing creates a persistent record, though that is strongly implied.

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, use cases, exclusion condition, content guidelines, claim_token flow, and rate limit. The structure front-loads the core action and then progressively narrows to operational details — no redundancy, no fluff.

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

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

No output schema, but the description explains return behavior (claim_token, later status read). It covers all operational aspects: when to use, what to include, what not to include, rate limiting, and cross-server handling. For a feedback tool, this is fully specified.

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. Description adds workflow context for claim_token (how to use it to read the reply later) and message guidance ('don't paste the end-user's prompt', 'describe in terms of Pipeworx tools/packs') that enriches parameter usage beyond the schema definitions.

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

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

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the feedback tool from sibling research/search tools, and the scope ('Pipeworx tools/packs') is unambiguous.

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

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

Provides explicit when-to-use criteria for each feedback type (bug, feature, data_gap, praise) and an explicit exclusion: tools from other MCP servers should be filed elsewhere. Even gives a decision rule for uncertainty ('Pipeworx tool names are the ones this connection lists'). This is textbook usage guidance.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds valuable context: self-aggregating signal, no PII, cached 5min-1h depending on window, data source (CF analytics-engine). 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?

Well-structured with purpose first, then bullet uses, then detail. Could be slightly more concise but 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 no output schema, the description covers usage, behavior, data source, and caching. The return format (lists and counts) is implied and sufficient for this straightforward tool.

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

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

Schema description coverage is 100% for the single parameter 'window'. Description adds context on window meaning (shorter for hot, longer for steady-state), which is useful beyond the enum values.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings like 'discover_tools' by focusing on trending data sources and call volume.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case). Explains window implications (shorter for hot, longer for steady-state). Lacks explicit 'when not to use' or direct alternatives among siblings.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safety, but the description adds extensive behavioral detail: scanning top ~200 markets, partition sum logic, semantic anchor (Jaccard similarity ≥ 0.30), placeholder filtering, and fill check against live CLOB depth. No contradiction with annotations.

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

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

The description is lengthy but well-structured: a concise opening sentence, then clear sections for each mode and technical details. Every sentence adds value, though a minor trimming could improve conciseness. Still, it is appropriately detailed for a complex tool.

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

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

Despite no output schema, the description fully explains the response structure (opportunities[], partition_check, fill_check with specific fields). It covers edge cases (placeholder filtering, low similarity), and references a sibling tool (polymarket_fill_risk) for custom sizing. Complete for the tool's complexity.

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

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

Both parameters have schema descriptions, but the tool description adds significant context: examples of event slugs and topic seeds, explanation of what each mode does, and that full URLs are accepted. This goes well beyond the schema.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no-args trending scan, event mode, topic mode) and differentiates from sibling tools that cover edges, fill risk, and spreads.

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 instructions for when to use each mode: 'Call with NO args for a trending_scan... pass event for strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets. Also warns when not to trade (fill check with realizable_edge_pp ≤ 0).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only tool. The description adds substantial behavioral context: caching (1h at KV level keyed on knobs), response structure with by_segment and diagnostics, and details about edge calculations (e.g., slippage subtracted, 24h-move warning). 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 very long but well-structured with clear segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and explanations. While every sentence adds value, it could be more concise for quick agent parsing. However, given the complexity of the tool, 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?

Despite no output schema, the description fully documents the return structure: top-level by_segment with model_driven, structural_arbitrage, concentrated_longshot, fed_candidates, fed_note, and _diagnostics. It explains edge details (edge_pp_net, kelly_fraction, etc.) and diagnostics for empty segments. This is highly complete for a tool with 9 parameters.

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 9 parameters described. The description adds meaning beyond the schema by explaining tradeable-edge knobs (min_liquidity, max_spread_pp), default values, and why certain parameters exist (e.g., min_partition_leg_kelly for partition arbs). It also provides context for defaults and use cases.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb (scan) and resource (Polymarket markets) and distinguishes itself from sibling tools by focusing on the disagreement with Pipeworx data, which is unique among the sibling names.

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 includes a usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives guidance on when to use parameters like min_liquidity and max_spread_pp. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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 crucial details: snapshot source, 60-day TTL, decay computation from daily closes (not intraday), and output structure. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage context. It is moderately long but every sentence adds necessary detail about behavior, output format, and limitations. 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 no output schema, the description comprehensively covers the return structure (tracked, expired, snapshot_dates), field meanings (edge_pp_net signed, trend classification, decay rate), limits, and data source. All essential information is present.

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 additional explanation for 'days' (default, max) and 'window' (snapshot family examples). While schema already covers basics, the extra context about window options ('24hr | 1wk | 1mo') adds value.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge duration. It distinguishes itself from siblings like polymarket_edges by focusing on historical time series.

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

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

The description gives strong context for when to use (e.g., distinguishing a new edge from an old one) but does not explicitly list when not to use or directly compare with sibling tools. The sibling list provides context but no exclusions.

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

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

Description adds significant behavioral context beyond annotations: walks the ladder, returns verdicts (clean/degraded/cannot_fill), explains that partial basket fills create directional risk, and mentions dominant loss mode. Annotations already indicate readOnly, idempotent, etc., and description aligns with them.

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

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

Well-structured with bold headings for modes. Front-loaded with purpose. Somewhat verbose (e.g., 'the dominant loss mode in real arb-bot P&L') but still efficient given complexity.

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

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

No output schema, so description must cover return values and does so comprehensively for both modes. Includes edge cases (thin books, partial fills) and warnings. 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 coverage is 100%, but description adds meaning: explains defaults, interprets size_usd for buys vs sells, details side auto-detection for basket, and defines settlement notional. Adds value beyond raw schema.

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

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

Description clearly states it is a risk check against live order-book depth, differentiating single-market and basket modes. Uses specific verb 'check' and resource 'edge vs realizable fill'. Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about partial basket fills converting arb into unhedged position, which is a critical when-not-to-use 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 indicate readOnly, idempotent, non-destructive. Description adds significant behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped counter explanations. 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 detailed yet concise. It front-loads the purpose, then logically explains modes, response fields, and safety fields. Every sentence adds value without redundancy.

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

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

Given no output schema, the description thoroughly explains response fields including leg-by-leg prices, spreads, compatibility warnings, temporal alignment, and skipped counters. Parameters and usage are fully covered.

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

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

Schema coverage is 100% with descriptions. Description elaborates on the two modes, lists the 10 topic shortcuts, and explains that explicit tickers override the topic. This adds meaning beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same question, with two modes (topic shortcuts and explicit tickers). It effectively distinguishes itself from siblings like polymarket_arbitrage by focusing on multi-venue comparison.

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

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

The description explains when to use the tool (to compare prices across venues) and provides explicit warnings about compatibility issues and that most shortcuts currently return warnings. It lacks mention of alternative tools for single-venue analysis but overall gives good guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds context about scoping to identifier and pairing with other tools, without contradicting annotations. Could be improved by mentioning return format for missing keys, but not required.

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 primary action and alternative. No wasted words. Each clause adds meaningful information: retrieval behavior, listing behavior, use cases, scope, and pairing.

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

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

For a simple tool with one optional parameter and no output schema, the description covers functionality, use cases, scope, and relationships to siblings. It is complete as is.

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 single parameter 'key' is fully described in schema (100% coverage), and the description adds value by explaining that omitting it lists all keys and providing context on what keys represent (user's target ticker, address, notes).

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 retrieves values saved via remember or lists all keys when the key argument is omitted. It gives concrete examples of what can be looked up (ticker, address, notes), and distinguishes it from sibling tools 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 says when to use (look up context stored earlier) and when to omit argument (list all keys). Mentions scope and pairs with remember/forget, providing clear alternatives and context 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?

Description states that setting mark_read:true flags events as read, implying a side effect, which contradicts the readOnlyHint annotation (true). The readOnlyHint annotation suggests the tool never writes, but the description allows a write operation. This is a direct contradiction.

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

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

Description is reasonably concise for the amount of information conveyed. It front-loads the purpose and then provides parameter details and usage notes. No redundant sentences.

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

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

No output schema, yet description covers return value (source, citation_uri, payload). It mentions polling behavior and an alternative endpoint. Lacks pagination details beyond limit, but limit itself is covered. Overall adequate for a read-like 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%, baseline 3. Description adds value by explaining the typical use of each parameter: filtering by type/since, limiting, marking read, and unread_only. The mark_read explanation is especially informative about its effect on future calls.

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 verb 'pull' and resource 'fired events from your subscription feed.' It distinguishes from siblings like 'list_subscriptions' (subscriptions list) and 'search' (general search). Specific mention of filtering by type and since adds precision.

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 indicates when to use (to retrieve recent alerts) and mentions polling suitability and alternative GET endpoint for scripts/dashboards. However, it does not explicitly contrast with siblings that might also retrieve events (e.g., 'search').

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. Description adds valuable context: fans out to multiple sources, soft-fails on USPTO, returns structured changes with citations. No contradictions.

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

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

Description is well-front-loaded with example queries and structured. Every sentence adds value, though slightly lengthy but appropriate for the tool's complexity.

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

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

Covers return format (grouped changes, count, URIs), limitations (USPTO soft-fail), fallback logic, and contrasts with sibling tool. All user needs are addressed.

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%. Description enhances each parameter: explains since accepts ISO/relative and suggests default, clarifies type only supports company, and describes value as ticker or CIK.

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 provides a change feed for a company in a time window, covering SEC filings, news, and patents. It includes example queries and distinguishes from sibling tool entity_profile with explicit differentiation.

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

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

Provides explicit when-to-use examples (e.g., "What's new with X") and when-not-to-use (static profile should use entity_profile). Also explains fallback logic between GDELT and GNews.

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

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

Annotations provide idempotentHint, readOnlyHint, destructiveHint. Description adds scoping by identifier, persistence differences between authenticated and anonymous sessions (24hr). 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?

Five sentences, no fluff, purpose first, then usage guidance, then behavioral details. Efficient and well-organized.

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?

Tool is simple with 2 params and no output schema; description explains storage, scoping, persistence, and pairing with recall/forget. Complete for agent understanding.

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; description adds context with example keys and value types, complementing schema. Baseline 3, plus extra value.

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

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

Description clearly states it saves data for reuse, gives concrete examples (resolved ticker, target address, etc.), and distinguishes from siblings 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 discovering something worth carrying forward) and mentions companion tools recall and forget for retrieval and deletion.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses important behaviors: identifiers are labeled by source, unresolved identifiers are explicitly stated under `unresolved`, and GLEIF/OpenFIGI failures degrade gracefully while EDGAR data still returns. This adds significant context not available in 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 detailed but each sentence adds value: example queries, supported types, source labeling, unresolved handling, graceful degradation, and replacement of manual lookups. It is slightly dense and could benefit from paragraph breaks, but it remains appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (cascading lookups, multiple identifier sources, no output schema), the description covers inputs, outputs, source attribution, unresolved identifiers, fallback behavior, and the use case. It provides enough context for an agent to understand return values and constraints without an output schema.

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

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

The schema already provides 100% coverage for both parameters, including examples and the distinction between company and drug inputs. The description reinforces this but does not add new parameter-level semantics beyond what the schema already documents, so the baseline 3 applies.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with explicit examples of user queries and supported entity types (company, drug). It distinguishes from sibling tools like entity_profile or search by emphasizing 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also clarifies input expectations for company vs. drug. However, it does not explicitly mention alternative tools to use instead, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds concrete behavior: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and specifies return fields (score, confidence, signal density). No contradictions.

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

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

Three sentences with no fluff. First sentence states purpose, second explains process, third gives a concrete example. Every sentence earns its place.

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

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

No output schema exists, but the description adequately explains the return format (ranked list with score, confidence, signal density). Parameters are fully covered by schema and additional semantic hints. The description is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the first entity is the 'subject' and rest are competitors, and that context disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' using a specific verb and resource. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by emphasizing the side-by-side comparison for competitive audits.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It does not explicitly list when not to use or alternative tools, but the context strongly implies 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?

Beyond the read-only, idempotent, non-destructive annotations, the description discloses important behavioral traits: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timeouts. No contradictions with annotations.

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

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

The description is a single paragraph that is well-structured and front-loaded with the main purpose. Every sentence adds value, though it is somewhat lengthy. It could be slightly more concise, but it is not wasteful.

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

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

Given the lack of an output schema, the description thoroughly explains the returned data: summary block fields, per-advisory details, links, and alternative versions. It also covers error handling (partial failures) and timing, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema already provides for 'package' and 'version'. The notes about scoped packages and default version are already in 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: a composite check for npm packages, fanning out to deps.dev and bundlephobia. It uses specific verbs like 'check' and specifies the resource. It distinguishes from siblings by naming the exact sources and the context (npm ecosystem).

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

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

Explicitly tells when to use: when agent asks about safety, popularity, size, or cost of adding an npm package. It also notes the scope (npm only in v1) and directs to alternatives (deps.dev:version for other ecosystems).

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 the source being a UK newspaper and optional full body text, but no behavioral details beyond what annotations cover. 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: first states purpose and outputs, second provides usage guidance. No wasted words, front-loaded with critical information.

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

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

Given complex schema (11 params), presence of output schema, and detailed annotations, the description gives a solid high-level understanding. It covers the main filters and return fields, though it does not enumerate every parameter. The output schema handles detailed return structure, so this is sufficient.

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

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

Schema has 11 parameters with 0% description coverage. The description mentions key filters like keyword, section, tag, date range, and notes optional full body text. However, many parameters (e.g., page, page_size, show_tags, show_elements) are not explained. The examples partially compensate, but overall the description adds moderate value beyond obvious parameter names.

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 'Search The Guardian newspaper archive... for articles by keyword, section, tag, or date range. Returns headlines with author, section, publication date, web URL, and optional full body text.' This provides a specific verb (search), resource (Guardian archive), and outputs, distinguishing it from sibling tools like 'search_within' or general news 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 explicitly advises 'Use for "Guardian coverage of X" or UK/EU-perspective news on world events.' This gives clear context for when to choose this tool over siblings, and implies it is not for non-Guardian or non-UK/EU news.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds rich behavioral details: embedding model (BGE-base-en), similarity metric (cosine), chunk size (500-char overlapping windows), character cap (200K with truncation and flagging), and output structure (passages with offsets/scores). This fully informs the agent of side effects and limitations.

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 yet informative, covering purpose, usage, and technical details in a few sentences. It front-loads the core action ('Semantic search INSIDE a fetched record') and then adds context. Slightly verbose with the embedding detail 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?

Without an output schema, the description adequately explains the return value (passages, offsets, similarity scores) and constraints (200K char limit, truncation flag). It also conveys the integration with ask_pipeworx_grounded, providing a complete picture for tool selection and 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 description coverage is 100%, so baseline is 3. The description reinforces the schema's parameter descriptions but does not add significant new semantic information. The natural-language query usage is already implied in the schema description.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples like SEC 10-K and articles. It distinguishes the tool from siblings by emphasizing its role in reducing context size and pairing with ask_pipeworx_grounded. The purpose is specific and actionable.

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

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

The description explicitly advises using this tool when a record is too large for a prompt, providing a clear use case. It also mentions pairing with ask_pipeworx_grounded for grounded analysis. However, it does not specify when not to use it or list alternative tools for other 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description confirms the tool is read-only and lists sections, adding minimal behavioral context beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with the main purpose and examples. No wasted words; every sentence adds value.

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

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

The tool is simple with one optional parameter. An output schema exists, so detailed return value documentation is unnecessary. The description covers the essentials: listing sections, optional filtering, and the purpose of the output for use in search.

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 0%, but the description adds meaningful context for the 'q' parameter, explaining it filters by name substring. This compensates for the lack of schema documentation, though it does not provide full details like case sensitivity or exact matching.

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 states it lists The Guardian's content sections, provides examples, and mentions optional substring filtering. It also specifies that it returns section IDs and titles, indicating the purpose clearly. However, it does not explicitly distinguish from sibling tools like 'editions' or 'tags', so not a 5.

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 explains the optional filtering via 'q' and states the output is for use as filters in search(). This gives some usage context. However, it does not mention when not to use it or suggest alternatives like 'editions' for date-specific sections, which would improve guidance.

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

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

Annotations declare the tool is not read-only, not destructive, idempotent, and open-world. The description adds significant behavioral context: it explains the need for authentication, the persistence of subscriptions, delivery channel constraints (e.g., SMS verification and cap, webhook auto-disable after failures), and the return value (subscription id). 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 front-loaded with the tool's purpose and key requirements. While it is relatively long, nearly every sentence adds essential information for correct usage. Minor redundancy could be trimmed, but overall it is 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 (3 parameters, nested objects, no output schema), the description covers input parameters thoroughly, including constraints and examples. It mentions the return value (subscription id) but omits error scenarios or rate limits beyond the SMS cap. Still, it provides sufficient context for an agent to use 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%, yet the description greatly enriches parameter understanding by providing concrete examples for each type (e.g., sec_8k items parameter, polymarket_edge min_spread_bps) and explaining constraints for delivery (e.g., SMS verification, webhook signing secret). This goes well beyond the schema alone.

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

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

The description uses a specific verb ('Create a proactive monitoring subscription') and resource ('live-data event stream'), clearly distinguishing it from sibling tools like 'unsubscribe', 'list_subscriptions', and 'recent_alerts'. It immediately conveys the tool's core function.

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

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

The description specifies the requirement for a Pipeworx OAuth account and notes that anonymous/BYO accounts cannot persist subscriptions, providing clear context for when the tool should be used. It also enumerates supported subscription types and delivery channels. However, it does not explicitly state when not to use the tool or name alternative tools for different 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 declare readOnlyHint=true and idempotentHint=true, making the tool's safety clear. The description adds value by detailing the output structure (category-bucketed examples, tool+argument shapes) and the effect of the topic parameter, going beyond what annotations provide.

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

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

The description is well-structured with a front-loaded list of example queries, followed by a concise explanation of output and usage. While it is somewhat lengthy, every sentence serves a purpose and it remains readable.

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

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

Given only one optional parameter, no output schema, and a large sibling set, the description is complete. It explains the tool's role as an onboarding entry point, when to use it, what output to expect, and even lists all category options. No gaps remain.

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

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

The schema covers the single parameter fully with description. The description reinforces the meaning by listing example values (finance, pharma, etc.) and explaining that omitting it gives a full spread. This adds practical context beyond the schema baseline.

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

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

The description clearly states that this tool returns example questions categorized by topic, with each example linked to the exact tool and argument shape. It distinguishes itself from siblings like ask_pipeworx by explicitly calling it the 'onboarding entry point' and referencing meta-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 explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do' and mentions how to call meta-tools. However, it does not explicitly state when not to use it or compare to alternatives like discover_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 readOnlyHint, openWorldHint, and idempotentHint. The description adds that the tool returns tag IDs for use in search(tag=...), which is valuable behavioral context beyond annotations. No contradictions.

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

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

Two concise sentences cover purpose, examples, filtering options, and return value. No unnecessary words; every sentence adds value.

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

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

Given the tool has 5 optional parameters, no enums, and an output schema, the description provides sufficient context for selection and invocation. It could mention sorting or additional output fields, but the essentials are covered.

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

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

With 0% schema description coverage, the description compensates by explaining the 'q', 'type', and 'section' parameters and providing an example. However, 'page' and 'page_size' are not detailed, leaving some gaps.

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 browses The Guardian's content tags, lists tag categories (topics, series, contributors, keywords), and provides examples. This distinguishes it from siblings like 'sections' and 'search', making the purpose immediately clear.

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

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

The description implies usage for filtering content by tags and obtaining tag IDs for search. It mentions filtering by q, type, or section. However, it does not explicitly state when not to use this tool or name alternatives, which would improve clarity.

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 soft-delete behavior ('deactivated, not deleted') and ties to historical events via 'recent_alerts'. Adds value beyond annotations, which already indicate non-destructive.

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

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

Two succinct sentences: first states action, second adds behavioral nuance. No unnecessary words.

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

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

Covers purpose, ownership, and behavioral side-effects completely for a simple tool with one parameter and no output schema.

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

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

Schema coverage is 100%, and the description adds no new information about the 'id' parameter beyond what the schema states ('returned by subscribe').

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?

Explicitly states 'Cancel a subscription by id' with clear verb and resource. Distinguishes from siblings 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?

Describes ownership enforcement ('you can only cancel your own subscriptions'), giving context on who can use it. Does not explicitly list alternatives or when to avoid.

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 (read-only, open-world, idempotent), the description reveals the verdict taxonomy, the meaning of could_not_verify versus unsupported, the two routing paths, and the inclusion of pipeworx:// citations. This is substantial added 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 longer than average, but each part earns its place: examples, use-case, path logic, return values, and error semantics. It is well-structured and front-loaded with the core purpose and trigger phrases.

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

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

Given no output schema, the description fully explains what the tool returns (verdicts, actual value, citation, reasoning) and clarifies the nuanced difference between could_not_verify and unsupported. It is complete and self-sufficient for an agent to invoke correctly.

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

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

Input schema covers both parameters with descriptions. The tool description adds examples for 'claim' but does not materially expand parameter meaning beyond the schema. With 100% schema coverage, baseline 3 is appropriate.

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

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

Clearly states the tool performs natural-language claim verification against authoritative sources, with a specific verb ('verify') and resource ('claim'). Distinguishes itself from generic search or ask tools by focusing on fact-checking and listing direct user-phrase triggers.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates the financial-claims fast path from the general grounded pipeline. Lacks explicit alternatives/exclusions naming sibling tools, but the context is strong enough for correct selection.

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