Chile Procurement

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

Annotations declare safe, idempotent, read-only behavior. The description adds valuable behavioral context: cost implications of Anthropic probing (BYO key, direct payment), default free model, and a description of the return structure (per-model score, confidence, signals, raw_response). 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?

Two sentences with no wasted words. The first sentence clearly states the primary action and output; the second adds default behavior, optional extension, and example use cases. Well-structured and front-loaded.

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

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

Given the tool's complexity (4 parameters, no output schema, annotations present), the description fully explains the purpose, parameters, model choices, and return format. It provides all necessary information for correct invocation without needing additional context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying the default model, the purpose of _apiKey (required for Anthropic), and explaining the context parameter's role in disambiguation, thus adding value beyond the schema.

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

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

The description states a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic'), with a clear outcome ('score visibility 0-100 per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on multi-model probing and scoring.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). While it doesn't explicitly state when not to use or list alternatives, the use cases are clearly communicated, and sibling tool names provide context for alternatives.

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

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

Annotations already provide read-only, open-world, idempotent, non-destructive hints. The description adds valuable behavioral detail beyond that: it routes to one of 5,798 tools, fills arguments automatically, and returns stable citation URIs. No contradiction with annotations is present.

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

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

The description is front-loaded with the key guidance and includes useful examples. However, a substantial block is duplicated: 'even if web search could also answer it. Examples: ...' appears twice, and 'START HERE for most questions' also appears twice. This redundancy makes it longer than necessary.

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

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

For a router tool with a simple schema and no output schema, the description is largely complete: it covers when to use it, what it returns, and the key alternative (deep_research). It does not, however, differentiate ask_pipeworx from the close sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, which an agent selecting among the sibling tools would need to know.

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 fully documents the single conceptual parameter and its aliases, so schema coverage is 100%. The description does not add parameter-level details, but it doesn't need to; the schema already carries that burden. 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 defines the tool as a router for factual/structured-data questions, explicitly listing domains (SEC filings, FDA, FRED/BLS, patents, weather, etc.) and stating it returns answers with pipeworx:// citation URIs. It also distinguishes itself from web search, which makes its purpose unmistakable.

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

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

The description gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete examples. It also provides a clear alternative condition: use deep_research for many parallel sub-questions that should fan out across sources, and clarifies breaking-news is already handled by ask_pipeworx.

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

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

Beyond annotations, the description discloses that this is a full working router with no fallback ('Falls back to nothing — this IS a full working router'), that candidate routing improvements may be enabled live, and that results are compared against the stable router. This adds meaningful experimental context on top of the read-only/idempotent 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, with the first sentence front-loading the core identity and distinction from ask_pipeworx. The specificity about the last candidate retirement date is slightly verbose, but it earns its place by clarifying the current operational state. Overall compact and well-ordered.

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

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

For a beta wrapper, the description covers purpose, current state, usage versus the stable alternative, and fallback behavior. It points to ask_pipeworx for the response shape, which is sufficient given no output schema exists. The description is complete enough for an agent to decide whether and how to invoke it.

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 six parameters documented as aliases for 'question'. The description does not add parameter-level detail beyond noting 'same arguments' as ask_pipeworx, so the schema carries the burden. A score of 3 is the appropriate baseline when the schema already fully documents parameters.

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

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

The description states it is a beta version of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape. This clearly distinguishes it from the stable sibling ask_pipeworx. The main weakness is that it relies on the 'router' metaphor rather than an explicit verb like 'answers questions', though context makes the function clear.

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

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

Explicitly provides usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It names the alternative, gives a selection condition, and states current behavior matches ask_pipeworx. This leaves nothing 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?

The annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: the exact success response shape, the structured refusal reasons for each failure mode, the verbatim-evidence guarantee, and the cost overhead. There is no contradiction between the description and 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?

Although the description is longer than average, every sentence earns its place: purpose, mechanism, return contract, refusal contract, usage cases, and cost/alternative. The key behavior is front-loaded in the first sentence, and the detail is dense rather than redundant.

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 it does so completely — including the refusal contract and refusal_reason enum values. It also covers when to use, when not to use, and how it differs from the sibling tool, so an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single semantic parameter 'question' and its aliases. The description does not repeat parameter details, which is appropriate; it also adds no extra parameter-level meaning, so the baseline of 3 applies.

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

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

The description opens by naming the exact function — a 'Hallucination-resistant answer mode for high-stakes reads' — and explains the mechanism: it routes like ask_pipeworx, fetches data, and extracts the answer using only the tool result. This clearly distinguishes it from the sibling ask_pipeworx by pointing out the same routing but a different answer-extraction behavior.

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 is given: use it when an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative — 'prefer ask_pipeworx for casual lookups' — and mentions the extra LLM call cost, which is exactly the kind of trade-off an agent needs.

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 extensive behavioral detail beyond readOnlyHint and idempotentHint annotations: fan-out resolution process, resolver contract with confidence scoring, parent event extraction, news fallback handling, cancellation risk parsing, and safety gates for low-confidence matches. 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?

Well-structured with CAPS headers and example-driven explanations, but the description is very long. Information is front-loaded with core purpose, but some redundancy exists (e.g., repeated mentions of fallback fields). Efficient for the complexity, but could be trimmed 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?

For a tool with 3 parameters and no output schema, the description covers all critical aspects: input flexibility, parallel fan-out, response shapes (market, analysis, evidence), error conditions (low-confidence, closed markets), special cases (wide spreads, cancellation rules), and data source details. Leaves minimal gaps for agent understanding.

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

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

The schema has 100% coverage with descriptions, but the description goes far beyond: explains market input formats (slug, URL, question), depth impacts on evidence volume, include_raw effect on response size, and even links depth to number of sources. Provides elaborate examples and classifiers that clarify parameter 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' with specific verb (Research) and resource (Polymarket bet). It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on broad research, including evidence packets and market comparison.

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

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

Provides explicit use cases: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. Also covers quick vs thorough modes and describes when the tool short-circuits (low confidence, closed markets). However, it does not explicitly contrast with specific siblings, so it lacks full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the list of return fields but no additional behavioral traits beyond what annotations provide. Bar lowered by annotations, description provides moderate context.

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

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

Description is one concise paragraph with front-loaded action and return fields. Every sentence adds value; no redundancy or 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 single-parameter read-only tool with no output schema, the description fully covers what the tool returns (name, description, status, dates, line items). Complete and sufficient for agent invocation.

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

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

Schema coverage is 100% with parameter description already in schema. The description repeats the example and CodigoExterno explanation, adding minimal semantics beyond the schema. Baseline 3 applies.

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

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

The description clearly specifies the tool retrieves full details of a single Chile government tender by its código, including source (Mercado Público / ChileCompra) and an example. It distinguishes from sibling chile_search_tenders by directing users to that tool for obtaining códigos.

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

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

The description explicitly instructs to get códigos from chile_search_tenders, providing clear context for use. It lacks explicit when-not guidance but is sufficient for this simple, single-purpose 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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description fully aligns with these. It adds valuable behavioral details: return fields (código, name, status, closing date), keyword matching specifics (Spanish, accent-insensitive, stemming), and mutual exclusivity of fecha and estado. 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 four concise sentences, front-loaded with the primary purpose. Every sentence adds essential information without redundancy. It is well-structured for quick parsing by an AI agent.

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 optional parameters, no required parameters, and no output schema, the description fully covers usage: default behavior, parameter combinations, filtering logic, and a pointer to the detail tool. It is complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining defaults (today), keyword behavior (Spanish, stemming), mutual exclusivity, and providing examples. This goes beyond schema descriptions, justifying 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 specifies the verb 'Search' and the resource 'Chile government procurement tenders (licitaciones) from Mercado Público / ChileCompra'. It explicitly distinguishes from the sibling tool 'chile_get_tender', which is used for full detail. This meets the highest standard of purpose clarity.

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 concrete usage instructions: default returns today's tenders, use estado='activas' for open tenders, use fecha for a specific day, and use chile_get_tender for details. It explains keyword filtering in Spanish with accent-insensitivity and stemming. While it lacks explicit 'when not to use' statements, the guidance is clear 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?

Beyond annotations (readOnly, idempotent, openWorld), the description reveals key behaviors: results sorted by primary metric, includes citation URIs, handles off-calendar fiscal years correctly, and replaces 8-15 lookups. No contradictions with annotations.

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

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

The description is a single dense paragraph. It is reasonably concise but could benefit from bullet points for clarity. It effectively front-loads purpose and usage.

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

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

For a tool with 2 parameters and no output schema, the description thoroughly explains inputs, behavior, and return characteristics (sorted data, citation URIs, handling of fiscal years). It covers all necessary context for an agent to use it correctly.

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

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

Schema covers type and values with enums and constraints. Description adds significant value by explaining what data is pulled for each type (company: SEC EDGAR/XBRL; drug: FAERS, etc.) and the meaning of 'values' (tickers/CIKs or drug names). However, schema already provides clear descriptions, so enhancement is moderate.

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 comparisons of 2-5 entities (companies or drugs) in one call, using trigger phrases like 'X vs Y' or 'rank these companies.' It distinguishes from siblings like entity_profile by emphasizing multi-entity comparison.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also details what data each type pulls (company: 10-K financials; drug: FAERS, FDA approvals, trials), helping the agent decide.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond them: parallel facet decomposition across 5,798 tools, the findings-packet shape (evidence + confidence + source + fetched_at + pipeworx:// citation), the honesty guarantee ('explicit gaps[]... never invented'), resolvable citation_uri semantics, contradictions[] behavior, semantic excerpting rather than head-truncation, and latency expectations. 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 long but every sentence carries a distinct, load-bearing fact — there is no fluff or repetition. It is front-loaded with the account requirement and the 'not open-web search' warning. It loses a point only because the organization is a dense stream with parenthetical asides interleaved (paid-plan note inside account sentence, depth behaviors split between the schema and two description locations), which could be sectioned more cleanly.

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

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

With no output schema, the description carries full responsibility for return-value semantics — and it delivers: the findings packet, gaps[], contradictions[], hop field, and citation_uri fetchability are all specified. It also covers auth/pricing, alternatives, data scope, and latency. Nothing an agent needs to invoke or interpret this tool 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 baseline is 3, but the description meaningfully enriches the depth parameter beyond the schema: it reveals that 'thorough' requires a paid plan, explains the hop behaviors (quick=single hop, standard=gap recovery + contradiction scan, thorough=iterative lead-chasing), and ties latency expectations to depth. The question parameter is also given context through the 'broad/multi-part' guidance.

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: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. It explicitly disambiguates itself from open-web search ('this is NOT open-web search') and from the closest sibling ask_pipeworx, so an agent can distinguish it without inspecting other definitions.

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

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

Provides explicit when-to-use guidance with examples ('Best for broad/multi-part questions over structured data') and names the alternative with the routing condition: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'. Both the selection condition and the exclusion are stated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds further behavioral details: returns top-N relevant tools with full schemas and examples, and notes that results are 'ready to call directly, no second schema lookup needed.' 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 (two sentences) and front-loaded with the purpose. It efficiently includes examples and return details, though the list of domains is somewhat lengthy.

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

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

For a discovery tool that returns tool metadata, the description explains what is returned (names, descriptions, schemas with examples, top-N) and sets expectations for immediate use. No output schema is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema for parameters—it only mentions that 'query' accepts aliases, which the schema already lists as separate properties.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, financials, etc.) and differentiates from sibling tools by emphasizing discovery over specific searches.

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 is given: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also describes when to use it for browsing or searching. No contradictions.

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 richly discloses behaviors beyond the readOnly/openWorld/idempotent annotations: it covers soft-fail behavior for the USPTO sunset, expected empty FDA sections, GDELT→GNews fallback, sources_used/sources_failed semantics, and the resolved:false path for private companies. This gives an agent accurate expectations about data presence and failure modes.

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

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

The description is long and dense, but almost every sentence carries useful behavioral or usage information. It is front-loaded with example queries and a strong preference directive. Minor redundancy exists, such as repeating the type/value interchangeability already present in the schema, but the overall structure serves a complex tool well.

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

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

With no output schema present, the description carries the full burden of explaining return values, and it does so thoroughly: CIK and company_name, resolved_from/resolved_to, recent_filings with URIs, fundamentals fields, each source section, and sources_used/sources_failed. It also covers edge cases and expected empty results, making the tool's behavior fully discoverable.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful semantic detail beyond the schema: names resolve via SEC EDGAR, private companies yield resolved:false with a notes line, and type accepts company/ticker interchangeably. This is genuinely helpful, though somewhat redundant with 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 identifies the tool as a full cross-source profile generator for US public companies, with concrete example queries like "Tell me about X" and "give me the rundown on NVDA." It distinguishes itself from chained single-source lookups and conveys that it is the preferred holistic-research 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 explicitly says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It also gives precise accepted input forms (ticker, CIK, company name) and explains the private-company fallback behavior, leaving little ambiguity about when and how to invoke it.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that deletion is based on a key and hints at privacy ('clear sensitive data'), but does not explain behavior if the key does not exist or confirm idempotent behavior. It adds some value beyond annotations but lacks full behavioral disclosure.

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 comprises only two sentences, each earning its place: the first states the core action and resource, the second provides usage guidance and sibling context. No unnecessary words or repetition.

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

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

For a simple tool with one parameter, no output schema, and annotations covering destructive and idempotent aspects, the description is largely complete. It explains purpose, usage, and relationship to siblings. It could mention success/failure or error handling for missing keys, but the current level is adequate given the tool's simplicity.

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

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

The schema has 100% coverage with a description for the 'key' parameter ('Memory key to delete'). The tool description does not add further meaning or constraints (e.g., format, length, case sensitivity) beyond that. Baseline 3 is appropriate since the schema already describes the parameter adequately.

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 ('Delete') and resource ('memory by key'), and explicitly distinguishes from siblings 'remember' and 'recall' by stating the complementary relationship. It also provides usage conditions, making the purpose unambiguous.

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

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

The description clearly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall'. However, it does not explicitly state when not to use it or list alternatives for similar tasks, though the positive guidance is strong.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it fetches the page and extracts title/description/key links, which is useful behavioral context. 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 two concise sentences plus a bulleted list of use cases. Every sentence adds value, and the most important information is front-loaded.

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

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

Given the rich annotations and complete schema, the description provides sufficient context for an agent to correctly select and invoke the tool. It explains the process, output format, and intended use cases.

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

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

Schema coverage is 100% with both parameters already described well. The description reiterates the URL and max_links usage but adds no new semantic detail beyond what the schema provides.

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

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

The tool name and description explicitly state it generates a production-ready llms.txt file for any URL by fetching the page and extracting key metadata. It clearly distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence, 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?

The description lists three concrete use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. It does not explicitly state when not to use or name alternative tools, but the provided scenarios are clear 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 readOnlyHint, idempotentHint, destructiveHint. The description adds value by specifying default active-only filtering and the exact fields returned, enhancing transparency.

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

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

Two efficient sentences front-load the action and result, with no unnecessary words.

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

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

The description fully covers the tool's purpose, usage, and output fields. Given the simple parameter and no output schema, it is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema's parameter description, but it implies the default behavior (active only).

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 lists the caller's active subscriptions and specifies the returned fields. It distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

The description advises using this tool to review existing subscriptions before adding more or to find an id for cancellation, providing clear usage context.

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

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

Beyond annotations (which are all false and thus uninformative), the description discloses key behaviors: filing returns a claim_token unless an account is used, rate-limited to 5 per identifier per day, free and doesn't count against quota, and the team reads digests daily. It also explains how to later check resolution via the token.

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

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

The description is long but every sentence adds distinct value, from usage cases to exclusions, token mechanics, rate limits, and cost. It's slightly verbose but not wasteful; the front-loaded purpose sentence immediately establishes what the tool does.

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 low complexity and full schema coverage, the description covers all essential aspects: who receives the feedback, what to include, how to follow up, rate limit, cost, and impact on roadmap. Even without an output schema, it explains the return token and its 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%, so baseline is 3, but the description adds extra meaning for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'. It also ties the message and context parameters to the guidance about describing issues in terms of Pipeworx tools/packs.

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

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

The description opens with a specific verb and object: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from siblings by scoping to tools served by this Pipeworx connection and explicitly warns against filing for other MCP servers.

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 gives explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides exclusions and alternatives: if the tool is from another server, file it there; names of Pipeworx tools are those listed by this connection.

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 convey safety (readOnly, idempotent). Description adds valuable details: self-aggregating signal, no PII, caching behavior (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?

Four sentences that front-load purpose, then use cases, then technical details. No fluff or repetition. 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?

Despite no output schema, the description fully explains the return types. For a simple read-only tool, this 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 fully covers the single parameter with enum and description. Description adds context about window semantics (short for hot, long for steady-state), enhancing the schema's meaning.

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 returns top tools, packs, and call volume over recent windows. It specifies a clear verb and resource ('returns trending data') and distinguishes itself from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Lists three specific use cases (discovering hot data, confirming canonical tool, seeing alignment) and explains window choices. Lacks explicit when-not or alternative tools, but context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: the internal mechanics (date-axis/threshold-axis ordering, partition_check), the semantic anchor (≥0.30 Jaccard similarity), the partition filter (placeholder slug removal), and the fill check behavior (theoretical vs realizable edge). It also explains when a signal should not be traded (realizable_edge_pp ≤ 0).

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

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

The description is front-loaded with the purpose and modes, and uses clear separation. However, it is quite long and contains dense technical details that could be streamlined. Every sentence earns its place given the complexity, but some redundancy exists (e.g., repeated mention of partition_check). Still highly effective.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities[], partition_check details, fill check). It covers edge cases (low similarity, placeholder filtering, fill check). It references sibling tools appropriately. The complexity is high, but the description leaves no significant gaps for an agent to understand invocation and interpretation.

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

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

Schema coverage is 100% with both parameters already described. The description adds significant meaning: event accepts full URLs, topic triggers cross-event scanning, and it explains how each parameter influences behavior (e.g., topic searches related events and unions markets). Examples and technical details (Jaccard threshold, placeholder filter) go well beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and provides specific examples. This differentiates it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scanning. It provides example inputs and explains the logic for choosing one over the other. It also mentions when to use a sibling tool (polymarket_fill_risk) for custom sizing.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: caching at 1h KV level, edge calculation net of slippage, 24h move warnings, and detailed model methodology. It fully discloses behavior beyond annotations without contradiction.

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

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

The description is verbose with multiple paragraphs and technical model details. While well-structured with labeled segments, it may overwhelm an AI agent. It could be trimmed to essential information without losing clarity.

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

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

Given 9 parameters, no output schema, and annotations, the description is highly complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), covers edge cases like Fed bets, and describes tradeable-edge knobs. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, with all 9 parameters described. The description adds significant value by providing rationale and usage examples for each parameter, such as min_kelly skipping small opportunities and min_partition_leg_kelly explaining why min_kelly doesn't filter partition arbs. While thorough, some explanations could be more concise.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from siblings by its focus on edge detection using multiple model families, but does not explicitly differentiate from related tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description implies usage for discovering betting opportunities without paging hundreds of markets, but it lacks explicit guidance on when not to use this tool or alternatives among siblings. Context is clear but no exclusions or condition-based switching.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: snapshot TTL of 60 days, data start constraints, computation from daily closes (not intraday), and detailed explanation of response fields (tracked, expired, snapshot_dates). 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 well-structured with clear purpose first, then parameter constraints, then response explanation. It is somewhat lengthy but every sentence adds unique value. Front-loading of the core question and contrasts makes it efficient.

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

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

Despite no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates arrays with detailed fields). It also covers constraints like TTL and data start date. Given the simple two-parameter input, this is comprehensive.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the 'window' parameter as a 'snapshot family' and clarifying defaults and limits (days default 14 max 30). This goes beyond the schema's literal 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 provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis and time-series behavior.

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

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

The description explains when to use (when needing historical edge persistence) and contrasts a fresh wide edge vs an old wide edge. It does not explicitly name alternatives, but the context implies polymarket_edges for current data, and sibling tools list provides differentiation.

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

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

Annotations already provide readOnlyHint=true and other safety hints. The description adds significant behavioral context: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains the risk of partial baskets converting arb into unhedged positions. 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 long but well-structured: starts with a concise main statement, then a REQUIRES clause, followed by clear sections for SINGLE-MARKET and BASKET modes, ending with usage advice. Every sentence adds value, though it could be slightly more compact while retaining 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?

Given the tool has 4 parameters, no output schema, and no nested objects, the description compensates fully. It explains all return fields in both modes, includes verdict categories (clean|degraded|cannot_fill), and details risks (thin_legs, max_clean_notional, forced_directional_risk). The context signals indicate high schema coverage, and the description fills remaining gaps.

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

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

Schema description coverage is 100%, but the description adds substantial meaning beyond the schema: explains default values, the interpretation of size_usd in basket mode as 'settlement notional — shares per leg, each paying $1 at resolution', the auto-detection of side in basket, and the distinction between single-market and basket parameters. This goes well beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly tells agents to use it before acting on signals from sibling tools like polymarket_arbitrage and polymarket_edges, providing differentiation.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why—'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'—providing clear context and exclusions.

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

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

Annotations already mark this read-only/idempotent, but the description goes far beyond that: it enumerates compatibility codes, explains null temporal_alignment semantics, states that unknown metric/match_subtype legs are never paired, and discloses that spreads are gross of Kalshi fees. This is exactly the behavioral context an agent needs.

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

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

The description is long but every block earns its place: purpose, modes, response shape, safety fields, skipped counters, fee caveat, and real-world calibration. It is front-loaded and structured so an agent can parse it progressively.

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

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

With no output schema, the description carries full responsibility for explaining return semantics—and it does: leg prices, top_spreads_pp, per-entry flags, temporal_alignment, skipped_unclassified, low_confidence_pairs, and fees_note are all defined. Nothing needed to call and interpret the tool 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 description adds real value on top: the full pre-mapped topic enum, examples for the ticker and slug, and the critical override relationship where explicit arguments replace the topic-mapped side. An agent can confidently choose the right parameter combination.

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 first sentence nails the exact deliverable: a cross-venue spread for the same resolving question between Kalshi and Polymarket. The two-mode explanation (topic shortcuts vs explicit pairings) and the warning that pre-mapped does not mean tradeable make the tool's role unambiguous and distinguishable from Polymarket-only 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 clear mode-selection guidance: use `topic` for pre-mapped shortcuts, or supply `kalshi_event_ticker` and `polymarket_event_slug` for custom pairings. It also warns that real cross-venue spreads are rarer than the shortcut list suggests, but it never names an alternative sibling tool to use instead.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds context on scoping (anonymous IP, BYO key hash, account ID) and pairing with siblings, enhancing transparency without contradiction.

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

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

Four sentences, each earning its place. Front-loaded with clear action and resource. 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 optional parameter, the description covers all necessary context: usage, scoping, pairing with siblings. No gaps given the low complexity and rich annotations.

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

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

Schema coverage is 100%, so the description adds minimal new meaning beyond the schema's parameter description. The description clarifies omitting key lists all keys, but that is already in the schema.

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

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

The description clearly states it retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools 'remember' and 'forget'.

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

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

Provides explicit examples of when to use (target ticker, address, research notes) and mentions scoping. However, lacks explicit 'when not to use' guidance.

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

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

The description says mark_read:true flags returned events as read, implying a state modification. However, annotations declare readOnlyHint=true, indicating no modifications. This is a clear contradiction. The description also adds context about polling and alternative endpoints, but the contradiction undermines transparency.

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

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

The description is concise (3-4 sentences), front-loads the main purpose, and every sentence adds useful information (purpose, fields, filtering, mark_read behavior, alternative access). No unnecessary words.

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

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

For a read-only tool with no output schema, the description adequately explains return fields and parameters. However, the contradiction between mark_read behavior and readOnlyHint annotation makes the description incomplete, as the agent may be misled about the tool's side effects.

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 parameter descriptions. The description adds value by providing an example for type ('sec_8k'), explaining the effect of mark_read, and clarifying that since expects an ISO timestamp. This goes beyond the schema definitions.

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

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

The description clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, payload), and mentions filtering. It is specific about the resource and verb. While it does not explicitly distinguish from sibling tools, 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?

The description provides guidance on filtering by type and since, using mark_read, and notes that polling works fine. It also mentions an alternative endpoint for scripts. However, it does not explicitly state when to avoid using this tool in favor of 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 already declare readOnly and idempotent, but the description adds extensive behavioral details: fans out to multiple sources, fallback mechanisms, soft-fails for USPTO, and return structure with grouped changes and citation URIs. 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?

Front-loaded with example queries and well-structured. Slightly verbose but every sentence adds value. Could be tightened slightly without losing clarity.

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

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

Despite lack of output schema, the description fully explains the return structure (changes grouped by source, total_changes count, citation URIs). Covers all essential aspects of this complex multi-source tool.

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

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

Schema covers all three parameters with descriptions (100% coverage). The description adds extra value by explaining since shorthand (e.g., '30d', '3m'), recommending '30d' or '1m', and clarifying value can be ticker or CIK.

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

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

The description uses specific verbs like 'change feed', lists example queries, and explicitly distinguishes from sibling 'entity_profile'.

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

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

Provides when-to-use with example queries, when-not-to-use (use entity_profile for static profile), and fallback logic for news sources and USPTO.

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 behavioral context beyond annotations: it explains scoping by identifier, persistence differences between authenticated users (persistent) and anonymous sessions (24 hours). Annotations already indicate idempotentHint=true and destructiveHint=false, and the description aligns without contradiction.

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

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

The description is a compact paragraph with front-loaded purpose. Every sentence adds value: purpose, usage examples, storage behavior, and pairing with other tools. 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 2 parameters and no output schema, the description covers all essential aspects: what it stores, how it's stored (key-value, scoped), retention policy, and integration with siblings. 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% (both parameters described), baseline 3. The description enriches parameter meaning by providing example keys ('subject_property', 'target_ticker') and clarifying that values can be any text. This adds practical context beyond the schema's generic descriptions.

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

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

The description uses specific verbs ('save data') and resources ('key-value pair'), clearly stating the tool's purpose: storing data for reuse across conversations or sessions. It distinguishes itself from sibling tools 'recall' and 'forget' by explicitly pairing with them.

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

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

Provides explicit guidance on when to use the tool ('when you discover something worth carrying forward') with concrete examples (ticker, address, preference). It also mentions complementary tools ('recall', 'forget'), setting clear context for alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds substantial context beyond these: it explains the cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, how ambiguous matches return figi_candidates, how unresolved identifiers are explicitly listed, and that non-equity instruments resolve. All of this is useful behavioral detail that complements the annotations without contradicting them.

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

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

The description is lengthy but well-structured: it opens with query examples, then covers supported types, behavior nuances, and input guidance. Information is front-loaded with the most critical examples at the start. While verbose, every sentence adds operational detail or usage nuance, and the structure aids readability. It is not overly terse, but the complexity justifies the length.

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

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

This is a complex tool with multiple entity types, multiple identifier sources, and edge cases. The description covers many outcomes: dual-type support, ambiguity handling via figi_candidates, graceful degradation, and explicit unresolved fields. However, because there is no output schema, it does not fully specify the response structure (e.g., exact JSON keys). It gives hints but not a complete contract. For an agent to use it correctly, the input guidance is thorough, but the output shape is only partially described.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value to the 'value' parameter by clarifying formatting (e.g., for bonds, pass the issuer exactly as printed), warning about trailing security-class words, and giving examples like 'ozempic' or 'metformin'. This goes beyond the schema's own description, which is generic. The 'type' parameter is fully covered by the enum, so no extra semantics are needed.

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 clear purpose: resolving user-spoken names to canonical identifiers, with concrete examples of queries like 'What's the ticker for...' and 'is X a subsidiary of Y'. It explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from siblings like entity_profile or compare_entities that operate on existing IDs. The supported types and behavior are detailed, making the resource and verb unambiguous.

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

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

Provides explicit guidance on when to use: 'Use FIRST whenever you have a name but need an ID.' It also explains input format nuances (e.g., pass only the entity name, not the full noun phrase). However, it does not name specific alternatives or state when NOT to use it (e.g., when you already have an ID). The clear when-to-use outweighs the lack of explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: calls ai_visibility_check internally, ranks, returns specific fields (score, confidence, signal density). Missing any caution about performance or costs of multiple probes.

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 core action, no redundant phrasing. 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?

For a tool with 4 params (all described in schema) and no output schema, the description appropriately explains return structure and purpose in a competitive audit context. Comprehensive for its 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%, so baseline is 3. Description adds slight value by explaining ordering of entities (first is subject) and role of context, but does not significantly enhance beyond schema descriptions.

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

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

Clearly states the verb (compare, probe, rank) and resource (AI visibility across entities). Distinguishes itself from sibling 'ai_visibility_check' by emphasizing multiple entities and competitive ranking.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and implies when to use. However, does not explicitly state when not to use or mention alternatives like 'ai_visibility_check' for single-entity checks.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds that bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timeouts. Adds context beyond annotations.

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

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

Description is moderately long but well-structured: front-loaded with purpose, then usage, then details. No fluff; 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?

Covers complexity of multiple data sources, return fields listed, edge cases like partial failures and timeouts addressed. No output schema but description lists return fields adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds that scoped packages are accepted and version defaults to latest, providing extra meaning beyond schema.

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

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

Description clearly states it is a composite check for adding an npm package, covering license, advisories, bundle size, etc. It distinguishes well from sibling tools by being specific to npm dependency scanning.

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

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

Explicitly says when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes NPM-only and alternative for other ecosystems.

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

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

Discloses algorithm details (BGE-base-en embeddings, cosine, 500-char windows), input cap (200K chars with truncation flag), and output features (character offsets, similarity scores). Annotations already indicate read-only and non-destructive, description adds substantive context.

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

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

Four sentences front-loaded with core purpose, no fluff, 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?

Covers input, output, limitations, algorithm, and tying to sibling tool. Despite no output schema, description sufficiently explains return values.

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

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

Schema has 100% coverage with descriptions. Description adds examples for query (e.g., 'supply-chain risk'), clarifies text is the already-fetched record, and explains the output structure beyond schema.

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

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

The description clearly states the tool does semantic search inside a fetched record, using verbs like 'search' and 'returns', and distinguishes it 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 when to use: when the record is too big for the prompt, and mentions alternative: ground over relevant passages instead of whole document with ask_pipeworx_grounded.

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 basic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds significant behavioral context: returns new subscription id, requires OAuth, delivery constraints (10 SMS/day, webhook auto-disable, signing secret one-time return), and type-specific examples. 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 fairly long but well-structured with clear sections (requirements, supported types, delivery channels). It front-loads the core purpose and uses bullet-like formatting. While slightly verbose, every sentence adds necessary detail given the tool's complexity.

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

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

For a tool with 3 parameters (type, params, delivery), nested objects, no output schema, and complex conditional logic, the description covers all essential aspects: requirements, type-specific param structures, delivery options with constraints, and behavior. It is fully self-contained.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains each type-specific params with real-world examples (e.g., sec_8k with items codes, polymarket_edge with topics), delivery channel constraints and verification requirements. This goes well 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 explicitly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb ('Create') and resource ('subscription'). It distinguishes from siblings like list_subscriptions, unsubscribe, recent_alerts by focusing on creation.

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 clarifies when to use by detailing supported subscription types and delivery channels, and mentions prerequisites (Pipeworx OAuth account). It does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns example questions with exact tool+argument shapes drawn from the live catalog. No contradictions.

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

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

The description is comprehensive but a bit long. It front-loads key phrases and uses structured lists. Every sentence adds value, though some redundancy exists ('what can I ask'). Still, it is well-organized.

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

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

Given the simple resource (one optional parameter), rich annotations, and no output schema, the description fully covers what the tool does, when to use it, and what it returns. No gaps.

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

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

Schema coverage is 100% for the single parameter. The description adds examples of topic values and explains that omitting it gives a full spread, providing more context than the schema alone.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and 'Call', and the purpose is distinct from siblings such as discover_tools or ask_pipeworx.

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

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

Explicitly states to use this 'FIRST when you do not yet know what Pipeworx can do' and gives guidance on using the topic parameter to focus. It does not explicitly say when not to use it, but the context is clear enough for an agent.

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

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

Description adds important context beyond annotations: that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Annotations already indicate non-destructive (destructiveHint=false) behavior, but description enriches understanding. No contradiction.

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

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

Two concise sentences, purpose front-loaded. 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?

For a simple tool with one parameter and no output schema, the description covers behavioral aspects (ownership, deactivation) and usage context. Slightly more completeness could be achieved but is adequate.

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

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

Schema coverage is 100% with a clear description for the single parameter 'id'. Description mentions 'by id' but does not add significant new information beyond the schema. Acceptable given high schema coverage.

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

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

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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 ownership enforcement ('you can only cancel your own subscriptions') and describes the deactivation behavior. While no explicit alternative is given, the context is clear.

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

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

Even though annotations already declare the tool read-only, idempotent, and non-destructive, the description adds critical behavioral context: it reveals two distinct processing paths (SEC EDGAR for financials vs grounded pipeline for everything else), defines the full verdict taxonomy, and warns that 'could_not_verify' means the check did not happen and must not be treated as evidence. This goes well beyond what annotations provide.

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

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

The description is structured with trigger phrases first, then usage guidance, pipeline routing, return values, and error semantics. Every sentence serves a purpose, no fluff. While it is long, the length is justified by the tool's complexity and the need to convey error-handling nuances. Front-loaded with the most important info.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description is complete. It explains the return verdicts, the actual value with citation, reasoning, and the distinct meaning of 'could_not_verify' vs 'unsupported'. It also clarifies the input claim and tolerance_pct semantics. The description leaves no significant gaps for an agent to misuse the tool.

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

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

The schema already covers both parameters with descriptions (100% coverage). The description adds extra value by explaining that tolerance_pct overrides claim wording defaults, suggesting 1–2 for hallucination detection, and noting the default is capped at 5. Examples for the claim parameter also clarify expected natural-language format. This exceeds the baseline 3 but is not a full 5 since the schema already does the heavy lifting.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources. It includes trigger phrases ('fact check', 'verify the claim that...') and explicitly distinguishes this from general Q&A tools by returning a verdict. The description also clarifies it replaces 4–6 sequential calls, making its purpose distinct from siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples. It also explains that company-financial claims go through one path and other claims through a grounded pipeline, which helps callers understand the internal routing. However, it does not explicitly list when NOT to use the tool or name alternative sibling tools, so it stops short of a 5.

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