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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral details: it routes to one of 5,743 tools across 1,500 sources, fills arguments, and returns answers with stable pipeworx:// citation URIs. This is consistent with and extends the annotation context.

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

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

The most important guidance is front-loaded, and the examples are useful. However, the description is long, with an extensive domain list and a repetitive ending ('START HERE for most questions — for most questions'). Some trimming would tighten it 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 has no output schema, the description still explains the tool's purpose, input type, trigger conditions, example queries, and the citation-bearing return format. It is largely complete for an agent to select and invoke the tool, though it does not clarify how it relates to its grounded or beta siblings.

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

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

Schema description coverage is 100%, and all parameters are documented as aliases for the same natural-language question field. The description reinforces that input is a natural-language question and gives examples, but it does not add meaning beyond the schema. 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 the tool as a natural-language question router that returns structured answers with citations from thousands of sources, and it distinguishes itself from web search. It gives concrete example queries and lists covered domains. However, it does not distinguish itself from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description explicitly says to 'PREFER OVER WEB SEARCH' and provides trigger phrases, example questions, and a broad domain list. It also says 'START HERE for most questions,' giving clear conditions for use. It does not explicitly address when not to use it versus siblings like deep_research or validate_claim.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the live candidate-routing behavior, the current inactive candidate state with a retirement date, that there is no fallback, and that it is a full working router. This adds substantial behavioral context beyond the structured hints.

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

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

The description is longer than minimal but each sentence earns its place: beta identity, current candidate state, usage instruction, and non-fallback guarantee. It is front-loaded with the tool's identity and avoids filler.

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

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

For a beta router with no output schema, the description conveys what it does, how it relates to the stable ask_pipeworx, and the current live state. It relies on the agent knowing ask_pipeworx for the actual response shape and argument details, but that is a reasonable reference given the identical-interface statement.

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 schema already documents all parameters. The description only adds that arguments are the same as ask_pipeworx, which supports usage but does not add per-parameter meaning beyond the schema; baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, states that it is an identical universal router with the same tools, arguments, and response shape, and distinguishes it from the stable ask_pipeworx and grounded variants. This gives an agent a specific, non-tautological 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?

It explicitly instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router for merge decisions. This is clear when-to-use guidance and differentiates it from the stable sibling.

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, openWorldHint, idempotentHint, and destructiveHint, but the description goes well beyond by disclosing the exact success return shape, the refusal schema, and specific refusal_reason enum values. It also transparently reveals the cost tradeoff of an extra LLM call, which is behavioral information not present in annotations or 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?

Every sentence earns its place: purpose, routing comparison, success/refusal contract, use cases, and cost tradeoff. The structure is front-loaded with the core value proposition and then moves logically through behavior, usage, and alternative. Despite its length, there is no redundant or filler content.

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

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

With no output schema present, the description fully compensates by detailing both the success response fields and the refusal response shape. It also covers when-refusal happens, when to prefer the alternative tool, and the behavioral cost difference. Nothing an agent needs to invoke and interpret this tool safely is missing.

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

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

The schema already documents all six parameters at 100% coverage, each marked as an alias for 'question,' so the baseline is 3. The description adds no parameter-specific semantics beyond noting that the tool 'fills arguments' during routing, which does not meaningfully deepen understanding of the question parameter itself.

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 'Hallucination-resistant answer mode for high-stakes reads,' immediately defining the tool as a grounded answer mode with a specific verb-like purpose. It distinguishes itself from sibling ask_pipeworx by explicitly stating 'Same routing as ask_pipeworx' while adding that it extracts the answer 'using ONLY what the tool result contains.' This makes the tool's identity and differentiation unambiguous.

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

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

The description explicitly states when to use this mode: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples like financial verdicts and legal claims. It also gives a clear alternative and tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This fully informs selection between the tool and its sibling.

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?

Even with annotations already declaring readOnlyHint/openWorldHint/idempotentHint, the description adds substantial behavioral detail: account/paywall requirements, parallel facet decomposition, the exact findings packet composition (verbatim evidence + confidence + source + fetched_at + citation), explicit gaps[] semantics with a 'never invented' guarantee, contradictions[] for standard/thorough, a `hop` field, citation_uri always fetchability, semantic excerpting rather than head-truncation, and latency expectations. This far exceeds what annotations convey.

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

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

The description is dense and front-loaded with the most critical routing signal ('ACCOUNT REQUIRED' and 'use ask_pipeworx instead'), and every major behavioral point is present. However, some redundancy exists: the depth-level explanation in the description partially repeats the input-schema depth description, and the latency sentence could be tightened. Still, no sentence is filler.

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

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

For a complex tool with no output schema, the description fully compensates by specifying the return packet contents, the gaps[]/contradictions[] fields, the citation_uri guarantee, and performance expectations. It also covers auth prerequisites, alternative tool routing, and nuanced depth behavior. An agent has everything it needs to select and invoke this tool correctly without inspecting schema further.

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 meaningful color beyond the schema: it ties depth tiers to cost ('thorough needs a paid plan'), explains behavior per depth level ('re-angles unanswered gaps', 'chases the best leads'), and clarifies that 'broad/multi-part is fine — decomposition is the point' for the question parameter. This enrichment justifies a 4.

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

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

The description opens with a specific verb+resource pair: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' and clearly states it decomposes questions into facets routed 'IN PARALLEL' to 5,743 tools. It distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and by directing single lookups to ask_pipeworx. This is a precise, non-tautological statement of 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 explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' It also scopes the ideal use case to 'broad/multi-part questions over structured data' and names alternatives like ask_pipeworx and open-web search. No ambiguity remains about 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 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.