Paraguay Dncp

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it scores 0-100, requires a BYO API key for Anthropic (with cost implication), and returns per-model details plus a 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?

The description is concise and well-structured. It front-loads the main action, explains the default, the optional API key, and the return format—all in a few sentences. Every sentence earns its place.

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

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

Despite lacking an output schema, the description fully explains the return structure (per-model score, confidence, signals, raw_response, plus combined view). Given the moderate complexity and high schema/annotation coverage, the description is complete and 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% with all parameters described. The description adds value by explaining the default model, the purpose of '_apiKey' (pay Anthropic directly), and the disambiguation role of 'context'. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool probes LLMs for what they know about a business or topic and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are explicit, and it distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model (free) and when to provide an API key. However, it does not explicitly state when not to use this tool 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 establish a safe read-only, idempotent profile; the description adds genuinely useful behavioral context beyond them: the router fills arguments automatically, returns stable pipeworx:// citation URIs, and spans 5,908 tools / 1,540 sources. No contradiction with annotations; the only blemish is the nonsensical 'SANE_TASKS...' sentence, which makes a false claim about what this tool is for.

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 core content is well front-loaded — priority instruction, domain list, behavior, triggers, examples — and earns its length for a meta-router of this scope. But the final stretch ('START HERE... SANE_TASKS_COMBINED_SANITY_CHECK_WITH_LIVE_CONFIRMATION...') is incoherent noise that should be deleted, and the trigger-phrase sentence partially restates the opening; a tighter ending would earn a 4 or 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?

For a broad routing tool with no output schema, the description covers the essentials — what it routes, what it returns, and when to reach for it — but leaves gaps: how ask_pipeworx_beta / ask_pipeworx_grounded relate, what happens when the router cannot resolve a question, and whether multi-part questions are supported. The misleading 'for everything else' tail adds to the incompleteness.

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%: the 'question' parameter and its five aliases are fully documented in the schema itself, so the baseline is 3. The description adds value on top by exemplifying valid queries (unemployment rate, 10-K filings, Ozempic adverse events, Tokyo forecast) and explaining what the tool does with the question, which goes beyond what the schema alone provides.

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

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

States a specific behavior — routing a natural-language question to one of 5,908 tools across 1,540 verified sources and returning citation-linked structured answers — and draws a clear line against web search. It does not, however, differentiate from the adjacent siblings ask_pipeworx_beta and ask_pipeworx_grounded, and the tail sentence ('START HERE... except...') partially blurs the stated scope.

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

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

Provides unusually explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases ('what is', 'look up', 'get the latest', 'how much', 'current'), a concrete domain list, and six realistic examples. The closure is flawed, though — the vague exclusion ('except for tools explicitly designed for...') and the redirect to the nonexistent SANE_TASKS_COMBINED_SANITY_CHECK_WITH_LIVE_CONFIRMATION undercut the otherwise clear routing advice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a full working router, not a fallback/degraded stub; it is the experimental edge; and candidate routing improvements may change behavior live. This is exactly the kind of extra context the annotations don't carry.

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 block of 3 sentences, front-loaded with the beta status and key distinction, then uses-specific guidance. It is information-dense without being bloated. Minor deduct for the slightly rambling last sentence ('Falls back to nothing — this IS a full working router, just the experimental edge'), which is slightly repetitive after the opening.

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 that mirrors an existing sibling, the description completely covers what an agent needs: identical behavior, same args, same response shape, current experimental status, no active candidate, and the routing intent. There is no output schema, but the description explicitly says the response shape matches ask_pipeworx, which is sufficient given the sibling exists.

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

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

Schema description coverage is 100% and the schema itself documents the main 'question' parameter plus aliases. The description reinforces that the tool accepts the same arguments as ask_pipeworx, but doesn't enumerate parameters. Since the schema already covers all parameters, and the description adds the important 'same arguments as ask_pipeworx' context, a 4 is justified.

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

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

The description states a specific verb+resource ('Ask Pipeworx Beta') and explicitly distinguishes it from ask_pipeworx as the experimental routing variant. It explains what the tool is ('identical universal router'), its relation to the stable version, and its current behavioral equivalence. This is far more specific than a vague name/title restatement and clearly differentiates it from the sibling stable router.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains how results are compared against the stable router. It also tells the agent that no candidate is currently active, so behavior matches ask_pipeworx exactly. This is strong when-to-use guidance with an explicit alternative named.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description goes well beyond them: it explains the answer extraction is limited to the tool result, lists the exact success return fields including verbatim evidence, and enumerates the complete refusal_reason enum. It also discloses the extra LLM call cost, which is a meaningful behavioral trait.

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 without being bloated: it front-loads the core purpose, then details behavior, return shape, usage context, and cost tradeoff in logical order. Every sentence contributes something an agent needs to call the tool correctly or choose between tools.

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 real parameter and no output schema, the description is complete: it documents the success return shape, the failure/refusal shape, the sourcing behavior, and the relationship to ask_pipeworx. The annotations cover safety, and the sibling list clarifies alternatives, so nothing critical is missing.

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

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

Schema description coverage is 100%, with all six parameters being documented aliases for a single natural-language question, so the schema already fully explains the parameters. The description adds high-level context about high-stakes use but does not need to add parameter-level detail; 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 hallucination-resistant answer mode for high-stakes reads, with a specific mechanism: route to the right source, fetch data, and extract the answer only from the tool result. It explicitly differentiates itself from ask_pipeworx by the grounded extraction and refusal behavior, so an agent can distinguish it from its siblings.

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

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

The description gives an explicit when-to-use rule: whenever the answer will be quoted, cited, or acted on, and the agent must not invent facts, with concrete examples. It also gives a when-not-to-use rule: prefer ask_pipeworx for casual lookups, citing the extra LLM call cost. This is strong, actionable routing guidance.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: fan-out parallelism, resolver contract with confidence levels and alternatives, parent event extractor, news fallback mechanisms, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread tradeability, and resolution-rule risk. These details go far beyond annotations and disclose all behavioral traits.

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

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

The description is lengthy but front-loaded with the most critical purpose and usage. Every section adds value given the tool's complexity, but it could be more structured (e.g., bullet points) for readability. It is not excessively verbose, but conciseness could be improved slightly.

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 thoroughly explains all response fields: result.market (bid/ask, liquidity, price change), result.analysis (model probability, edge, kelly fraction, 24h move warning), result.evidence (keyed by source), resolver contract (confidence, alternatives, suggestions), parent event (top legs), news fields (fallback info), and status codes (low_confidence_match, market_closed_or_inactive). It also covers resolution-rule risk and tradeability. Everything an agent needs to interpret the response is included.

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 significant value: it explains the three input formats for 'market', the meaning of 'depth' (quick vs thorough with examples), and the purpose of 'include_raw' (summarized vs full payloads). It also notes defaults and behavioral implications, enhancing the schema's documentation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The detailed classifiers, fan-out examples, and response shapes distinguish it from sibling tools like polymarket_edges or polymarket_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?

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also explains when to inspect certain fields (e.g., market_match_confidence, parent_event) and caveats for low-confidence resolutions, closed markets, wide spreads, and resolution-rule risk. It implicitly differentiates from siblings by focusing on comprehensive single-bet research.

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

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

The description adds significant context beyond annotations, including data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, and return format (paired data + citation URIs). 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-organized with examples upfront, but slightly verbose. Every sentence adds value, though could be trimmed without loss of 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 lacking an output schema, the description fully explains return types, sorting, and efficiency gains. It covers both entity types thoroughly and addresses edge cases like fiscal year 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?

Schema coverage is 100%, and the description enriches parameter meaning by explaining expected formats (tickers/CIKs for companies, drug names) and constraints (2-5 items). The type parameter is clearly differentiated.

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, specifying data sources for each type. It includes example queries and distinguishes from sequential lookups, making the purpose unambiguous.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups, provides example natural language queries, and clarifies behavior for fiscal years. The guidelines are comprehensive and actionable.

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

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

Annotations already declare read-only/open-world/idempotent, lowering the bar, and the description clears it easily: never-invented gaps[], resolvable citation_uri only when fetchable, contradictions[] for standard/thorough, semantic excerpting (not head-truncated), a hop field per finding, and concrete latency expectations (15-60s, ~90s for thorough). This is substantial behavioral context beyond the annotations, with 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?

Dense and well front-loaded: the account gate and core purpose land in the first two sentences, and nearly every sentence adds new information. Docked for a redundant stray fragment ('(one LLM call, not many)') that repeats 'in ONE call', and the ask_pipeworx routing advice appears three separate times, which slightly blunts the structure.

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 return values, and it does so thoroughly: findings packet fields (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[], contradictions[], hop, and citation_uri semantics. Auth requirements, tier gating, latency, data coverage, and alternatives are all covered. For a tool this complex, nothing essential is missing.

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

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

Schema coverage is 100% and the depth enum description is already rich (facet counts, default, hop behavior, contradictions scan), so the baseline is 3. The description adds real value on top: thorough being paid, the gap-recovery vs. lead-chasing difference across depths, and latency consequences of each depth — all of which inform parameter choice. Not a 5 because the schema already carries most of the depth 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 a specific verb+resource ('Grounded multi-source research across Pipeworx's 1540 STRUCTURED data sources') plus the mechanism (facets routed to 5,908 tools in parallel) and an explicit negative scope ('this is NOT open-web search'). It also names its nearest sibling as what it is not, so an agent can distinguish it from ask_pipeworx and its other 30 siblings without opening any schema.

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

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

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), and a hard precondition ('If you are not signed in, use ask_pipeworx instead'). It even routes a specific edge case (breaking/colloquial/current-news topics) to the alternative and states that depth:'thorough' requires a paid plan. Nothing is left to inference.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: it explains that results include 'names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This clarifies the non-destructive, convenient nature of the tool.

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

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

The description is three sentences long, front-loaded with the primary purpose. The middle sentence contains a long list of domains, which, while informative, slightly reduces conciseness. Overall, every sentence adds value, but the list could be more succinct.

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

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

There is no output schema, so the description compensates well by stating the output format: 'top-N most relevant tools with names, descriptions, and full input schemas.' It also mentions default limit (20) and max. The tool is a discovery meta-tool, and the description covers its behavior adequately. A minor gap: it does not explicitly state that it searches only among available tools (not external data), but that is implied.

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 each parameter thoroughly. The description enhances by providing natural language usage context and examples (e.g., 'analyze housing market trends', 'look up FDA drug approvals'), which helps an agent understand semantic intent beyond parameter names.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the tool's purpose as a discovery mechanism. It lists numerous specific domains (SEC filings, financials, FDA drugs, etc.) and contrasts with sibling tools like ask_pipeworx or entity_profile, which are specialized data retrieval 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 directs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies when to use: 'browse, search, look up, or discover what tools exist for...' This provides strong context for both when and when not 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 declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower, yet the description still adds exceptional context: soft-fail sources (XBRL, USPTO sunset), the semantic that an empty section is 'real no data, not a bug', sources_used/sources_failed transparency, name-vs-ticker resolution, the resolved:false contract for private companies, and the expectation that small-molecule-only drug companies show no FDA products. 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 a dense single paragraph with heavy parenthetical usage, which hurts scannability for an agent parsing it programmatically. However, every clause earns its place: examples, source list, return contract, error semantics, and parameter behavior are all load-bearing. The purpose and the 'ALWAYS PREFER' directive are front-loaded before implementation details.

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

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

There is no output schema, so the description carries the full burden of explaining returns — and it does: cik, company_name, resolved_from/to, recent_filings with pipeworx:// URIs, fundamentals fields, the sources_used/sources_failed contract, and the resolved:false note for private companies. All input shapes, expected empty results, and soft-fail behaviors are covered. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters, giving a baseline of 3. The description adds value beyond it with concrete examples ('AAPL', '0000320193', 'Moderna'), the behavioral consequence of each input form (name resolution via EDGAR match), and the resolved_from/resolved_to edge case. It reinforces rather than replaces the schema, meriting one point above baseline.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' backed by seven concrete query examples. It enumerates the exact sources fanned out (SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, GDELT/GNews, GLEIF) and the return fields, which cleanly separates it from siblings like resolve_entity (single-entity resolution) and deep_research (multi-step research).

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 directs the agent: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' naming the alternative and the condition that selects this tool. The example utterances operationalize the trigger. It does not, however, say when to choose a sibling like deep_research or compare_entities instead, leaving some routing to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is clear. The description adds little beyond confirming deletion, but does not contradict 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 context, no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers usage, when to use, and pairing with siblings, making it 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% with one parameter 'key' described as 'Memory key to delete'. The description does not add extra semantic detail, so baseline 3 is appropriate.

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

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

The description uses the verb 'Delete' and specifies the resource 'memory by key', clearly distinguishing its purpose from siblings like 'remember' and 'recall'.

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

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

It explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data', and mentions pairing with 'remember' and 'recall'.

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. The description adds value by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown format. 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 concise (four sentences), front-loads the main action, and includes output format and use cases. Every sentence is informative with no redundancy.

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

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

Given two simple parameters, no output schema, and comprehensive annotations, the description sufficiently explains input, process, and output. It lacks error handling details but is complete enough for a non-critical 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 description coverage is 100% and adequately describes both parameters. The description does not add new semantic meaning beyond the schema; it reiterates the process but not parameter details. Thus, baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It lists specific AI crawlers and use cases, making it distinct from siblings like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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

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

The description explicitly mentions when to use it (getting a client's site indexed, drafting for own project, auditing competitors) and implies it's for generating the file, not for checking existing ones. However, it does not explicitly exclude alternatives or state when not to use.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds that it only returns active subscriptions by default and the specific fields, providing additional 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?

Two sentences with no wasted words; every sentence adds value.

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

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

With only one optional parameter, no output schema, and annotations present, the description fully covers the return fields, usage context, and parameter purpose.

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 does not add meaning beyond what the schema already provides for the single optional parameter (include_inactive).

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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.), distinguishing it from siblings like subscribe/unsubscribe.

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

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

Explicitly tells when to use: to review monitored subscriptions before adding more or to find an id to cancel.

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 value by specifying the API source, return format (OCDS release), field details (ocid, title, buyer, etc.), and language notes (Spanish values, English keys).

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 well-structured sentences that front-load the purpose, then provide input and output details. No wasted words; each sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully covers API source, input alternatives, output fields, and language nuances. Complete for the given 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 examples. Description adds clarity by explicitly stating acceptable input formats and providing concrete examples, enhancing 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 uses the specific verb 'Get' and identifies the resource as 'full Paraguay procurement record'. It distinguishes from the sibling tool 'paraguay_search_tenders' by focusing on retrieving a single record by ID rather than searching.

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 clear input format guidance with examples (numeric ID or ocid). No explicit when-not or alternative usage, but the purpose is distinct enough that usage is implied from the sibling context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds crucial behavioral context: date scoping, paginated results, client-side filtering, and the fact that field values are in Spanish and amounts in PYG, which annotations do not cover.

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

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

The description is a single paragraph that efficiently conveys all necessary information without redundancy. It is front-loaded with the core purpose. Could be slightly more structured (e.g., bullet points), but it remains clear and easy to read.

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 4 parameters, no output schema, and moderate complexity, the description adequately explains the return fields, pagination, and date defaults. It does not detail pagination navigation or error conditions, but for a search tool this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining defaults for date parameters, clarifying that 'query' is a client-side filter, and mentioning the API parameter names (fecha_hasta, fecha_desde). This additional context warrants 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 clearly states it searches Paraguay government procurement processes from the official DNCP OCDS API, specifying the returned fields and noting Spanish-language values and PYG currency. It distinguishes from the sibling tool paraguay_get_record by directing users there for detailed records.

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

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

The description provides explicit usage guidance: the API requires a date range, defaults to the last 30 days, and explains that 'query' is a client-side filter with no server-side free-text search. It also tells users to use paraguay_get_record for full details, effectively distinguishing when to use which 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 provide no hints (all false), so the description carries the entire burden. It discloses rate limits (5 per identifier per day), that it's free and not quota-counted, the claim_token flow for later retrieval, and that feedback is read daily by the team. It does not explicitly state whether the feedback is sent to an external server or how long tokens remain valid, but covers the key behavioral traits.

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

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

The description is dense but every sentence adds value: purpose, use cases, exclusions, instructions, token mechanism, team behavior, rate limit, and cost. It is front-loaded with the core purpose and clearly structured, making it easy to scan despite its length.

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

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

With no output schema, the description must explain return behavior, and it does: the claim_token returned on filing and the later ability to read status. It covers the tool's scope, usage constraints, and token mechanics. Minor gaps like exact response format after filing or token expiration prevent a 5, but it is complete enough for an agent to use effectively.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining the claim_token's purpose and usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which goes beyond the schema. It also reinforces the meaning of each enum value in the type parameter, increasing clarity.

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

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

The description uses a specific verb phrase, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly defines the tool's purpose. It also distinguishes this tool from siblings by explicitly restricting it to feedback about Pipeworx tools and mentioning the return of a claim token, something no sibling 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?

The description provides explicit use cases: bug, feature/data_gap, and praise, with detailed definitions. It also gives a clear exclusion criterion: feedback about tools from other MCP servers should be filed elsewhere. This is exemplary when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching intervals (5min-1h). 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?

Three sentences efficiently cover purpose, use cases, and technical details. Front-loaded with core functionality, then use cases, then caching. Every sentence adds value, 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 read-only info tool with one optional parameter, the description explains the output (top tools, packs, call volume) and caching behavior. Annotations cover safety. No output schema is needed as description clarifies return structure.

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 provides full enum and description for the single parameter. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enriches the enum values beyond simple labels.

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 'the top tools, top packs, and total call volume over a recent window,' specifying the verb (returns) and resource (Pipeworx trending data). This distinguishes it from sibling tools like 'discover_tools' or 'ask_pipeworx' which serve different purposes.

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?

Three explicit use cases are listed, covering discovery, confirmation, and alignment. Window options are contrasted for hot vs steady-state. While no 'when not to use' is given, the context is clear and helpful.

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 context: 'walks child markets', 'checks date-axis/threshold-axis ordering', 'partition_check (sum of YES prices... deviations >3pp emit BUY/SELL EVERY LEG signal)', 'SEMANTIC ANCHOR using Jaccard similarity', 'PARTITION FILTER drops placeholder slugs', 'FILL CHECK against live CLOB depth'. 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 longer than typical but each sentence adds value. Structure is logical: overall purpose, three modes with detailed behavior, advanced features (semantic anchor, partition filter, fill check), and referral to sibling tool. Front-loaded with purpose. Could trim minor redundancy like 'Call with NO args' vs 'for a trending scan' but still efficient given complexity.

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

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

No output schema, yet description fully explains response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)', 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}', and 'fill_check{theoretical_edge_pp_at_book, realizable_edge_pp at 1000 shares/leg, thin_legs[]}'. Covers edge cases like 'skipped_low_similarity' and 'placeholders_filtered'. Complete for a complex arbitrage detection 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% but description adds rich meaning beyond schema. For event: 'pass a Polymarket event slug... walks child markets, checks date-axis/threshold-axis ordering AND computes partition_check'. For topic: 'pass a seed question... searches related events, flattens markets, runs comparator on union. Cross-event mode catches patterns that single-event misses.' Schema only says 'event slug' or 'topic string'; description transforms these into actionable behavior.

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 finds arbitrage opportunities via 'monotonicity violations + partition-sum checks'. It distinguishes three modes: no args for trending scan, event for single-event mode, and topic for cross-event scan. The verb 'find' and specific resource 'arbitrage opportunities on Polymarket' make purpose unambiguous.

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

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

Explicit guidance: 'Call with NO args for a trending scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. It also explains when not to trade via fill check: 'realizable_edge_pp ≤ 0 means... do not trade it'. Alternatives mentioned: 'For custom sizing use polymarket_fill_risk'. This fully satisfies when-to-use and when-not.

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 far exceeds annotations by detailing three model families, caching behavior (1h at KV level), response structure including diagnostics, and specific edge calculations (edge_pp_net, kelly_fraction). It also mentions Fed bets exclusion and filter knobs, providing rich behavioral context beyond the readOnly/idempotent hints.

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

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

The description is comprehensive but verbose and densely packed with technical jargon. While it front-loads the purpose, the detailed model explanations could be streamlined for quicker consumption. It earns a 3 as it is adequate for an AI agent but not optimally 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 9 parameters, no required params, 100% schema coverage, and no output schema, the description thoroughly covers expected outputs (by_segment, diagnostics, edge fields), caching, Fed exclusion, and filter mechanisms. It left no gaps for an AI agent to interpret the tool's behavior.

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

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

The input schema has 100% coverage with detailed descriptions for all 9 parameters. The tool description adds cross-referencing context (e.g., 'TRADEABLE-EDGE KNOBS') that explains how parameters interact, which enhances understanding beyond individual parameter descriptions.

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

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

The description clearly states that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It explicitly says it's built for 'what should I bet on today' and distinguishes itself from sibling tools by focusing on edge discovery without manual paging.

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

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

The description provides clear guidance on when to use the tool (for discovering betting opportunities) and hints at alternatives (e.g., 'agents discover opportunities without paging hundreds of markets'). It also explains tradeable-edge knobs and response structure, but does not explicitly state when not to use or compare to specific siblings.

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

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

Annotations indicate safe read-only/idempotent behavior. Description adds rich detail: data source (daily snapshots), TTL limits, gap handling, computation details (daily closes, not intraday), and response 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?

Efficiently structured: purpose first, then response format, then limitations. Every sentence adds value, no fluff.

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

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

With no output schema, description fully explains response structure (tracked, expired, snapshot_dates) and field meanings. Covers limitations and edge cases (gaps, TTL). Complete for agent usage.

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

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

Schema coverage is 100%. Description repeats parameter info with minor additions (defaults, valid values). No new semantics beyond schema, meeting baseline.

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

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

Clear purpose: 'Edge persistence and decay telemetry' with specific question 'how long has this edge existed?' Distinguishes from siblings like polymarket_edges by focusing on time-series trends.

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: to assess edge longevity and decay. Implicitly contrasts with fresh edges via example, but could be more explicit about when to use 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 (readOnlyHint, idempotentHint) indicate safe read operations. The description adds specific behavioral details: walks the order book ladder, computes VWAP fill price, slippage, verdicts (clean|degraded|cannot_fill), and warns about forced directional 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 well-structured with bold section headers and bullet-like formatting. It front-loads the core purpose and uses explicit marker words (SINGLE-MARKET, BASKET). While slightly lengthy, every sentence serves a purpose, and no filler is present.

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 is provided, so the description must explain return values. It fully enumerates outputs for both single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket modes (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, baseline 3. The description adds significant meaning: explains the dual interpretation of side (single-market vs basket), default auto behavior for basket, and clarifies that size_usd represents settlement notional in basket mode. Also documents the requirement for one of market or event.

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 a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check. The purpose is unambiguous.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (partial fills convert arb to directional position, the dominant loss mode) and distinguishes between single-market and basket modes with clear requirements.

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

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

The description discloses several non-obvious behaviors beyond the annotations: spreads are gross because Kalshi fees are not modeled, compatibility warnings can be non-empty even when matched_pairs > 0, temporal_alignment null means 'could not be computed' rather than 'aligned', and unknown-metric legs are never paired. This is far beyond what the readOnly/idempotent annotations provide.

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

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

The description is front-loaded with a clear purpose, but it is a very long, dense paragraph. It repeats warnings across prose, codes, and flags, and uses uppercase labels instead of clearer formatting. Every sentence carries useful content, but the overall structure could be tightened.

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

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

There is no output schema, so the description carries the full burden of explaining return values and warnings. It covers top_spreads_pp, compatibility codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skip counters. An agent has enough information to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that topic auto-fetches the matching event on each venue, explicit params override the topic-mapped side, and both modes run the identical token-overlap matcher. This helps agents understand mode interaction 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 exactly what the tool does: computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It names both venues, the object of comparison, and the two modes, making it clearly distinguishable from one-venue siblings like polymarket_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 gives clear mode-selection guidance: use topic shortcuts for pre-mapped macros and explicit ticker/slug for custom pairings, and warns that most pre-mapped topics return compatibility warnings today. It does not explicitly contrast with sibling tools, but the internal routing and caveats are 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 and non-destructive behavior. The description adds valuable context: scoping to user identifier, listing all keys when key omitted, and pairing with remember/forget. 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 concise, well-structured, and front-loaded with the primary action. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers all necessary aspects: retrieval, listing, scoping, pairing, and typical use cases. It is fully informative for an agent.

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

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

Schema coverage is 100% and already describes the 'key' parameter and its omission for listing. The description repeats that information but adds examples. It does not significantly enhance 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 retrieves a saved value or lists all keys. The verb 'retrieve' and resource 'value' or 'keys' are specific. It distinguishes from siblings 'remember' and 'forget' by stating the pairing.

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 examples (e.g., 'user's target ticker, an address, prior research notes') and explains scoping. It does not explicitly compare to other retrieval tools, but the pairing with remember/forget 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?

Description states that mark_read mutates state (flags events read), contradicting the readOnlyHint=true annotation. This is a critical inconsistency that misleads about side effects.

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

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

Four sentences, each earning its place: purpose, return format, filtering/mark behavior, alternative access. Front-loaded with primary purpose. No fluff.

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

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

Covers return structure, polling suitability, and alternative endpoint. No output schema, so description compensates. Lacks details on authentication or rate limits, but annotations imply open access.

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

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

Schema coverage is 100%, but description adds valuable context beyond schema: explains type format (e.g. 'sec_8k'), ISO timestamp for since, and effect of mark_read. Adds meaning beyond parameter names/descriptions.

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

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

Clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, raw payload), and mentions filtering options. Distinct from sibling tools like list_subscriptions.

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

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

Provides explicit filtering guidance (type, since), describes mark_read behavior for polling, and notes alternative access via URL. Lacks explicit when-not-to-use but effectively guides usage.

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

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

The description details the internal fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO (with soft-fail note), plus the return format. This adds significant context beyond the annotations (readOnlyHint, idempotentHint). 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 thorough but slightly verbose due to the list of example queries at the start. However, it is well-structured and front-loaded with the 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?

Given the complexity (multiple sources, fallback, soft-fail), no output schema, but the description covers the return structure and parameter behavior comprehensively, making it complete for an AI agent.

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

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

Schema coverage is 100%, and the description enriches parameters with usage examples (e.g., '30d', ticker vs. CIK) and clarifies that 'type' only supports 'company'.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with example queries and explicit differentiation from the sibling 'entity_profile' tool.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' and explains the 'since' parameter with examples (ISO date vs. relative shorthand).

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

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

Adds key behavioral details beyond annotations: scoping by identifier, persistence duration (24h for anonymous, persistent for authenticated). No contradiction with annotations.

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

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

Four sentences, each adding value, front-loaded with purpose, no superfluous 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?

For a simple save tool, the description provides complete context: purpose, scope, pairing, and retention policy.

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 descriptions; the description does not add new parameter-level detail beyond that.

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

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

The description uses a specific verb 'save' and resource 'data to reuse later', clearly distinguishing the tool from siblings like 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?

States when to use ('when you discover something worth carrying forward') and pairs with recall/forget, but does not explicitly exclude use cases.

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

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

Beyond the read-only/idempotent annotations, the description discloses cascading internal lookups, graceful degradation of LEI/FIGI enrichment, ISIN-to-LEI mapping for non-US issuers, and that non-equity instruments resolve. It also specifies return components (CIK, ticker, LEI, FIGI, RxCUI, brand, etc.) and the citation URI, giving an agent a realistic model of call effects.

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 each clause carries distinct information; the example queries front-load intent and the supported-type breakdown is structured. It is long enough to cover a complex multi-endpoint tool, though a bulleted layout would improve scannability.

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

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

For a tool with no output schema, the description enumerates the returned identifiers and fallback behavior (EDGAR still returns if GLEIF/OpenFIGI unavailable). It covers input formats, supported entity types, ownership questions, and the replacement of multiple lookups. It does not describe result shape for ambiguous matches, but the listed fields and degradation rule suffice.

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

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

The schema already documents both parameters (100% coverage), including the entity-name-only warning. The description adds ISIN as an accepted input, the exact-ticker-map behavior, and clarifies that a bond should pass the issuer name, which goes beyond the structured schema. No param is left opaque.

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

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

The description opens with concrete example queries, then defines the tool as resolving a user-spoken name to canonical identifiers required by other tools. It differentiates from siblings by positioning itself as the first step when you have a name but need an ID, and enumerates supported types.

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 FIRST whenever you have a name but need an ID', giving a clear trigger condition. It does not name alternative tools or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it probes each entity with 'ai_visibility_check', ranks results, and returns a ranked list with score, confidence, and signal density. This explains the process beyond annotation 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?

Two sentences: first states purpose and mechanism, second provides use case and output summary. Every sentence adds value with zero redundancy. Front-loaded with key action verb.

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 specifies return: 'ranked list with score, confidence, signal density per entity.' Input schema is fully described. Adequate for agent to understand inputs and outputs, though exact return structure is slightly vague.

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% for 4 parameters. The description does not add meaning beyond schema descriptions (e.g., 'entities' is already described as array of brand names with first as subject). Baseline 3 is appropriate since the schema carries the load.

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 ('Compare', 'Probes', 'ranks') and resources ('AI visibility across multiple entities'), clearly distinguishing it from siblings like 'ai_visibility_check' (single entity). It states the tool performs a side-by-side comparison and surfaces most/least recognized.

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 clear context: 'Useful for competitive AI-marketing audits' with an example question. Implies when to use (multi-entity comparison) but does not explicitly state when not to use or name alternatives. Given sibling 'ai_visibility_check' is single-entity, the comparison is implicit.

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

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

Description discloses extensive behavioral traits: fans out across deps.dev and bundlephobia, partial failure handling, bundlephobia's first measurement delay (5-30s), and sources_failed list. Annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and complemented.

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

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

The description is a single paragraph but front-loads the main purpose and packs in substantial detail. Slightly dense, but effective and not overly verbose.

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

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

Despite no output schema, the description thoroughly explains the return format (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases like partial failures. This makes the tool's behavior fully predictable.

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 adds no significant meaning beyond what is already in the schema. Both parameters (package and version) are well-described in the schema, and the description merely restates them without extra context.

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

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

The description clearly states the tool is a composite 'should I add this npm package' check, listing specific features (license, advisories, version history, bundle size, ESM/tree-shake). It distinguishes from sibling tools like 'compare_entities' and 'entity_profile' by focusing on npm dependency analysis.

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

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

Explicitly advises use when an agent asks about safety, popularity, size, or cost of adding a package. Also specifies ecosystem (NPM only in v1) and points to alternatives for other ecosystems (deps.dev:version).

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

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

Adds rich behavioral context beyond annotations: BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation and flagging, character offsets, and similarity scores. 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?

Three sentences, front-loaded with purpose. Every sentence adds value—purpose, usage, technical details. No wasted words.

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

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

No output schema, but description explains return format (top-N passages with offsets and similarity scores) and truncation behavior. Thorough for a 3-param tool with no output schema.

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

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

Schema coverage is 100%, but description adds extra meaning: for text it clarifies max ~200K chars, for query it gives example queries, and for limit it specifies range 1-20 and default 5, which is not 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?

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb+resource, and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

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

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

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

Adds significant behavioral context beyond annotations: OAuth requirement, delivery channel specifics (email, SMS with 10/day cap, webhook auto-disable after 10 failures, HMAC signing details). 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?

Concise yet comprehensive; frontloads purpose and requirements, organizes details logically without redundancy. Every sentence adds necessary 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?

Covers OAuth requirement, all subscription types with parameter structures, delivery channels with limitations, and return value. No output schema, but return value is mentioned. Sufficient for a complex parameterized tool.

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

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

Schema description coverage is 100%, but the description enriches parameter meaning with concrete examples for each type and delivery field, explaining constraints like phone verification and webhook signature. Adds value beyond schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream, specifies the return of a subscription id, and distinguishes from sibling tools 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?

Explains requirement for Pipeworx OAuth account, lists supported subscription types with examples, and mentions delivery options with constraints like phone verification and daily cap. Lacks explicit when-not-to-use or alternatives, but prerequisites are clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns category-bucketed example questions with exact tool + argument shapes. No contradictions exist.

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 with useful information but slightly verbose. Every sentence earns its place, covering purpose, usage, and examples. It could be tightened slightly without losing meaning.

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

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

Given one optional parameter, no output schema, and the tool's role as an onboarding entry point among many siblings, the description fully covers what an agent needs: when to use, what to expect, and how to customize. No gaps remain.

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

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

Schema coverage is 100% with a single optional parameter. The description adds value by listing example topic values (finance, pharma, etc.) and explaining behavior when omitted (full spread), which the schema alone does not convey.

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: an onboarding entry point that returns category-bucketed example questions with tool shapes. It uses specific verbs like 'returns' and 'use this FIRST', and distinguishes it from siblings by clearly defining when to invoke it.

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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear context. However, it does not explicitly state when NOT to use it or cite alternative tools beyond mentioning meta-tools.

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

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

Discloses important behavior beyond annotations: ownership enforcement and deactivation vs deletion. Aligns with annotations (destructiveHint=false, idempotentHint=true). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with core action, then behavioral notes. Highly 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?

Complete for a simple one-parameter tool with no output schema. Covers action, side effects, ownership, and alternatives for historical data.

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

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

Schema already provides description for the single parameter (id). Description does not add extra param info, which is acceptable given 100% schema coverage.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explains ownership enforcement and that the row is deactivated not deleted, with historical events accessible via recent_alerts. Provides context for when to use, though not explicitly listing when not to.

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

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

Annotations already cover read-only/idempotent; the description adds essential behavior: verdict enums, grounded/structured value with citation, reasoning, and critical caveats about could_not_verify and unsupported. 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?

Though long, every sentence earns its place: trigger examples, routing logic, verdict list, caveats, and efficiency claim. The description is front-loaded with use cases and avoids 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?

With no output schema, the description fully explains return values and edge cases. It covers failure modes, routing, and interpretation pitfalls, making the tool self-sufficient for an agent.

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

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

Schema covers both parameters at 100%, but description adds semantic detail beyond schema: tolerance_pct range, override behavior, hallucination-detection suggestion, and default cap. This 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 states a specific verb and resource: natural-language claim verification against authoritative sources. It includes trigger phrases and clearly distinguishes this tool from siblings like ask_pipeworx by focusing on fact-checking with SEC/grounded routing.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains routing for company-financial vs other claims. It doesn't name specific sibling exclusions, but the guidance is strong and actionable.

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