Edamam

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 important behavioral context: default free model, optional Anthropic probing with BYO key (billing implications), and the return structure (per-model fields + combined view). No contradictions.

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

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

Four sentences with zero waste. The purpose is front-loaded, followed by key behavioral details and use cases. Every sentence adds essential information.

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

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

Despite having 4 parameters and no output schema, the description covers purpose, parameters, return format (per-model fields + combined), and use cases. There are no gaps given the tool's simplicity.

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

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

Schema description coverage is 100%, but the description adds value beyond the schema: it explains the default for 'models', the condition for '_apiKey', and the disambiguation purpose of 'context'. This helps the agent understand parameter relationships.

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

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

The description uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'), clearly distinguishing from sibling tools like 'ask_pipeworx' (which answers questions about a specific entity) or 'deep_research' (more extensive research). It specifies the output format and default model.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use or compare to alternatives, but the context of sibling tools provides implicit guidance, and the description is clear enough for an agent to decide.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: the tool routes across 5,798 tools, fills arguments autonomously, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure modes, but the behavioral profile is well covered.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and packed with useful examples and routing guidance. However, the final routing section is a garbled run-on ('...use ask_pipeworx_grounded; for a broad/multi-part question...') with missing capitalization and clear separation, which hurts readability despite the valuable content.

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

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

Despite the lack of an output schema, the description explains what the tool returns: a structured answer with stable pipeworx:// citation URIs. It covers scope, trigger conditions, examples, alternatives, and even notes the free-account aspect of deep_research. It is sufficiently complete for an agent to select and call this tool effectively.

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 parameter descriptions already explain that all six fields are aliases for the natural-language question. The tool description reinforces this with examples and intent, but adds little semantic detail beyond what the schema already provides, so the baseline 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 identifies this as a router/aggregator for factual questions over authoritative structured data sources, with explicit examples spanning SEC filings, FDA data, economic statistics, and more. It also distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, so an agent can tell them apart.

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 instructs 'PREFER OVER WEB SEARCH' and gives concrete trigger phrases and example questions. It also names alternatives and the conditions for choosing them: ask_pipeworx_grounded for hallucination-resistant verbatim answers, deep_research for broad multi-part fan-out questions.

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 valuable context: candidate routing improvements are enabled live when under test, no candidate is currently active, it currently matches ask_pipeworx exactly, and it falls back to nothing because it is a full working router rather than a thin wrapper. This goes beyond the annotations and clarifies the beta nature 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 longer than minimal but every sentence contributes: it establishes the beta relationship, explains the current experimental state, and gives usage direction. The parenthetical specifics like 5,798 tools and the retirement date add useful precision without becoming padding. It is front-loaded with the core 'beta version' identity.

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 router tool, the description covers the key operational details: current identity, identical behavior to ask_pipeworx, live candidate status, no fallback, and full functionality. The only mild gap is that the actual response shape is referenced but not described, although it points to the stable ask_pipeworx as the reference. Given the annotations and schema, this is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents each parameter, including the aliases for 'question'. The description only says 'same arguments' without adding parameter-level detail, which is acceptable because the schema already carries the burden. This matches the baseline for high schema coverage.

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

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

The description immediately identifies the tool as 'Beta version of ask_pipeworx' and states it is an identical universal router with the same tools, arguments, and response shape. This clearly distinguishes it from the sibling ask_pipeworx and ask_pipeworx_grounded. The purpose is concrete: it is the experimental routing variant of ask_pipeworx.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router to decide merges. It references the stable ask_pipeworx as the comparison point, providing clear context. It does not explicitly state when not to use it, but the 'use when you want the newest routing' condition is sufficient.

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

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

Annotations already mark readOnlyHint=true, openWorldHint=true, and idempotentHint=true, and the description adds a full behavioral contract on top: the success payload {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, a complete enumerated refusal contract, the verbatim-quote guarantee, and the extra-LLM-call cost. Nothing 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?

Three dense sentences, each earning its place: behavior, return/refusal contract, and usage-with-alternative are cleanly separated. The inline refusal enum and payload spec are verbose but necessary because no output schema exists; the length is justified but near the upper bound.

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

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

Covers purpose, routing behavior, the extraction guarantee, full return contract, refusal semantics, when-to-use guidance, and the cost-based alternative. With no output schema and no parameter enums, the description carries the full burden and succeeds; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the single question parameter with five documented aliases already carries the full semantic weight. The description adds context about how the question is processed (routing across 5,798 tools, argument filling, extraction) but gives no additional phrasing or format guidance for the parameter itself. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific behavior: it is a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes itself from ask_pipeworx by naming the sibling directly ('Same routing as ask_pipeworx') and positioning itself as the grounded variant. The verb-resource pairing (answer extraction + Pipeworx data) is unambiguous.

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

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

Explicitly prescribes when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and the cost tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

Annotations already mark the tool as read-only and idempotent. The description goes far beyond by detailing response shapes, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and comprehensive but well-structured with capitalized section headers. While it earns its place with detailed behavioral transparency, some redundancy could be trimmed for efficiency.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers input variations, process, return fields, edge cases (closed markets, low confidence), and safety considerations. No gaps are apparent.

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

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

Schema covers all 3 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by illustrating the market parameter's flexible formats (slug, URL, question text) and giving examples. Depth and include_raw are well-explained in schema.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, specifying input types (slug, URL, question text) and the process flow. It distinguishes from siblings like polmarket_arbitrage and polmarket_edges by focusing on single-bet research with evidence gathering.

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

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

Explicitly suggests use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive examples of fan-out for different bet types. Lacks explicit alternatives among siblings but gives clear context and safety guidance for when not to trust results (low-confidence, closed markets).

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

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

The description adds significant behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), fiscal year handling, sorting by primary metric, and output format including citation URIs. No contradiction with annotations.

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

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

The description is relatively concise given the complexity, front-loading example queries and key benefit. Every sentence adds information, though it could be slightly tighter.

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

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

Given the tool's complexity (two entity types, multiple data points) and the presence of annotations, the description covers essential aspects: data sources, sorting, output format. No output schema but description mentions returned data, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for values (tickers/CIKs for companies, drug names) and clarifying entity types, making parameter usage more intuitive.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, providing specific examples of user queries and distinguishing from sequential lookups.

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

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

It explicitly advises to prefer this over sequential single-pack lookups and quantifies efficiency (replaces 8-15 lookups), but does not explicitly state when not to use it or mention alternatives by name.

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 substantial behavior beyond annotations: account/paid-plan requirements, parallel routing, findings packet structure, gaps[] and contradictions[], hop/citation_uri fetchability guarantees, semantic excerpting, and expected latency. No contradiction with readOnly/openWorld/idempotent hints.

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

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

Long but appropriately dense for a complex tool; nearly every sentence adds something useful. Slightly disorganized and redundant in places ('One call, not many' echoes 'in ONE call'), which prevents a 5.

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?

Complete for a complex research tool with no output schema: it covers auth, cost, latency, input suitability, return format, citation resolvability, gap/contradiction behavior, and alternatives. Nothing needed 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?

Schema description coverage is 100% and the schema already explains depth levels and the question parameter fully. The description adds usage context (e.g. broad/multi-part questions are fine) but no additional parameter-level semantics, so baseline 3 applies.

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

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

States a specific behavior: grounded multi-source research over 1517 structured data sources in one call, decomposing questions into facets and routing them in parallel. Also distinguishes itself from open-web search and from ask_pipeworx for single lookups, so an agent can tell it apart from siblings.

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

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

Gives explicit when-to-use: best for broad/multi-part questions over structured data, with examples. Explicitly says to use ask_pipeworx instead for single lookups and if the user is not signed in; also notes the paid requirement for thorough depth.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results are ready to call directly without a second lookup, which is important behavioral context. No contradictions.

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

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

The description is moderately sized but well-structured, front-loading the purpose and key domain list. Every sentence adds value, though it could be slightly more concise.

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

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

Given the lack of an output schema, the description adequately explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It covers the essential information an agent 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?

Schema coverage is 100%, so the baseline is 3. The description mentions 'query' as the main parameter and gives examples, but does not add significant meaning beyond the schema descriptions for other parameters.

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

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

The description starts with 'Find tools by describing the data or task,' which clearly states the tool's purpose. It enumerates specific domains and explains that it returns top-N tools with schemas, differentiating it from sibling tools that perform specific tasks.

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

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

The description explicitly advises '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 use this tool versus others.

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

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

Annotations already declare readonly/idempotent, so the description's burden is behavioral detail beyond safety. It adds substantial context: parallel fan-out across SEC, XBRL, patents, contracts, FDA, hiring, news, and GLEIF; explicit mention of sources_used/sources_failed; and the warning that an empty section is real 'no data' not a bug. This is exactly the kind of behavior an agent needs to interpret results correctly.

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 information-dense; every sentence contributes actionable detail about purpose, sources, return fields, and edge cases. It is front-loaded with the core purpose and preferred usage. The structure is a single dense paragraph, so splitting into bullet points would improve scannability, but it earns its length given the tool's complexity.

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

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

Even without an output schema, the description covers return fields (cik, company_name, recent_filings with URIs, fundamentals sections, sources_used/sources_failed), source-by-source detail, and failure modes (private company, no data for a source). This is sufficient for an agent to know what results to expect and how to handle anomalies. The tool is complex, and the description addresses that complexity thoroughly.

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 value beyond the schema by giving concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that type is interchangeable for all value shapes, and explaining name resolution via SEC EDGAR. It does not need to compensate for schema gaps, but it enriches parameter understanding.

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

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

The description clearly states the tool's purpose: a 'full cross-source profile of a US public company in ONE parallel call.' It uses actionable verbs like 'tell me about X' and explicitly contrasts itself with chaining single-pack lookups. It distinguishes itself from sibling tools such as resolve_entity or compare_entities by emphasizing the holistic cross-source 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?

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted input forms (ticker, CIK, company name) and explains what happens for private companies (resolved:false with notes). This leaves minimal ambiguity about when to invoke the tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns without adding new behavioral context. No contradiction, but little extra 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?

Two sentences, front-loaded with purpose and usage. Every sentence is essential and there is 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?

For a tool with one parameter and no output schema, the description covers the action, purpose, and usage context adequately. It pairs well with sibling tools and is complete.

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

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

Schema description coverage is 100% for the single parameter 'key'. The description does not add additional meaning beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the method ('by key'). It also differentiates from siblings ('remember' and 'recall'), making it distinct.

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

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

It provides specific scenarios for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with related tools, giving clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context: fetches the page, extracts title/description/key links, and emits markdown. No contradictions.

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

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

Three sentences: purpose, method, use cases. Every sentence adds value. 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?

For a tool with 2 params, no output schema, and no nested objects, the description adequately covers what the tool does and what output to expect. Minor gap: no mention of error handling or timeouts.

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

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

Schema description coverage is 100%; the description repeats the URL example and 'max_links' default/max but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool generates an llms.txt file for any URL, listing specific use cases. It uses specific verb+resource (generate llms.txt) and distinguishes from all 39 sibling tools.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it lacks explicit when-not-to-use, the guidelines are clear and context-rich.

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, not destructive. Description adds that it returns specific fields and can include inactive subscriptions, offering context beyond annotations.

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

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

Two sentences, front-loaded with action and return list. No filler; every sentence serves a purpose.

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

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

No output schema, but description lists return fields. Parameters covered. Complete for a list tool with good 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 coverage is 100%, so description adds limited value beyond the schema. It mentions return fields which help contextualize the parameter, but does not elaborate on 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?

States 'List the caller's active subscriptions' with specific verb and resource, distinguishes 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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use and alternative actions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context by specifying output fields and providing an example input format, which is beyond annotation coverage.

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

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

Description is a single sentence plus an example. No wasted words, front-loaded with core function.

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 2 params and no output schema, the description is sufficient: it states inputs, outputs, and provides an example. 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% and describes both parameters concisely. The description adds a concrete example and clarifies the ingredient format, which aids understanding beyond the schema.

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

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

The description clearly states it analyzes nutrition of a food ingredient or recipe line and lists specific outputs (calories, weight, labels, macros). This distinguishes it from sibling tools like search_food and search_recipes.

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

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

No explicit guidance on when to use vs alternatives. An example is given, but no 'when not to use' or mention of sibling tools. Usage is implied by purpose.

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?

With no useful annotations (all false), the description carries the full transparency burden. It discloses the claim_token workflow (filing without an account returns a token, passing it back later reads status), rate limiting (5 per identifier per day), and that the tool is free and doesn't count against quota. These are valuable behavioral traits beyond the annotations.

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

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

The description is long but every sentence earns its place. It front-loads the purpose, provides clear usage guidance, exclusions, workflow detail, and operational notes. It is well-structured with no fluff, making it appropriately sized for the tool's complexity.

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

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

The tool has no output schema, so the description must explain return behavior, which it does via the claim_token mechanism. It covers scope (Pipeworx tools only), use cases, rate limits, and roadmap impact. For a feedback tool with nuanced workflows, the description is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining the claim_token round-trip usage and cautioning not to paste end-user prompts. It doesn't detail the context fields, but those are already clearly described in the schema, so the addition is sufficient.

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: to tell the Pipeworx team about things that are broken, missing, or need to exist. It specifies categories (bug, feature/data_gap, praise) and distinguishes itself from sibling Q&A and search tools by being a 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?

The description explicitly states when to use the tool (for bugs, feature gaps, praise) and provides a clear exclusion: only for tools served by this Pipeworx connection, not for other MCP servers. It also advises phrasing feedback in terms of Pipeworx tools and not pasting end-user prompts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining data source (CF analytics-engine), no PII, and caching (5min-1h). 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?

Four sentences with zero waste: main purpose, three use cases, technical details. Front-loaded and well-structured.

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

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

Though no output schema, the description sufficiently explains return values. Caching and data source are mentioned. Adequate for a simple read-only trend 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 covers 100% of parameters with enum and description. Description adds semantic guidance on window selection (shorter for hot, longer for steady-state), enhancing meaning beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window, using specific verbs and distinguishing from sibling tools 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?

Lists three explicit use cases (discovering hot sources, confirming canonical tools, aligning use cases) and explains window trade-offs (shorter for hot, longer for steady-state). Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: semantic anchor (Jaccard similarity), partition filter for placeholders, fill check against CLOB depth, and explicit warning against trading when realizable edge is ≤0. These traits go well 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 long but well-structured, using section breaks and bolded terms. It front-loads the purpose and progressively details each mode. While verbose, the density of information (modes, internal logic, caveats) justifies the length, though minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains the return structure and behavior across all modes. It covers edge cases (placeholder filtering, fill validation) and provides actionable guidance, leaving no gaps for an AI agent to interpret the tool's actions and results.

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

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

With 100% schema coverage, both parameters are already described in the input schema. However, the description enriches semantics by explaining usage (event slug vs. URL, topic as seed question) and how each mode operates, adding significant value beyond the schema.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' specifying the action and resource. It distinguishes three modes (no args, event, topic) and differentiates from sibling Polmarke tools by its unique arbitrage focus.

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

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

The description explicitly directs when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It explains the benefits of each and even redirects to a sibling tool (polymarket_fill_risk) for custom sizing, providing clear guidance on when not to use this tool alone.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: caching at KV level, methodology breakdown (three model families, diagnostics structure), and safety details (read-only, zero destructive actions). 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 dense but well-structured with clear segments and bullet points. Every sentence adds value, though it is somewhat lengthy. Could be slightly more concise without losing clarity.

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 having no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and parameter knobs. It covers output fields, caching, and model details, making it very complete for a complex tool.

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

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

Schema coverage is 100% with all parameters described. The description adds marginal extra context (e.g., slippage_pp explanation about fees), but does not significantly extend beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on data-driven edges rather than pure arbitrage.

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

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

The description explicitly says it's built for 'what should I bet on today' and explains tradeable-edge knobs like min_liquidity/max_spread_pp for filtering. However, it doesn't explicitly state when not to use it or provide direct alternatives among siblings.

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

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

The description adds significant detail beyond annotations: explains snapshot mechanism, cache-miss gaps, decay computation from daily closes, TTL limitations. 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 verbose and includes response structure details, which is helpful but could be more concise. It is well-organized but slightly too long.

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

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

Given the tool's complexity and lack of output schema, the description fully compensates by detailing the output fields and limitations. It is complete for a read-only 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 describes both parameters. The description adds defaults and clarifies 'lookback' and 'snapshot family', but adds only marginal value beyond the schema.

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

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

The description states it provides 'edge persistence and decay telemetry' and explicitly distinguishes from siblings by focusing on historical persistence rather than current 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 gives context on when to use by comparing fresh vs old edges, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds behavioral detail: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp), and explains the verdict. For basket mode, it covers theoretical vs realizable sums, capture ratio, and thin_legs. No contradictions with annotations.

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

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

The description is well-structured with uppercase keywords for modes and clear separation of single-market and basket behaviors. It front-loads the purpose and requirement. While it is somewhat lengthy, all sentences are informative and earn their place. Minor trimming could improve conciseness, but overall it is 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?

Despite having no output schema, the description thoroughly explains return values for both modes, including edge cases like thin books and partial fills. It covers forced directional risk and max clean notional. For a complex tool with two modes, this provides complete context for an AI agent to understand behavior and results.

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

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

Schema description coverage is 100%, and the description goes further: it explains that 'market' is for single-market mode and 'event' for basket mode, defines 'side' defaults and values for each mode, and clarifies 'size_usd' interpretation (spend vs target proceeds for single-market; settlement notional for basket). It also notes the clamp range (10–1,000,000). This adds significant value beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and contrasts with siblings like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those actions. The verb 'check' and resource 'edge' are specific and clear.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states when not to rely solely on theoretical overround and warns about risks like partial basket fills creating unhedged positions. This gives clear context 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 goes far beyond the annotations: it discloses the token-overlap matching logic, the safety fields and their code meanings, the fee model limitation, skipped comparison counters, and the meaning of null temporal alignment. It also rightly emphasizes that compatibility_warning can be non-empty even when pairs are returned. No contradiction with readOnlyHint or idempotentHint exists.

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 exceptionally dense: every sentence adds a caveat or clarification that an agent needs for correct interpretation. It is front-loaded with the core purpose and then layers response, safety, and matching details. A slightly more structured layout with named sections would improve skimmability, but no sentence is wasted.

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly: raw prices, top_spreads_pp, compatibility fields, per-entry flags, skipped categories, fees_note, and temporal alignment semantics. Given the tool's complexity, an agent has enough information to call it and interpret the response correctly.

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

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

The schema already documents all three parameters, so the baseline is high. The description adds value by explaining how the modes interact, that explicit params override topic mappings, and that both modes run the identical matcher. This clarifies parameter semantics beyond the schema, but the schema already covers the literal fields well.

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

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

The description opens with a specific resource—'Cross-venue spread between Kalshi and Polymarket for the same resolving question'—and defines the tool's function precisely. It also names two operational modes, so an agent can immediately tell what the tool is for. Its focus on cross-venue comparison distinguishes it from the mostly single-venue sibling tools.

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

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

The description gives concrete selection guidance: use the pre-mapped topic mode for known macro shortcuts and explicit ticker/slug mode for custom pairings, and it warns that most pre-mapped topics are not currently tradeable. It does not explicitly contrast this tool with sibling tools like polymarket_arbitrage, so it stops one step short of full alternative routing.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that scoping is per identifier (IP, hash, account ID) and that omitting key lists all keys. No contradictions.

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

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

Description is two sentences with no wasted words. First sentence states core function, second adds usage guidance and scoping. 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?

For a simple tool with one optional parameter and no output schema, description covers purpose, usage, scoping, and behavior adequately. No missing critical information.

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

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

Only one parameter (key) with schema coverage 100%. Description reinforces that omitting key lists all keys, adding clarity beyond schema.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It uses a specific verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools 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?

Description explicitly says to use for looking up stored context without re-deriving it, and pairs with remember/forget. It provides clear context but does not explicitly state when not to use the 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 details mark_read behavior that modifies state (flags events as read), which contradicts the idempotentHint annotation indicating the tool is idempotent. This is a critical inconsistency.

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

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

Four sentences, front-loaded with main purpose, each sentence adds distinct value. No fluff 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?

Covers return fields, filtering, mark_read semantics, and alternative access. Lacks explicit pagination details but is sufficient for basic 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?

Though schema covers all parameters, the description adds practical context: examples of type filter ('sec_8k'), ISO timestamp format for since, and the effect of mark_read/unread_only. It also notes default limit of 50 and alternative feed URL.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the returned data (source, citation_uri, raw payload). It distinguishes itself from sibling tools, none of which perform this function.

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

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

Provides guidance on filtering by type and since, notes the mark_read option for reading state, and mentions alternative access via HTTP. However, it does not explicitly contrast with sibling tools or state when not 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO, with details on fallback triggers and a soft-fail warning for USPTO. It also mentions the return format, enhancing transparency beyond annotations.

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

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

The description is a single, dense paragraph that packs a lot of information efficiently. It front-loads with example queries, then covers sources, parameters, and alternatives. While not perfectly structured (e.g., could use bullet points), it remains focused and wastes no words.

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

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

Given the tool's complexity (multiple external APIs, fallback logic) and the absence of an output schema, the description provides a fairly complete picture. It explains the sources, fallback behavior, parameter usage, and return structure. The USPTO sunset warning adds foresight. It could mention pagination or limits, but overall it is well-rounded.

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

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

With 100% schema description coverage, the schema already documents parameters. The description adds value by explaining the 'since' parameter with both ISO date and relative shorthand examples, clarifying that 'value' can be a ticker or CIK, and noting that 'type' only supports 'company'. This enriches the schema's minimal descriptions.

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

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

The description begins with example queries that immediately convey the tool's purpose. It clearly states it returns a change feed for a company over a time window, fanning out to multiple sources in one call. It also distinguishes itself from the sibling tool 'entity_profile', making the purpose unmistakable.

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

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

The description explicitly advises using 'entity_profile' for static profiles, providing a clear alternative. It also offers guidance on the 'since' parameter ('Use "30d" or "1m" for typical monitoring'). However, it does not explicitly cover when not to use it (e.g., for real-time updates), but the context is largely 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 indicate idempotentHint=true and destructiveHint=false. The description adds important context: memory is key-value scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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, informative paragraph that covers the tool's purpose, usage, and behavior without unnecessary words. It is well-structured but could benefit from 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?

For a simple key-value storage tool, the description fully covers what the agent needs to know: purpose, when to use, storage semantics, and scope. No output schema is needed as the tool is a write operation.

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 parameters key and value are already well-documented. The description adds examples like 'subject_property' and 'target_ticker' but does not provide additional semantic depth beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address, user preference) and distinguishes from sibling tools recall and forget.

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

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

The description advises use 'when you discover something worth carrying forward' and mentions pairing with recall/forget. However, it does not explicitly state when not to use it, but the context is 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?

The description discloses cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, and source labeling—details well beyond the readOnlyHint/idempotentHint annotations. No contradiction; it enriches behavioral understanding significantly.

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-organized with clear sections and examples. It front-loads the core purpose and usage guidance. While dense, the complexity of the tool justifies the length; only minor trimming could make it slightly more concise 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?

Given the tool's complexity (multiple entity types, external sources, edge cases), the description thoroughly covers expected return values (identifiers, unresolved, figi_candidates), error handling, and usage subtleties. Even without an output schema, the prose explains what the agent will receive, making it complete for correct invocation.

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

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

Schema coverage is 100%, but the description adds essential value: it explains how to interpret `value` for different entity types, warns against common pitfalls (e.g., trailing security-class words for bonds), and clarifies the meaning of `type`. This is exactly the kind of contextual meaning that helps agents correctly populate parameters.

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

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

States a specific verb (resolve) and resource (user-spoken name to canonical identifiers), with concrete examples across entity types and clear differentiation from siblings by positioning it as the first lookup step when an ID is needed. The description leaves no doubt about what the tool 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?

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID', and provides specific input-format guidance (e.g., for bonds pass the exact issuer name, never the full noun phrase). It also explains when results are ambiguous (figi_candidates) and what behavior to expect, effectively routing the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds that it probes each entity via ai_visibility_check (internal detail), ranks by score, and returns a ranked list with score, confidence, and signal density. No annotation contradiction. Adds moderate behavioral context beyond the safety profile.

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

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

Two well-crafted sentences plus an illustrative question. Every part earns its place: purpose, method, use case, and output format. No fluff, efficiently 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?

No output schema, but description explains return format: ranked list with score, confidence, signal density per entity. For a multi-entity comparison tool with rich annotations, this is fairly complete. Minor omission: could mention ordering direction (descending by score).

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 parameters are documented. Description adds extra meaning: first entity is treated as 'subject' for narrative, and 'models' parameter explains supported options (workers-ai default, anthropic requires key). This supplements the schema meaningfully.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. The example question and mention of competitive AI-marketing audits make the purpose highly specific and distinguishable from siblings like ai_visibility_check (single entity) and compare_entities (generic 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?

Description explicitly states the tool is 'useful for competitive AI-marketing audits' and provides a concrete example question, giving clear context for when to use. It implies this tool is for multi-entity comparison rather than single-entity checks, but does not explicitly name alternatives or conditions to avoid. Still, context is 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?

Annotations already declare idempotent and read-only. Description adds significant behavioral context: fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s. No contradiction with annotations.

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

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

Description is somewhat long but every sentence adds value. Front-loaded with the key composite nature, then details. Could be slightly more concise but appropriately structured for the information density.

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

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

Given no output schema, the description fully explains what is returned (summary block, per-advisory detail, links, alternative versions) and covers edge cases (timeouts, partial failures). Comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra value: scoped packages accepted, version defaults to latest. This exceeds the baseline of 3.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, bundle size, etc. The verb 'scan' and resource 'dependency' are specific, and the description distinguishes it from sibling tools like 'scan_competitor_ai_presence'.

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

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

Explicitly says 'Use whenever an agent asks...' and provides clear conditions for when to use and when not to use (NPM ecosystem only in v1; alternatives for other ecosystems).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and behavior. The description adds value by specifying the return format (per-100g macros) and the database source (Edamam), providing behavioral 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 extremely concise: two sentences and an example, with no wasted words. All information is front-loaded and 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 no output schema, the description adequately explains the return values as 'per-100g macros (calories, protein, fat, carbs)'. It could mention additional fields like food name or ID, but the example and annotations provide sufficient context for a simple search tool.

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

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

The input schema has 100% coverage for all three parameters with descriptions. The description adds an example and clarifies the output context ('per-100g macros'), which is not in the schema. This exceeds the baseline by providing practical 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?

The description clearly states the verb 'search' and the resource 'Edamam's food database', with a specific focus on returning per-100g macros. The example further clarifies the tool's function. It distinguishes itself from siblings like 'nutrition_analysis' and 'search_recipes' by its explicit output of raw food macros.

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 does not explicitly specify when to use this tool versus alternatives such as 'nutrition_analysis' or 'search_recipes'. It implies usage for obtaining per-100g macros for a food query, but lacks explicit 'when to use' or '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?

Annotations (readOnlyHint, idempotentHint, destructiveHint) already convey safety. The description adds value by specifying return fields (calories, time, servings, ingredient lists) and example usage, which is helpful for an agent despite no output schema.

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 plus an example. Front-loaded with action and resource. Every element serves a purpose; 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 6 parameters and no output schema, the description is fairly complete: it states the action, filters, and return values. It does not mention the optional _apiKey or default limit, but these are covered in the schema. Lacks pagination or rate limit warnings, but overall adequate.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description mentions the optional filters (diet, health, cuisine) but does not add semantic detail beyond the schema. Baseline score of 3 is appropriate.

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

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

Description clearly states it searches Edamam's recipe database by keyword with optional filters, returning recipe details. While it doesn't explicitly differentiate from sibling 'search_food', the focus on recipes is specific enough to imply purpose.

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

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

The description provides an example and lists filters, implying use for recipe searches. However, it does not explicitly state when to use this tool over alternatives like 'search_food' or when not 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?

Annotations already show safe read-only, idempotent behavior. Description adds algorithmic details (BGE-base-en embeddings, cosine, 500-char windows), truncation cap (200K chars with flag), and output structure (passages with offsets and scores), exceeding annotation coverage.

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?

Highly concise and front-loaded: first sentence captures the core purpose. Every sentence adds essential information without redundancy.

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

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

Despite no output schema, the description fully explains return values (passages with offsets and similarity scores), limits (200K chars, truncation), and pairs with a sibling tool. Complete for a semantic search 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 covers all 3 parameters with descriptions. The description adds contextual meaning: 'text' is the fetched record, 'query' is natural-language with examples, 'limit' controls passage count. It also explains that passages carry offsets for verification, adding value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with examples of use cases (SEC 10-K, articles) and distinguishes itself from siblings by noting it pairs with ask_pipeworx_grounded for grounding over passages.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and provides an alternative (ask_pipeworx_grounded), giving clear usage context.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds valuable behavioral details: SMS cap (10/day), phone verification requirement, webhook auto-disable after 10 failures, and delivery channel options. However, there is a potential contradiction with idempotentHint since the description implies a new subscription ID is returned each time, which may conflict with idempotency.

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 purpose and uses structured bullet points for types and delivery channels. While slightly verbose, every sentence serves a purpose. A minor improvement would be to separate idempotency clarification.

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

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

Despite no output schema, the description covers return value (subscription ID), all parameter types, delivery options, prerequisites (OAuth account, phone verification), and limitations (SMS cap, webhook auto-disable). It is sufficiently complete for an agent to correctly invoke the 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 extensive meaning for each parameter, including type-specific examples (sec_8k, polymarket_edge, fred_series) and detailed delivery channel configurations (webhook signing, auto-disable). It fully compensates for the lack of schema-level descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, specifies types and delivery channels, and distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

It explains when to use (create subscription), mentions requirements (Pipeworx OAuth account, cannot use anonymous/BYO), and implies alternatives (list_subscriptions to view existing, unsubscribe to remove). Explicit contraindications or when-not-to-use are not stated, but the context is 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns 'category-bucketed example questions (company financials, drugs & clinical trials, ...) each with the exact tool + argument shape' and is drawn from a live catalog. 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 well-structured, starting with synonyms and then the core purpose. It is slightly long but each sentence adds value. It is front-loaded with the main use case. Could be marginally trimmed but remains highly 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers purpose, when to use, what it returns (category-bucketed examples), and how to call 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?

Schema coverage is 100% with one optional parameter 'topic'. The description adds meaning: it explains the possible values ('finance, pharma, economics, etc.') and that omitting gives a cross-category spread. This goes 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?

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('returns', 'draws from') and resources ('category-bucketed example questions', 'live catalog'). It distinguishes itself from siblings by positioning as the onboarding entry point for an agent that just connected.

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 it: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'Call with no arguments for the full spread, or pass topic to focus'. It also mentions alternative meta-tools but does not explicitly state when not to use it. However, the guidance is clear and direct.

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 value beyond annotations by specifying ownership enforcement, deactivation (not deletion), and the relationship with recent_alerts. This complements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Three sentences, each serving a distinct purpose: action, ownership, and behavioral effect. No fluff, front-loaded with the primary 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?

The description covers the main behavioral aspects but lacks return value information. Since there is no output schema, a brief note on what is returned would improve completeness.

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

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

Schema coverage is 100% and the schema already describes the id parameter. The description only mentions 'by id' without adding new meaning, so it does not significantly enhance parameter 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 'Cancel a subscription by id,' which is a specific verb-resource combination. It distinguishes from siblings like subscribe and list_subscriptions by focusing on cancellation and ownership.

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

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

The description implicitly tells when to use (to cancel a subscription) but does not explicitly contrast with alternatives. It does mention ownership enforcement and that historical events are preserved via recent_alerts, providing context for when not to use this tool.

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

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

Annotations already declare read-only, open-world, and idempotent hints, but the description adds crucial behavioral context: the distinction between could_not_verify (check did not happen) and unsupported (no source exists), and the warning that could_not_verify is not evidence. It also discloses the internal routing logic (SEC EDGAR vs grounded pipeline) and return structure.

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 and well-structured, starting with example phrasings, then purpose, routing, return value, and important warnings. Every sentence adds value, though the 'Replaces 4–6 sequential calls' is a nice-to-have and the text is fairly long, keeping it from a perfect 5.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers use cases, internal routing, verdict types, citation format, reasoning, and edge-case semantics. It also warns about the could_not_verify vs unsupported distinction, which is essential for correct handling.

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

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

The input schema already contains detailed descriptions for both parameters (100% coverage), so the baseline is 3. The description adds marginal value by noting 'exact percent-delta math' and the tolerance override for hallucination detection, but does not deeply elaborate on parameter formatting or constraints 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 natural-language claim verification against authoritative sources, with a specific verb (verify) and resource (claims). It distinguishes itself from sibling tools by focusing on factual correctness judgments with a verdict output and explicitly mentions replacing multi-step pipelines.

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

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

It provides explicit guidance on when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two routing paths for financial vs other claims. However, it does not explicitly name alternative tools or state exclusions, though it implies a consolidated workflow.

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