Kegg

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: probing multiple LLMs, scoring methodology, default free model, BYO key for Anthropic with direct payment, and detailed return format including per-model and combined views. 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?

The description is a single, well-structured paragraph of two sentences. It front-loads the core purpose, then explains default behavior and optional functionality. Every sentence adds essential information, with no redundancy or 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?

Given the tool's complexity (multiple models, optional parameters, scoring, no output schema), the description covers all critical aspects: what it does, default model, optional Anthropic probe, required entity parameter, optional context for disambiguation, and the return format per model plus combined view. It also lists use cases, making it self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default model behavior, the purpose of the API key (BYO for Anthropic), and how the context parameter helps disambiguate. 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 uses a specific verb ('probe') and resource ('LLMs for knowledge about a business/brand/product/topic') and clearly distinguishes the tool's purpose: scoring visibility (0-100) per model. It states the default model and return structure, making it distinct from siblings like 'scan_competitor_ai_presence' which likely focuses on competitive analysis rather than multi-model scoring.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It provides context on default model and optional Anthropic integration. However, it does not explicitly state when not to use this tool or list sibling alternatives by name, slightly reducing the score.

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

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

Beyond the annotations, it discloses that the tool routes internally, fills arguments automatically, and returns structured answers with stable citation URIs. It also surfaces a meaningful tradeoff by directing agents to a grounded variant when citations are missing.

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

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

The description is long but front-loaded with the most important routing directive and each block supplies scope, examples, or variant selection. It is dense rather than padded, though some example repetitions could be trimmed without losing 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 no output schema, the description's statement that the tool returns structured answers with stable pipeworx:// citation URIs is essential and present. It also covers domains, trigger phrases, and sibling alternatives, so an agent has enough context to select and call it correctly.

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

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

The input schema covers 100% of the parameters, including the question field and all aliases. The description mainly reinforces that the value should be a natural-language factual question, which adds examples but not substantial new 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 a specific verb and resource: it routes natural-language factual questions to 5,767 tools across 1,506 verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from Web search and from the ask_pipeworx_grounded/ask_pipeworx_beta variants.

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

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

It explicitly says to prefer this over Web search for current or historical data, gives concrete domains and trigger phrases, and even says to use it when Web search could also answer. It names alternatives: ask_pipeworx_grounded for missing citations and ask_pipeworx_beta for latency vs accuracy tradeoffs.

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 the safety surface (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false). The description adds genuinely useful dynamic behavior beyond that: candidates are 'enabled live whenever one is under test', none is active now (retired 2026-07-26), so it 'currently matches ask_pipeworx exactly'. It also disambiguates the riskiest misreading by asserting it is a full working router, not a stub. No contradiction with the annotations.

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

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

Four information-dense sentences with the identity and relationship to ask_pipeworx front-loaded before the current state, usage, and fallback clarification. Every sentence earns its place and there is no filler. It is somewhat long, but the nuance of the live-candidate mechanism justifies the length.

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

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

For a beta variant tied to a sibling, the description resolves the critical ambiguities: it is fully functional, currently identical to ask_pipeworx, and experimental only in routing behavior. The one gap is that core semantics and response shape are only given by reference ('same response shape', 'like ask_pipeworx'), and with no output schema on this tool the agent must resolve that reference elsewhere.

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

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

Schema description coverage is 100%: the required 'question' parameter has a full description listing its aliases, and all five alias parameters are documented as 'Alias for question'. The description adds no parameter-level meaning beyond the schema, so the 3 baseline for high coverage applies. Nothing is missing, but nothing extra is contributed either.

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

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

States a specific resource and role: 'Beta version of ask_pipeworx: identical universal router (same 5,767 tools, same arguments, same response shape)'. It differentiates from siblings by positioning itself as the experimental edge alongside the stable ask_pipeworx and the grounded ask_pipeworx_grounded. Minor deduction because it defines itself by reference to ask_pipeworx rather than independently stating what the routing does.

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?

Gives explicit selection guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It names the sibling alternative and the condition that selects this tool, and clarifies it 'Falls back to nothing' so the agent knows it is fully functional. No explicit exclusion ('use the stable version when you need proven behavior') is stated, which keeps it below a 5.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains that answers are extracted only from the tool result, that an explicit refusal is returned when data cannot directly answer, and it enumerates all possible refusal_reason values. It also discloses the extra LLM call cost, which is not visible in annotations or schema. This is exactly the kind of context an agent needs.

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 information-dense but every sentence earns its place: purpose, behavior, return shape, refusal reasons, use cases, and cost trade-off. It is front-loaded with the most important differentiator ('hallucination-resistant answer mode') and then builds logically. There is no filler or repetition.

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

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

The description is complete despite the lack of an output schema because it fully specifies both the success return object and the refusal return object with all key fields. It also covers when to use the tool, how it routes, what it refuses on, and its cost relative to the sibling tool. An agent has everything needed to select and invoke this 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 description coverage is 100%: all six parameters are just aliases for a natural-language question, and the schema already documents those aliases. The tool description reinforces that routing and argument-filling happen automatically, but it does not add new meaning about what the question parameter should contain. A baseline 3 is appropriate since the schema handles the parameter semantics.

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

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

The description states a specific verb and resource ('Ask Pipeworx') and clearly identifies this as the grounded, hallucination-resistant answer mode. It differentiates itself from ask_pipeworx by explaining the extraction-only-from-tool-result behavior and the explicit refusal mechanism. This is a precise, non-tautological purpose statement.

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 mode 'whenever an answer will be quoted, cited, or acted on' and when the agent 'must not invent facts', with concrete high-stakes examples. It also explicitly says to prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description goes into exceptional detail about behavioral traits: how it resolves markets, classifies bets, fans out to data packs, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, wide-spread handling, and cancellation rules. It aligns with annotations (readOnlyHint, openWorldHint, idempotentHint) and adds substantial context beyond them.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence provides valuable information; the length is justified by the tool's complexity. Slight deduction for being verbose but overall 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?

Despite no output schema, the description thoroughly explains return values and edge cases (low-confidence matches, closed markets, wide spreads, cancellation rules). It covers safety considerations and provides enough detail for agents to handle all scenarios. Excellent 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 description coverage is 100%, and the tool description adds significant meaning beyond the schema, such as explaining the 'depth' enum values ('quick = 2-3 evidence sources, thorough = full fan-out') and 'include_raw' effect on response size. This helps agents understand parameter trade-offs.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), distinguishing it from siblings by its single-call, comprehensive research nature.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not explicitly state when not to use it or offer alternatives, the provided context is clear and specific enough to guide appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds value by explaining the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and output format (paired data with citation URIs). No contradictions detected.

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 efficient, front-loaded with trigger phrases and key advantages. Slightly long but every sentence serves a purpose. Could be trimmed slightly but remains clear 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?

Given no output schema, the description adequately explains return values (revenue, net income, etc. for companies; adverse-event counts, FDA approvals, trials for drugs) and provides citation information. Covers edge cases (off-calendar fiscal years) and replacement value (replaces 8-15 lookups).

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

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

Schema coverage is 100%, but description enhances understanding by explaining the type enum with concrete examples (tickers/CIKs for company, drug names for drug), constraints (2-5 items), and behavior like sorting by primary metric so rank queries work intuitively.

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 side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases like 'compare X and Y' and 'rank these companies'. It distinguishes itself from siblings like entity_profile (single entity lookups) by emphasizing parallel 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides concrete trigger phrases. It also explains when to use company vs drug type and how results are sorted for ranking queries.

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 readOnlyHint/idempotent annotations, it discloses auth and paid tier, parallel routing to 5,767 tools, result fields (evidence/confidence/source/fetched_at/citation), gaps[] behavior ('never invented'), contradictions[] for standard/thorough, semantic excerpting, citation fetchability, and expected latency. It also says standard adds a gap-recovery hop and thorough adds an iterative hop, so no annotation 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 dense and front-loaded with the account gate, then moves from scope to behavioral detail to examples, so the highest-value information is early. It loses a point for being a long single paragraph and for the trailing sentence about catalog introspection, which doesn't clearly belong to this tool and adds ambiguity.

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

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

With no output schema, the description fully specifies what the agent gets back: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, citation_uri, gaps[], contradictions[], and excerpting behavior. It also covers latency, auth/paid tiers, and when to route to ask_pipeworx, so an agent has everything needed to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description mostly restates the schema's depth and question semantics (quick/standard/thorough, natural language). It does add the paid-gating fact for 'thorough' and the hop/recovery semantics, but those are also already in the schema's depth 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 names a specific action ('Grounded multi-source research'), a concrete resource ('Pipeworx's 1506 STRUCTURED data sources'), and an explicit output ('findings packet') in the first paragraph. It distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell what this tool is for. The later catalog-introspection sentence introduces some noise, but the central purpose is unambiguous.

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

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

It explicitly states when to use: 'Best for broad/multi-part questions over structured data', and when not: 'For a single lookup use ask_pipeworx instead', plus a sign-in prerequisite with fallback. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations declare readOnlyHint, idempotentHint true, destructiveHint false. Description adds that it returns top-N relevant tools with names, descriptions, and full input schemas, and that each result is ready to call directly. This explains the output behavior and convenience 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 concise with about 5 sentences, each adding essential information. It is well-structured: starts with purpose, lists domains, explains return value, and gives usage guidance. No unnecessary words.

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

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

For a discovery tool with no output schema, the description sufficiently explains what the tool returns (top-N tools with schemas) and how to use it. It covers the input, output, and usage context, making the tool fully understandable for an AI agent.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds value by explaining the query parameter with aliases and providing example queries ('analyze housing market trends', 'look up FDA drug approvals'), which helps the agent form correct inputs.

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 (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the first call to discover the option set.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to invoke this tool versus 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 provide readOnly/openWorld/idempotent hints, yet the description adds substantial behavior beyond them: parallel fan-out across nine sources, GDELT-to-GNews fallback, `sources_used`/`sources_failed` semantics, 'an empty section is a real "no data", not a bug,' private-company resolved:false handling with a notes line, and the fda_products expected-empty caveat. No statement contradicts the annotations.

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

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

Well front-loaded: example queries and the core purpose open the description. However, it is one unbroken, dense paragraph of over 200 words mixing source enumeration, return-field definitions, no-data semantics, and input-shape guidance, with the input-shape portion partially repeating the schema. Bullet separation would substantially improve scannability.

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

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

With no output schema, the description carries the full burden of return-value disclosure — and it pays it: every return section is enumerated (cik, company_name, recent_filings with URI format and 5-item cap, fundamentals fields, patents, federal_contracts, fda_products, hiring, news, LEI) plus failure semantics and name-resolution behavior. Remaining gaps such as invalid-ticker handling are minor against this coverage.

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 and the schema carries the semantic load: both parameters have descriptions, including the interchangeability of type values and the ticker/CIK/name forms for value. The description adds concrete value examples ('AAPL', '0000320193', 'Moderna') and the resolved_from/resolved_to note, but these are modest enhancements, not essential compensations.

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?

Opens with seven concrete user-query examples, then states the core function: 'full cross-source profile of a US public company in ONE parallel call.' The verb-resource-scope combination ('profile' + 'US public company' + 'cross-source') clearly distinguishes it from siblings like resolve_entity, compare_entities, and deep_research, none of which build a single holistic multi-source profile.

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

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

Explicitly guides the agent: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' naming the alternative behavior and the triggering condition. The example query patterns further operationalize when to invoke it. It does not, however, state exclusions for overlapping siblings such as compare_entities or deep_research.

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, and non-destructive behavior. The description adds that it is 'keyless' (no API key) and returns KEGG IDs with descriptions, providing extra 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 three sentences plus a standalone 'Keyless.' which is efficient. Each sentence serves a purpose: purpose, domain context, examples, and auth info. No redundancy.

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

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

Given the tool is a simple search with 2 parameters and no output schema, the description explains the database options, query examples, and the return format (IDs with descriptions). It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this with concrete examples and a list of database values, making parameter usage clearer.

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

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

The description clearly states 'Search KEGG by keyword' and provides specific examples of databases and queries, making the purpose unmistakable and distinct from sibling tools like get_entry or search_within.

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

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

It explicitly lists acceptable databases and gives example queries, guiding when to use. However, it lacks explicit 'when not to use' or alternatives, though the context is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not significantly expand behavioral disclosure beyond annotations.

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

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

Two concise sentences, front-loaded with purpose and usage guidance. No redundant words.

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

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

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, usage context, and parameter meaning.

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 parameter description in schema is adequate. Description adds no additional semantics beyond 'by key'; baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Delete' and the resource 'memory by key', and distinguishes from siblings by mentioning pairing 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?

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and mentions alternative tools for other operations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the safety profile is clear. The description adds that it fetches a page and emits markdown, but does not disclose network dependencies or potential latency, which would add value beyond annotations.

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

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

Three sentences with no wasted words: first sentence states purpose, second explains process, third lists use cases. Front-loaded and efficient.

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 two parameters, no output schema, and straightforward functionality, the description fully covers what the tool does, its inputs, and its output (a text blob ready for deployment). No gaps.

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

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

Schema coverage is 100% with both parameters described in the input schema. The description does not add new information beyond what the schema already provides (e.g., default and max for max_links are in 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 uses a specific verb ('generate') and resource ('llms.txt file'), and clearly states the goal of enabling AI crawlers to index sites. It distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

The description explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), providing clear context for when to use. However, it does not mention when NOT to use or compare to alternatives, missing 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds keyless authentication requirement and specifies the return format (parsed fields plus raw text), which are behavioral traits beyond annotations.

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

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

Three sentences with zero waste: first states purpose, second provides examples, third gives usage guidance. Information is front-loaded 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?

For a single-parameter tool with no output schema, the description covers purpose, parameter examples, return value overview, and usage prerequisite, making it 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 coverage is 100% but description adds valuable examples of ID formats and instructs to use find first, enriching the meaning beyond the schema's 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?

Clearly states verb (fetch), resource (KEGG flat-file entry), and scope (by ID). Distinguishes from sibling 'find' by advising to use find first to discover IDs.

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

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

Explicitly advises 'Use find first to discover IDs' as a prerequisite, providing clear when-to-use guidance. Implicitly defines when not to use (without a known ID).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by noting the result cap and truncated flag, which are behavioral traits beyond annotations. 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 with no fluff. It front-loads the core purpose and follows with usage guidance and constraints. Every sentence earns its place.

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

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

Given the tool has one simple parameter, no output schema, and clear annotations, the description adequately covers the return format (id+description), capacity limit (100), and flags. No significant gaps remain.

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

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

Schema coverage is 100% with a clear description of the 'database' parameter. The description adds examples ('pathway', 'drug') and clarifies that the output includes id and description, which enhances semantics beyond the schema.

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

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

The description clearly states 'List all entries in a KEGG database (id + description)', using a specific verb and resource. It distinguishes the tool from sibling tools by specifying KEGG databases, a unique domain among the listed siblings.

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

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

The description provides examples of when to use (enumerating pathways, drugs, organisms) and mentions the 100-result cap with a truncated flag. It does not explicitly state when not to use or name alternatives, but the context is sufficient for an agent to decide.

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

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

Description adds value beyond annotations by listing specific return fields (id, type, params, etc.) and implying read-only behavior. Annotations already indicate readOnlyHint and non-destructive, so 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 output, second gives usage guidance. No redundant information.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers return fields and usage, making it complete.

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

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

Schema coverage is 100% with one parameter described. The description does not add new semantic meaning about the parameter beyond what's 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly suggests using the tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use it.

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

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

Even though annotations are all false (no read-only/destructive hints), the description discloses the claim_token mechanism, rate limits ('Rate-limited to 5 per identifier per day'), quota impact, and that 'The team reads digests daily and signal directly affects roadmap.' This goes far beyond the structured annotations.

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

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

The description is longer than one sentence but every clause adds critical behavioral or usage detail—no filler. It is front-loaded with purpose and then flows into usage rules, token mechanics, and limits, making it dense but 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?

Given the lack of an output schema, the description explains the return behavior (claim_token), how to retrieve resolution status, and the human workflow behind the feedback. It covers caveats about cross-server feedback and message content, making it fully self-contained for an agent to use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical guidance on claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs users to 'Describe the issue in terms of Pipeworx tools/packs,' adding value beyond the schema's field definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which precisely states the tool's action and target. It clearly differentiates from all sibling research/subscription tools by being the only feedback channel.

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

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

It explicitly defines trigger conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion rule: not for other MCP servers, and directs users to file with that server instead.

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?

Goes beyond annotations by explaining data source (CF analytics-engine), privacy (no PII), and caching (5min-1h).

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

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

Concise, well-structured with bullet points and front-loaded purpose. Every sentence contributes.

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?

Fully covers what the tool does, returns, data source, caching, and use cases. No gaps given simplicity and annotations.

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 full coverage, and description adds nuanced meaning for window values ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description clearly states it returns top tools, packs, and call volume over a window, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Provides three explicit use cases, but does not mention when not to use or alternatives, though the siblings list implies 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: scanning scope (top ~200 markets), partition checks (threshold >3pp), similarity filter (Jaccard ≥0.30), placeholder filter, fill check against live CLOB depth, and reference to another tool for custom sizing. 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?

The description is front-loaded with the purpose and mode overview. It is detailed but not overly verbose. Some sentences (e.g., the fill check details) could be condensed, but the structure is logical and easy to follow.

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

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

Despite no output schema, the description explains the response structure (opportunities[], gap_pp, suggested_trade, etc.) and covers all edge cases (low similarity, placeholder filters, fill check). It also references another tool for custom sizing, making it self-contained for an agent.

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

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

Schema description coverage is 100% (both event and topic described). The description adds meaning beyond schema: event accepts slug or full URL, topic is a seed question, and explains when to use each mode with concrete examples.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb and resource, distinguishing it from siblings like polymarket_edges (edge detection) and polymarket_fill_risk (fill risk analysis).

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

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

Explicitly provides when to use each mode: 'Call with NO args for a trending_scan... pass `event` for... or `topic` for...' Recommends event mode for specific markets, topic for cross-event scanning, and warns against trading when realizable_edge_pp ≤ 0. Clear alternatives and 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?

The description discloses several behavioral traits beyond annotations: caching ('Cached 1h at the KV level'), response structure with diagnostics ('_diagnostics{...filter_skips} so callers can see WHY a segment is empty'), and edge computation details (Kelly fraction caps at 0.25, slippage subtraction). The readOnlyHint and idempotentHint are already in annotations, so the description adds useful operational context without contradiction.

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

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

The description is excessively long and dense, presenting a wall of text without clear structure. It covers multiple segments, response fields, and edge computation details in a single paragraph. While the content is valuable, it would benefit from breaking into sections (e.g., Overview, Model Families, Filtering, Response) to improve readability. 2 because overlong and unstructured.

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

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

Given the complexity (9 parameters, no output schema), the description is fairly complete. It explains the three response segments, the fed_note, diagnostics, and the tradeable-edge knobs. It even details edge computation and caching. The missing output schema is partially compensated by the description's detailed explanation of what each response element contains. Score 4 because it covers most aspects an agent would need to understand the tool's behavior.

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

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

All 9 parameters are documented in the input schema with descriptions, so the baseline is 3. The description adds some value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and providing behavioral context (e.g., 'min_kelly never filters them' for partition arbs). However, the parameter descriptions in the schema are already comprehensive, so the description's addition is marginal.

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. Built for "what should I bet on today"'. It identifies the specific resource (Polymarket markets) and action (return opportunities with edge). The purpose is well-differentiated from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explains the tool's use case: discovering opportunities without paging hundreds of markets. However, it does not explicitly state when to avoid this tool or suggest alternatives. Given the extensive sibling list, explicit guidance on when to use polymarket_arbitrage vs this tool would improve clarity. The description implies it is the primary edge discovery tool.

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

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

The description adds significant behavioral context beyond annotations: limitations (60-day snapshot TTL, data gaps, decay computed from daily closes, not intraday), and nuances about snapshot generation (cache-miss dependency). Annotations already declare readOnly, idempotent, openWorld, and non-destructive, and the description aligns with them while providing rich details.

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: purpose first, then response structure, then limits. Every sentence provides necessary information without repetition. It earns its length given the complexity of telemetry data and absence of output schema.

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

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

Given no output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]) with detailed field semantics and computational methods. It also covers data freshness and limitations, making the tool fully understandable without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating default values (14 days, '1wk' window), maximum clamp (30 days), and explaining that 'window' refers to snapshot family. It also explicitly lists response fields and their meanings, compensating for the missing output schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings by focusing on historical persistence, with a concrete example differentiating fresh vs. old wide 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?

The description explains when to use the tool (to get historical edge persistence and decay) and provides an example that guides interpretation. While it does not explicitly list when not to use or name alternatives, the context from sibling tools and the clear purpose make usage fairly clear.

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

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

Beyond annotations (readOnlyHint, etc.), the description reveals detailed behavior: walking the ladder, returning specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), basket-mode nuances (theoretical vs realizable sum, capture ratio, forced directional risk), and warnings about unfilled partial baskets. 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 structured with clear sections (SINGLE-MARKET, BASKET) and a usage guidance paragraph. While lengthy, the detail is warranted for a complex tool with two modes. Minor redundancy could be trimmed, but overall 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?

With no output schema, the description fully covers return values for both modes, including verdicts, thin legs, forced directional risk, and max clean notional. It also addresses edge cases and risks, making it self-contained for agent decision-making.

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

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

Schema coverage is 100%, but the description adds significant meaning: clarifies mode selection via market vs event, explains size_usd as settlement notional for baskets, and default side logic. This goes beyond schema descriptions, enhancing agent understanding.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth, distinguishing two modes (single-market and basket). This specificity differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges, which are for generating signals or listing 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?

The description explicitly instructs to use this tool before acting on arbitrage signals or trades above $500, and explains the risk of partial basket fills converting arb into directional positions. This provides clear when-to-use and when-not-to guidance, referencing alternatives implicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes far beyond that by disclosing pairing_unverified is always set, spreads are gross not net tradeable, compatibility warnings can be non-empty even when pairs are returned, and unknown legs are never paired — exactly the behavioral nuance an agent needs.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence adds operational detail, though some ideas are repeated across the compatibility-code explanations and the temporal_alignment notes, making it slightly denser than necessary.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: top_spreads_pp, compatibility_codes[], flags[], temporal_alignment, skipped_unclassified, low_confidence_pairs[], fees_note, and the skipped-cross counters are all described with their semantics. An agent can correctly interpret results and know which pairs are trustworthy without needing the 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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that explicit parameters override the topic-mapped side, that both modes use identical matcher logic, and that the topic parameter is a curated list of macros. This is useful but not extensive, since the schema already documents each parameter with examples.

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

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

States a specific verb+resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two-mode description (topic vs explicit ticker/slug) further pins down exactly what the tool does and sets it apart from per-venue siblings like 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?

Gives clear mode-selection guidance: use pre-mapped topic shortcuts or explicit kalshi_event_ticker/polymarket_event_slug for custom pairings, and notes that both modes run the same matcher. It warns that most pre-mapped topics currently return compatibility warnings, but it does not explicitly name alternative tools or state when NOT to use this tool versus a sibling like polymarket_arbitrage.

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

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

Adds scoping context (anonymous IP, BYO key hash, account ID) beyond annotations. No contradictions with readOnlyHint, idempotentHint, destructiveHint.

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: two modes, usage examples, scoping, pairing with other tools. No wasted words, front-loaded with main action.

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

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

Given no output schema, description could mention return format (e.g., string value or array of keys). But it's complete enough for its simplicity; minor gap.

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

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

Schema already describes the 'key' parameter with 100% coverage. Description adds that omitting key lists all keys, matching schema's 'omit to list all keys'. Baseline 3 is appropriate; description provides marginal extra context.

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

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

Description clearly states the tool retrieves a saved value by key or lists all keys when key is omitted. Distinguishes from siblings like '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: to look up previously stored context without re-deriving. Gives examples like target ticker, address. Pairs with remember/forget. Could be more explicit about when not to use but still strong.

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

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

Adds behavioral details beyond annotations: mark_read effect, returned fields (source, citation_uri, payload). No contradiction with readOnlyHint or destructiveHint.

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

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

Four focused sentences, no fluff, logical flow: purpose, return fields, filtering, polling. Highly concise yet informative.

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, filtering, read-state management, and alternative access. No output schema needed; description adequately explains what to expect.

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

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

Schema coverage is 100%, but description adds examples (sec_8k), format (ISO timestamp), and mark_read behavior. Adds value beyond schema.

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

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

Clearly states 'Pull fired events from your subscription feed' with specific verb and resource. Distinguishes from sibling tools like list_subscriptions, subscribe, etc.

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 filtering guidance (type, since) and polling advice. Mentions alternative endpoint for scripts/dashboards, but lacks explicit when-not-to-use comparisons.

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

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

Describes calls to SEC EDGAR, GDELT/GNews, USPTO, soft-failure for patents, and return format (changes[], total_changes, citation URIs). Annotations already indicate safety; description adds rich 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?

Dense but well-structured paragraph with example queries, technical details, and clear separation of concerns. Every sentence provides unique 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?

No output schema, but description explains return structure (changes[], total_changes, citation URIs). Covers all parameters, fallbacks, and limitations (patents soft-fail). Complete for an information retrieval tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining `since` accepts ISO or relative with examples, `value` as ticker/CIK, and typical monitoring window suggestion.

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

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

The description clearly defines the tool as a change feed for a company over a recent window, with example queries. It distinguishes from the sibling `entity_profile` by explicitly contrasting use cases.

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

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

Provides explicit guidance on when to use (change feed queries) and when to use `entity_profile` instead. Also explains fallback behavior 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?

The description adds rich behavioral context beyond annotations: key-value storage, scoping by identifier, and persistence differences (authenticated vs anonymous 24h). Annotations are idempotentHint=true, and description confirms idempotent behavior. 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?

The description is concise (3 sentences) with a clear front-loaded purpose, then usage guidelines, then technical details. Every sentence adds value with zero waste.

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

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

Given no output schema, the description explains behavior and storage semantics thoroughly. It could mention return value or error handling, but covers the core functionality completely for a storage tool.

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

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

Schema coverage is 100%, and the description adds real-world examples for keys and values, enhancing understanding. While schema already documents params, the examples provide added semantic clarity.

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

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

The description states a specific verb ('Save') and resource ('data the agent will need to reuse later'), with examples of use cases. It also distinguishes from sibling tools recall and forget, meeting the highest standard.

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 when to use ('when you discover something worth carrying forward') and pairs with recall and forget for complementary actions. It also provides context on scoping and persistence, guiding the agent effectively.

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

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

Beyond the readOnly/idempotent/open-world annotations, the description discloses graceful degradation when GLEIF or OpenFIGI is unavailable, ambiguous-name behavior via figi_candidates, explicit unresolved identifiers, source labels, and internal cascading through multiple endpoints. These behaviors significantly help an agent predict outcomes before calling the tool.

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

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

The description is long and dense, but it front-loads the core purpose and usage intent. The supported-types section and parenthetical caveats are mostly necessary for a tool with two entity types and multiple identifier sources, though tighter formatting and less run-on phrasing would improve scannability.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly: identifiers, source labels, unresolved fields, figi_candidates, RxCUI citations, and failure mode when upstream sources are unavailable. Nothing critical for correct invocation is missing.

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

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

The schema already documents both parameters fully, but the description adds useful semantic context: ISIN is accepted as a company input, names mapping to multiple instruments return candidates, and non-equity instruments without tickers can still resolve. Some of the entity-name-only guidance is duplicated from the schema, so the added value is meaningful but not overwhelming enough for a 5.

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

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

The description opens with concrete user-phrase examples and clearly states the verb-resource pair: resolve a user-spoken name to canonical/official identifiers that other tools require as input. It further distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID' and scopes supported types to 'company' and 'drug', making it hard to confuse with siblings like entity_profile or find.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. It also covers what inputs are accepted per type. It stops short of a 5 because it does not explicitly name when-not-to-use alternatives or give exclusion criteria against sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with per-entity metrics. No contradictions with annotations.

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

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

The description is two sentences plus a usage note, front-loading the main action. Every sentence adds value, with no redundant or filler content.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers the key aspects, though it could mention error handling or what happens when entities are unrecognized. Still sufficient for an agent.

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

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

Schema coverage is 100% and the description adds critical context: first entity is treated as 'subject', models have defaults and prerequisites (e.g., Anthropic API key), and context disambiguates. This significantly enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. It distinguishes from the sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking.

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 case ('competitive AI-marketing audits') and a concrete example. It implies when to use but does not explicitly state when to avoid or provide alternative tool names beyond the mention of ai_visibility_check in the flow.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds crucial behavioral details about partial failures and timing (bundlephobia's first measurement takes 5-30s, sources_failed list), which go beyond annotation coverage and help set agent expectations.

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 concise paragraph that front-loads the core purpose and then elaborates on details. It is efficient with no wasted words, though it could be broken into bullet points for readability.

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

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

Given no output schema, the description thoroughly explains the return values (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases (failure modes, ecosystem limits). This makes the tool fully understandable for an AI agent.

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

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

Schema coverage is 100%, so the description does not need to explain parameters; it adds context about the return summary block but does not enhance parameter meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs a composite check for evaluating whether to add an npm package, specifying data sources (deps.dev and bundlephobia) and the exact purpose. It distinguishes itself from sibling tools, which are unrelated to dependency scanning.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and provides a clear exclusion ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), effectively guiding agent 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, idempotentHint, etc. The description adds significant behavioral details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char truncation with flagging, and character offsets for verification. 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 dense paragraph with no wasted words. Each sentence serves a purpose: core function, example, usage guidance, and technical details. Well front-loaded.

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

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

Despite lacking an output schema, the description details the return value (top-N passages with offsets and scores). It covers edge cases (truncation), tool model details, and integration with siblings. Complete for a medium-complexity tool.

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

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

Schema coverage is 100% with three parameters described. The description goes further: explains text max size and truncation, limit default and range (1-20), and provides query examples. 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 the tool performs semantic search inside a fetched record, using input text and natural-language query. It distinguishes from sibling tools like ask_pipeworx_grounded and find by specifying it operates on already-retrieved content, returning passages with offsets and scores. The verb 'search within' plus resource is precise.

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 recommends using the tool when records are too large for prompts and pairs it with ask_pipeworx_grounded for grounding. While it does not list exclusions or alternatives beyond that, the usage context is clearly stated.

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=true and destructiveHint=false, but the description adds important behavioral details: OAuth requirement, phone verification, SMS cap of 10/day, webhook auto-disable after 10 failures, and one-time return of webhook secret. These go beyond annotations and help the agent understand side effects and constraints.

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

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

The description is front-loaded with the core action and return type, followed by requirements, supported types, and delivery details. Although lengthy, the structure is logical and each sentence adds value. Minor redundancy in repeating constraints across delivery channels, but overall 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?

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is remarkably complete. It covers all parameter types with examples, explains delivery channel quirks, mentions the return value (subscription id), and highlights important constraints (authentication, verification, rate limits, auto-disable). No major gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning. For each supported type, it provides concrete parameter examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}'). For delivery, it explains verification and rate limits. This additional context helps the agent construct correct parameter 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 starts with 'Create a proactive monitoring subscription to a live-data event stream.' This uses a specific verb ('Create') and resource ('proactive monitoring subscription'), clearly stating the tool's purpose. It also mentions 'Returns the new subscription id,' which clarifies the output. Among sibling tools (list_subscriptions, recent_alerts, unsubscribe), this description uniquely identifies the create action.

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

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

The description provides clear context for using the tool, including prerequisites ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channel options. However, it does not explicitly compare to alternatives or state when not to use this tool. Since the purpose is straightforward (creating subscriptions vs. listing or unsubscribing), the guidance is adequate but not exhaustive.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds that it returns category-bucketed examples with tool+argument shapes, and uses live catalog. 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?

Packs substantial information (categories, usage, return structure) into a flowing sentence. Slightly long but efficient, with clear front-loading of intent.

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 param and no output schema, the description fully covers what the tool does, what it returns, and how to use it. No gaps.

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

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

The only parameter (topic) has full schema coverage (100%). Description adds meaning: enumerates valid values, explains behavior when omitted vs. specified, and how it focuses the output.

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: an onboarding entry point that returns example questions across categories, with specific tool+argument shapes. It distinguishes from siblings like ask_pipeworx and entity_profile.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to use optional topic parameter. Missing explicit when-not-to-use, but clear enough.

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

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

Annotations indicate non-read-only, idempotent, and non-destructive. The description adds value by disclosing that the operation deactivates rather than deletes, preserving historical events. 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 three concise sentences that front-load the core action ('Cancel a subscription by id') and then add key constraints and behavior. No extraneous information.

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

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

For a simple cancellation tool with one parameter, the description provides sufficient context: what it does, ownership constraint, side effects (deactivation), and relation to 'recent_alerts'. The annotations cover safety traits. Complete for an agent's needs.

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 full coverage for the single 'id' parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds contextual ownership enforcement but does not provide additional parameter-level semantics beyond the schema.

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

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

The description clearly states the tool cancels a subscription by ID, using a specific verb ('Cancel') and resource ('subscription'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), which tells the agent when the tool is usable. It also mentions that the row is deactivated rather than deleted, linking to 'recent_alerts' for historical data. However, it does not explicitly state when not to use this tool or compare with alternatives.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, non-destructive. The description adds valuable post-verification behavior: the distinction between could_not_verify (check did not happen, must not be used as evidence) and unsupported (no source exists), plus the presence of verification_error with stage/detail. It also discloses the automatic fallback pipeline and citation mechanics, going well beyond the annotations.

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

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

The description is longer than average but every sentence earns its place: triggers, use cases, routing, verdicts, error semantics, and efficiency note. It is front-loaded with examples and ends with a clear 'IMPORTANT' caveat. Structure is logical, though slightly dense for a casual reader.

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 (routing, verdict types, error states) and the absence of an output schema, the description fully covers return values, evidence format, and failure semantics. It explains the difference between could_not_verify and unsupported, which is critical for agent decision-making. 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?

Even though the schema covers 100% of parameters with descriptions, the tool description enriches both. For claim, it provides realistic examples. For tolerance_pct, it explains the override semantics and gives a use case (1–2 for hallucination detection) and a default cap of 5%. This adds meaning beyond the bare schema.

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

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

The description opens with concrete natural-language triggers ("Is it true that…", "fact check") and specifies the action: natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by stating it's for verifying factual correctness and even notes it replaces multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives a detailed breakdown of financial vs. other claims and the routing behavior. No explicit exclusions for when not to use, but the context is strong enough to infer boundaries.

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