Banxico

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

Annotations already declare readOnly=True, idempotent=True. Description adds that default model is free Workers AI, while Anthropic requires BYO key with direct payment, and returns per-model scores and combined view. No contradiction.

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

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

Two sentences, front-loaded with main action, each sentence adds meaningful detail without redundancy. Efficient text.

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

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

Covers purpose, parameters, return structure, and usage scenarios. Lacks mention of error handling or timeout behavior, but is sufficient for a non-mutation tool with good annotations.

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

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

Schema coverage is 100% with descriptions. Description adds value by explaining default model and the _apiKey requirement for Anthropic, and purpose of context parameter for disambiguation.

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 probes LLMs for visibility scoring on a business/brand/product/topic, with specific verb 'probe...score'. It distinguishes from sibling tools like ask_pipeworx (Q&A) or deep_research (general research) by focusing on AI visibility audits.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Does not mention when NOT to use or alternative siblings, but context makes intended usage clear.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive behavior. The description adds valuable context by explaining that the tool acts as a router, auto-fills arguments, dispatches across many source tools, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations exists.

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

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

The description front-loads the most important directive ('PREFER OVER WEB SEARCH') and then flows through behavior, trigger phrases, example queries, and exclusions. Despite its length, every sentence carries actionable information; there is no filler or redundant phrasing.

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

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

For a complex routing tool, the description covers purpose, usage boundaries, alternatives, and return format (structured answer with citations). With 100% schema coverage and strong annotations, the agent has everything needed to decide when and how to invoke the tool. The absence of an output schema is compensated by the prose description of the expected response.

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 defines a single required 'question' parameter with aliases. The description adds understanding beyond the schema by illustrating the intended semantic scope through domain examples (SEC, FDA, FRED, weather, patents) and natural-language trigger phrases, clarifying what kind of input the parameter should carry.

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 function: routing factual questions to one of 5,908 tools across 1,540 verified sources, filling arguments, and returning answers with stable pipeworx:// citation URIs. It clearly differentiates from siblings by explicitly naming compare_entities and ai_visibility_check for other query types, and it positions itself as the default 'START HERE' tool for factual questions.

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 triggers like 'what is', 'look up', 'find', 'get the latest', and says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also provides when-not-to-use guidance: hypothetical/opinion questions should go to web search, comparisons to compare_entities, and AI-agent questions to ai_visibility_check. This is comprehensive routing guidance with no dependency on inference.

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

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

Annotations already carry the safety profile (readOnly, openWorld, idempotent, non-destructive), and the description still adds real behavioral value: behavior is time-varying ('candidate routing improvements enabled live whenever one is under test'), the current inactive-candidate state (last retired 2026-07-26), and the key negative clarification 'Falls back to nothing — this IS a full working router'. This prevents the agent from assuming the beta is a stub or degraded endpoint.

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 (~90 words), each carrying distinct information: identity, current state, usage directive, and negative clarification. Front-loaded with the identity statement and free of filler, though slightly dense for a quick read.

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

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

For a tool with one effective parameter, 100% schema coverage, a rich annotation set, and no output schema, the description covers identity, temporal state, usage, and outcome tracking. The 'same response shape' phrase adequately handles return-value expectations by pointing to the known stable sibling.

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% — all six parameters (question plus five aliases) are documented in the schema itself, so the baseline of 3 applies. The description only confirms 'same arguments' as ask_pipeworx without adding new parameter-level semantic detail.

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?

Identifies the tool as the beta edge of ask_pipeworx — a universal router that routes a question across the same 5,908 tools with the same arguments and response shape. By explicitly naming the stable sibling and contrasting the beta variant against it, the description makes the tool's scope and identity 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?

Gives an explicit directive: 'Use it exactly like ask_pipeworx when you want the newest routing', and explains the results are compared against the stable router to decide merges. It names the primary alternative and the decision context, but stops short of explicit when-not-to-use guidance or mention of other routing siblings like 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?

The description goes far beyond the annotations by disclosing the exact success return shape, the refusal reason enum, and the guarantee that answers are extracted only from tool results. It also reveals the cost tradeoff of one extra LLM call. This is valuable behavioral context that annotations alone would not 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 dense but every sentence earns its place: purpose, routing behavior, return contract, refusal contract, usage guidance, and cost comparison. The most important purpose and tradeoff are front-loaded, with lower-level refusal details following naturally.

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

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

Despite having no output schema, the description fully compensates by specifying both success and refusal response structures. It covers when to use, why it is grounded, the key tradeoff versus ask_pipeworx, and failure modes, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already documents the question parameter and its aliases. The description adds meaning by explaining that the input drives routing across thousands of sources and automatic argument filling, which helps the agent understand how the question is used.

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

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

The description states a specific verb and resource: ask Pipeworx in a grounded, hallucination-resistant mode. It explicitly differentiates itself from the sibling ask_pipeworx by describing the extra LLM call and the grounded extraction behavior, so an agent can distinguish it without opening the schema.

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

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

The description tells the agent when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative, ask_pipeworx, and explicitly says to prefer it for casual lookups, making both selection and exclusion clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context by indicating it returns the latest published rate plus recent history, enhancing the agent's understanding of the output.

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, consisting of two sentences with no extraneous information. It front-loads the main purpose and includes usage guidance and source authority in an efficient manner.

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 simplicity of the tool (2 optional parameters, no output schema), the description adequately covers the main aspects: what it returns, source authority, and usage guidance. It could be more complete by describing the output format, but given no output schema, it is sufficient.

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

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

Schema coverage is 100%, so the parameters are fully described in the schema. The description does not add extra meaning beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description clearly states the tool returns the official USD/MXN exchange rate with specific verb 'returns' and resource 'exchange rate', and distinguishes from sibling tools like banxico_policy_rate by being explicit about the currency pair.

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

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

The description provides explicit guidance ('PREFER OVER WEB SEARCH') for when to use this tool, but does not explicitly mention when not to use it or compare with sibling tools like banxico_policy_rate or banxico_series.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. Description adds minor behavioral context ('returns the current rate plus recent history') but adds no further safety or side-effect details beyond annotations.

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

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

Three sentences: definition, usage guidance, output description. No redundancy, front-loaded with key information. 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 simple read-only tool with 2 optional parameters and no output schema, the description adequately explains what it returns. Sibling context (banxico_exchange_rate, banxico_series) is differentiated by 'policy rate'. Minor gap: no mention of output format or precision.

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?

Input schema covers both parameters with descriptions, achieving 100% coverage. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns 'Banco de México's overnight interbank TARGET RATE' and distinguishes it from web search for queries like 'Banxico interest rate'. It also contrasts with sibling banxico_exchange_rate implicitly by specifying 'policy rate'.

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 'PREFER OVER WEB SEARCH' for specific queries, providing clear when-to-use guidance. However, it does not mention when not to use or alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds that it returns recent observations plus title/units, and its 'escape hatch' nature, providing useful behavioral context beyond annotations.

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

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

Two highly informative sentences with no wasted words. Purpose is front-loaded, followed by helpful examples and guidance.

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 sibling tool context, the description fully explains what the tool does, what it returns, and when to use it, making it complete for an agent.

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

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

Schema already covers all parameters (100% coverage). Description adds value by listing common series IDs with their meanings, enhancing understanding beyond the schema descriptions.

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

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

Clearly states it fetches any Banco de México SIE series by ID, listing specific categories (inflation, interest rates, etc.) and distinguishing it from sibling tools for specific series.

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

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

Explicitly advises using banxico_exchange_rate or banxico_policy_rate for common headline series, and provides common IDs, guiding when to use this general tool.

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

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

The description extensively discloses behaviors beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details fan-out logic, response shapes (result.market, result.analysis, result.evidence), resolver contract (confidence levels, alternatives), parent event extractor, news fallbacks, safety short-circuits (low-confidence, closed markets), liquidity notes, and resolution-rule risk. This is far more than required for a read-only tool, providing deep behavioral 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 quite long (multiple paragraphs), covering numerous details. The first sentence is front-loaded with the core purpose, and the structure follows logically (classifiers, fan-out, response shapes, resolver contract, etc.). However, some detail could be condensed (e.g., the long list of classifiers, extensive response field explanations). The length is partly justified by the tool's complexity, but it sacrifices conciseness.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is exceptionally complete. It covers all input types, behaviors, output shapes (market, analysis, evidence), edge cases (low-confidence matches, closed markets, wide spreads, cancellation rules), and safety mechanisms. Every foreseeable agent need—when to inspect match confidence, how to interpret parent events, what news fallbacks indicate—is addressed.

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 covers all three parameters (market, depth, include_raw) with descriptions. The description adds context: it clarifies the market parameter accepts slugs, URLs, or question text; it explains `depth` defaults to 'thorough' and `include_raw` defaults to false with rationale ('keeps responses under ~20KB'). While the schema provides the basics, the description fills in defaults and intentions, justifying a score above the 3 baseline.

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

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

The first sentence clearly states the tool's core purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet via Pipeworx data), and scope (one call). The description further distinguishes use cases ('should I bet on X', etc.), and the sibling list includes alternative bet-related tools like polymarket_edges and polymarket_arbitrage, making the unique value proposition clear.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifiers and fan-out examples to illustrate appropriate scenarios. However, it does not explicitly state when NOT to use this tool or directly contrast with alternatives like polymarket_edges. The guidance is strong but lacks explicit exclusion criteria.

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 and idempotentHint, and the description adds substantial behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with practical query examples, minimizes fluff, and every sentence conveys essential information. It efficiently packs purpose, usage, data sources, and behavioral notes without redundancy.

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

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

Given no output schema, the description explains return format ('paired data + citation URIs') and sorting. It could be more explicit about the exact fields or structure of paired data, but it covers critical aspects 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%, but the description adds meaning beyond parameter descriptions by specifying what each type pulls (company: revenue, net income, etc.; drug: adverse events, approvals, trials), providing examples of valid values (tickers, drug names), and noting constraints like max 5 items. This adds significant value.

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 companies or drugs, with explicit verb-resource mapping and coverage of specific data points. It distinguishes from sequential lookups and implicitly from sibling tools 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?

The description gives explicit when-to-use guidance with example phrases ('X vs Y', 'rank these companies') and instructs to prefer over sequential lookups. However, it does not explicitly state when not to use (e.g., for single entity queries) or mention specific sibling tool 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?

Beyond the annotations, the description discloses parallel decomposition, routing to thousands of tools, the findings packet structure, gaps[] for unanswered facets, no invention of data, stable citations, semantic excerpting, contradictions[] behavior, and latency expectations. It adds rich behavioral context and does not contradict the readOnly/openWorld/idempotent hints.

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

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

The description is long but front-loaded and dense: it leads with account requirements and the fallback tool, then core behavior, use cases, output details, and timing. Every sentence carries distinct information needed for correct invocation and sibling selection.

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 compensates by explaining the findings packet contents, gaps[], contradictions[], citation format, excerpting behavior, latency, and authentication constraints. An agent has sufficient context to invoke the tool and interpret its results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with the paid-plan requirement for thorough, expected latency ranges, and clarifying that broad/multi-part questions are appropriate, though much of the depth parameter's semantics already appear 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 precisely identifies the tool as grounded multi-source research over Pipeworx's structured data sources in one call, and explicitly contrasts it with open-web search. It also distinguishes itself from ask_pipeworx for single lookups, making the scope and resource crystal 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?

It gives explicit routing instructions: use ask_pipeworx when not signed in or for a single lookup, and states that the thorough depth requires a paid plan. It also provides concrete best-fit scenarios with examples, so an agent knows exactly when to select this tool over 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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed' — valuable behavioral context beyond annotations.

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

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

The description is front-loaded with the core purpose and domain list. While slightly lengthy, every sentence adds value: purpose, domains, return details, usage guidance. It could be more concise but remains 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?

No output schema exists, so the description adequately covers return content (names, descriptions, schemas). It also covers usage context ('Call this FIRST'), parameter meaning, and examples. For a discovery tool, this 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% with detailed descriptions for each parameter (including aliases). The description reinforces usage by providing example queries and explaining the query parameter's role as 'Natural language description', 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 explicitly states the tool finds tools by describing data or task, and lists many specific domains (SEC filings, financials, etc.). It clearly distinguishes from sibling tools which are specific-purpose tools, while discover_tools is for browsing/selection.

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 instruction 'Call this FIRST when you have many tools available and want to see the option set' provides clear guidance on when to use. It implies alternatives by stating 'not just one answer', but doesn't explicitly list when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond that: it fans out to multiple sources, reports sources_used/sources_failed, and explains that empty sections are real 'no data' states, not bugs. It also discloses that a private company returns resolved:false with a notes line rather than a failure. The only minor gap is not describing latency or rate-limit behavior, but the parallel fan-out nature is clear.

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

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

The description is dense but front-loaded with example queries and the 'ALWAYS PREFER' directive, which is the most important usage guidance. While it is long, every sentence carries operational information: sources, return fields, input normalization, and failure semantics. It would benefit from a little structural trimming, but it earns its length given the tool's complexity.

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

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

Given no output schema, the description compensates well by listing return components (cik, company_name, recent_filings with URIs, fundamentals, etc.) and explaining failure semantics. It also covers the input space thoroughly. The only missing piece is a brief note about typical response size or latency, which would help agents set expectations, but the tool is complex and this is a minor gap.

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

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

Schema coverage is 100%, so the schema documents both parameters fully. The description reinforces the semantics by enumerating accepted input shapes and noting that type accepts 'company' or 'ticker' interchangeably — a nuance explicitly stated in the schema enum description but usefully echoed. It adds the resolution behavior (resolved_from/resolved_to) that isn't in the schema, which helps the agent understand what to expect.

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 verb-resource relationship: it produces a full cross-source profile of a US public company in a single parallel call. It enumerates the sources (SEC, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, GLEIF) and return components, distinguishing it from narrow single-source lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies accepted input forms (ticker, CIK, company name) and what happens for private companies (resolved:false with a notes line). This gives the agent clear decision rules for when to use this tool versus alternatives.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context about use cases but doesn't detail behavior on missing keys, which is acceptable given low complexity.

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

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

Two sentences, no wasted words. Purpose, usage, and context are front-loaded and clear.

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 deletion tool with one parameter and no output schema, the description covers purpose, usage, and sibling context completely.

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

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

Schema coverage is 100% with a single key parameter. Description adds no additional meaning beyond 'by key', so no extra value.

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

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

Clearly states it deletes a memory by key, distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly says when to use: stale context, task completion, or clearing sensitive data. Also mentions pairing with remember and recall.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about the output format (standard markdown, ready to drop at site-root) and the extraction process (title/description/key links), which goes beyond 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 two sentences long, front-loaded with purpose, and every sentence adds value. No redundant or irrelevant information.

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

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

Given the tool's simplicity (2 params, no output schema, annotations cover safety), the description fully explains what the tool does, what output it produces, and common use cases. It is complete and requires no 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 the baseline is 3. The description does not add significant new meaning beyond what the schema provides for the two parameters. It mentions the default value for max_links (25) implicitly but not explicitly.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific actions (fetch, extract, emit) and format (standard markdown). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on generation rather than 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?

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor views. It does not provide exclusion criteria or direct alternatives, but the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds context about return fields and scope (the caller's own subscriptions), which is helpful but not critical beyond annotations.

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

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

The description is two sentences, starting with the core purpose, then listing return fields, and ending with usage guidance. 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 list tool with one optional boolean and rich annotations, the description provides all necessary information: what it returns, when to use it, and its safety profile (via annotations). 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?

The input schema has 100% coverage for the single optional parameter 'include_inactive', so the description doesn't need to add more. It is adequate but doesn't enhance understanding of the parameter beyond the schema.

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

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

The description clearly states it lists 'the caller's active subscriptions' and specifies the return fields (id, type, params, etc.). It distinguishes from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description explicitly advises using it to 'review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use this tool versus alternatives.

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

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

Beyond the sparse annotations, the description richly discloses behavioral traits: rate limiting (5 per identifier per day), free usage not counting against quota, daily human review, and the token-based follow-up mechanism for anonymous filings. This gives the agent full visibility into side effects and limitations.

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 contributes critical usage and behavioral guidance. It is front-loaded with the purpose, then flows through when-to-use, scope exclusions, token mechanics, and limitations 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?

With no output schema and minimal annotations, the description fully compensates by explaining the output behavior (claim_token), the follow-up flow, rate limits, and scope boundaries. This is a self-contained, high-quality description for a complex feedback tool.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful extra semantics by explaining how claim_token works, what context should reference, and how to frame the message in terms of Pipeworx tools/packs rather than pasting end-user prompts.

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 resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by focusing on feedback about Pipeworx tools themselves, rather than data retrieval or research operations.

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

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

The description provides explicit when-to-use guidance including bug, feature/data_gap, and praise scenarios. It also gives a clear exclusion: reporting issues for non-Pipeworx MCP servers should be filed elsewhere, and it explains the claim_token flow for follow-up.

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 it as read-only, idempotent, non-destructive. The description adds source (CF analytics-engine), no PII, and caching details (5min-1h). 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?

Every sentence serves a purpose: what it returns, three use cases, technical source/caching. No wasted words. Front-loaded with core function.

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

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

Without an output schema, the description adequately describes return values (top tools, packs, volume). Caching and privacy are covered. No gaps for a simple read-only tool.

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

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

Schema coverage is 100% for the only parameter 'window'. The description adds semantic guidance on how window choice affects results (hot vs steady-state), which adds real value beyond the enum list.

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

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

The description clearly states it returns trending tools, packs, and call volume over a window. The verb 'returns' and resource 'trending data' are explicit. It distinguishes from siblings by focusing on aggregated popularity metrics.

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

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

Three concrete use cases are listed, and guidance on window choice (shorter for hot topics, longer for steady-state) is provided. Could explicitly mention when not to use, but the 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the internal algorithm (monotonicity checks, partition_sum, semantic anchor, fill_check), what each mode returns, and how signals are generated. There is no contradiction with annotations, and the behavioral traits are fully disclosed.

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 quite verbose but well-structured with clear sections for each mode and additional details (semantic anchor, partition filter, fill check). It front-loads the core purpose. While it could be slightly more concise, the structure aids readability and the detail is justified 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?

Given no output schema, the description fully explains the return format (opportunities[] with fields) and includes important context like the fill check process and a reference to a related tool for deeper analysis. It covers all necessary aspects for an agent to use the tool effectively.

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

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

With 100% schema coverage, the description adds substantial value by explaining the purpose of each parameter with examples and context. It clarifies that 'event' is for single-event mode with slug/URL, and 'topic' is for cross-event scanning with seed questions, including how the tool searches and filters.

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 on Polymarket. It specifies three distinct modes (no args, event, topic) and describes each, making the purpose very clear and distinguishing it from sibling tools like polymarket_edges or 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 provides explicit guidance on when to use each mode: no args for general scan, event for specific market, topic for cross-event scanning. It also mentions an alternative tool (polymarket_fill_risk) for custom sizing. However, it doesn't explicitly state when not to use the tool or list exclusion criteria beyond the mode descriptions.

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

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

The description adds significant behavioral context beyond annotations, including caching (1h at KV level), response structure with diagnostics, and model assumptions. It does not contradict the readOnly/ idempotent hints and provides transparency about model limitations and edge cases.

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

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

The description is very long and packed with detailed algorithmic explanations, which may overwhelm concise use. While well-structured, it could be trimmed to essential guidance for an AI agent without sacrificing 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's complexity (9 parameters, no output schema), the description thoroughly explains every aspect: output segments, diagnostics, tradeable-edge knobs, model details, and even why certain opportunities are excluded. It leaves no significant gaps for an AI agent to understand 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?

Although schema description coverage is 100%, the description adds substantial value by explaining the rationale behind each parameter (e.g., slippage_pp's default, min_partition_leg_kelly's purpose) and providing usage context like default values and edge cases.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and it distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement.

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 targets the 'what should I bet on today' use case and explains when to use the tool. However, it does not explicitly mention when not to use it or directly compare with alternatives, although the detail on segments and knobs provides implicit 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?

Adds substantial behavioral detail beyond annotations: returns time-series, trend, decay, expired opportunities with lifespan, snapshot dates, and notes on data gaps and decay computation. Annotations already indicate readOnly, openWorld, idempotent, non-destructive.

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 purpose, then details. Dense but every sentence provides value. Slightly verbose but appropriate given the 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?

Tool has simple parameters, no output schema, but description fully explains response structure (tracked[], expired[], snapshot_dates[]) and covers behavior, limitations, and edge cases comprehensively.

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

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

Schema coverage is 100% with clear descriptions. Description adds context: 'snapshot family' for window and 'lookback' nuance for days. Adds value beyond schema without redundancy.

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 tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. Distinct from siblings like polymarket_edges which likely provide current edges.

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

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

Explains when to use (to differentiate fresh vs old wide edges) and provides limitations (60-day TTL, snapshot gaps). Doesn't explicitly state when not to use, but context implies alternatives like polymarket_edges for current edges.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: walks order book ladder, returns detailed fill info, verdict, and forces directional risk for basket mode. Discloses risk of unhedged directional positions from partial fills. No contradiction with annotations.

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

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

Description is comprehensive but somewhat lengthy. Front-loaded with purpose and requirements, then details per mode. Every sentence adds value, but could be slightly more concise while retaining information.

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

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

Despite no output schema, the description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, forced_directional_risk). Covers edge cases (thin books, partial fills) and usage context. Highly complete for a complex tool.

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

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

Schema descriptions cover all 4 parameters (100% coverage). The description adds nuance: mutual exclusivity of market/event, side default differences per mode, and size_usd interpretation as max spend, target proceeds, or settlement notional. Provides clarity beyond schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific outputs. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by indicating when to use it.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial basket fills cause unhedged positions). Also states requirement of one of `market` or `event`.

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 as read-only and idempotent, and the description adds substantial behavioral context: spreads are gross rather than net, Kalshi fees are not modeled, legs with 'unknown' metric_type/match_subtype are never paired, and compatibility warnings can appear even on returned pairs. There is no contradiction with the annotations.

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

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

The description is long, but it is organized with labeled sections such as 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS', and the core purpose is front-loaded in the first sentence. Some repetition exists, such as noting 'BOTH modes' twice, but the density is justified by 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?

With no output schema present, the description carries the full burden of explaining return values, and it succeeds: it details leg-by-leg prices, top_spreads_pp, compatibility codes, alignment semantics, skipped-leg counters, and the fees note. An agent has enough context to invoke the tool and interpret its results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that explicit parameters override the topic-mapped side, that both modes run the identical token-overlap matcher, and by providing concrete examples of valid values. This added layer of semantics justifies a 4.

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

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

The description opens with a specific action and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes beyond a vague label by detailing two modes, the response structure, and the matching mechanics, making it clearly distinct from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly explains when to use the `topic` shortcut mode versus explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings, and warns that most pre-mapped topics currently return compatibility warnings. It does not explicitly contrast this tool with sibling alternatives such as polymarket_arbitrage, so it stops just short of full 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 complements annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing scoping (anonymous IP, BYO key hash, account ID) and the pairing behavior. No contradictions; it adds meaningful 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?

Four concise sentences, each serving a purpose: core function, usage context, scoping, and sibling pairing. No unnecessary words, and the structure is logical and easy to parse.

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

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

For a single-parameter tool with full annotations, the description covers purpose, usage, scoping, and sibling relationships. It does not specify the return format (e.g., what a retrieved value looks like), but given the simplicity and lack of output schema, this is a minor gap.

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

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

The schema provides 100% coverage with a 'key' parameter description. The description restates that omitting key lists all keys, which matches the schema. It adds no new semantic meaning beyond what the schema already conveys.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted. It explicitly names the companion tools (remember, forget) for differentiation, leaving no ambiguity about what it does.

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

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

The description explains when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairs with remember/forget, effectively guiding use versus alternatives.

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

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

Description claims mark_read:true causes side effects (flagging events read), but annotations declare readOnlyHint=true, indicating no writes. This is a clear 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?

Five sentences, front-loaded with purpose, 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?

Covers filtering, mark_read, and alternative access. Minor gaps: no explicit mention of default ordering or unread_only behavior beyond schema.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for type, explains mark_read and since, though unread_only and limit are less elaborated.

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 verb 'pull' and resource 'fired events from your subscription feed', distinguishing it from sibling tools like list_subscriptions.

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

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

Explains filtering and polling, and mentions an alternative API endpoint. Lacks explicit comparison to sibling tools but context is clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details multi-source fan-out, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure with citation URIs. It fully discloses how the tool behaves.

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 example queries and is information-dense. While it is lengthy, every sentence adds value. Slightly more structural formatting (e.g., bullet points) could improve, but it remains concise relative to the 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?

Given the absence of an output schema, the description explains the return structure (grouped changes, total count, citation URIs). It also covers parameter formats, fallback behavior, and sibling differentiation, leaving no apparent gaps.

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

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

The input schema already provides detailed descriptions for all three parameters (100% coverage). The tool description adds context on how 'since' affects the feed and offers default suggestions, but the schema already handles most parameter 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?

The description clearly states it returns a 'change feed for a company' within a time window, listing data sources and explicitly distinguishing from the sibling tool 'entity_profile' which provides static profiles. The purpose is specific and 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 example queries, specifies the time window context, and directly advises when to use 'entity_profile' instead. This gives clear guidance on appropriate usage versus alternatives.

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

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

Annotations already indicate idempotentHint=true, destructiveHint=false. Description adds context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Two sentences, front-loaded with purpose, then usage, then behavioral details. 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 2-parameter tool with no output schema, the description fully covers purpose, usage, behavior, and relationships with siblings. No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. Description adds value by providing example keys (subject_property, target_ticker, user_preference) and clarifies value can be any text. Enhances understanding 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 saves data for reuse across conversations/sessions. It specifies key-value storage scoped by identifier and provides examples of what to store (resolved ticker, target address, etc.). Distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides concrete examples. Mentions pairing with recall (to retrieve) and forget (to delete), implying when not to use this tool.

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

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

Annotations already signal read-only/idempotent behavior, and the description adds substantial beyond that: cascade through multiple endpoints, graceful degradation when LEI/FIGI sources fail, ambiguity handling via `figi_candidates`, explicit `unresolved` reporting, and source-labelled identifiers. 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?

Long, but nearly every sentence carries operational value—examples, supported types, input caveats, fallback behavior, and ambiguity rules. It is somewhat dense and could be structured into cleaner sections, but it avoids fluff.

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

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

For a complex multi-endpoint resolver with no output schema, the description covers the essential context: input variants, entity-specific behavior, ambiguity/output hints, unresolved identifiers, and failure degradation. An agent has enough to decide when to call it and what to expect back.

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 significantly extends parameter meaning: it gives input formats (ticker, CIK, ISIN, brand/generic drug names), explains how ISIN maps to legal entities, and warns to pass only the issuer entity name for bonds. This goes well beyond the schema's field 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 states a precise verb+resource: resolving user-spoken names to canonical/official identifiers. It distinguishes the tool from siblings by listing concrete natural-language triggers and naming supported types, so an agent can tell it apart from entity_profile or compare_entities immediately.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not explicitly name sibling alternatives or state when NOT to use it, but the positive context is strong enough to route correctly.

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 and idempotentHint, indicating safety. The description adds detailed behavioral context: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. 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 four sentences long, each serving a purpose: stating purpose, describing action, providing use case, and listing output. No unnecessary words. Front-loaded with the core action.

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

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

Given the tool's complexity (4 parameters, no output schema, rich annotations), the description fully explains the process, output format, and use case. It provides enough context for an agent to select and invoke correctly without ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject' for narrative, and clarifies that 'context' disambiguates common names. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probes each entity with ai_visibility_check, ranks by score) and distinguishes from sibling ai_visibility_check which handles single entities.

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 usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies use when comparing multiple entities versus single, but does not explicitly state when not to use or list alternatives beyond the sibling context.

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

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

Adds important behavioral context beyond annotations: mentions composite nature, partial failures with graceful degradation, specific latency for bundlephobia's first measurement (5-30s), and that sources_failed will list timeouts. No contradiction with annotations.

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

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

Description is efficiently front-loaded with purpose, then usage, then behavior, and limitations. Every sentence adds value, though slightly verbose with some technical details.

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

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

Given the tool's complexity (composite, external API calls, partial failures), the description covers all essential aspects: what it does, what it returns, supported ecosystem, behavioral quirks, and error handling. No output schema exists, so description compensates fully.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully. The description adds no new parametric meaning beyond what is in the schema, confirming defaults and scoped package acceptance which are already present in schema descriptions.

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

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

The description uses specific verbs (scan, check, fans out across) and clearly identifies the resource (npm packages). It distinguishes itself from siblings by explicitly stating it's a composite check for npm packages, which is unique among the listed tools.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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 are readOnly, idempotent, non-destructive. Description adds details: truncation at 200K chars with flag, BGE-base-en embeddings + cosine over 500-char windows, offset and similarity scores in results.

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

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

Three well-structured sentences with key information front-loaded (purpose, use case, return format). No wasted words.

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

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

No output schema, but description explains return format (passages with offsets and scores), algorithm, and limitations (cap, truncation). Sufficient for an AI agent to invoke correctly.

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

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

Schema has 100% coverage with descriptions. Description adds value by explaining max chars, default limit, query examples, and underlying algorithm 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 'Semantic search INSIDE a fetched record' with specific verb+resource. Differentiates from siblings like ask_pipeworx_grounded by explaining pairing.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Mentions alternative tool and provides context for saving context with passage offsets.

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, such as requiring OAuth and delivery channel constraints. However, there is a contradiction with the idempotentHint annotation: description says returns 'new subscription id' implying non-idempotent, while annotation says idempotentHint=true. This reduces 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 a single dense paragraph that packs substantial information. While concise relative to content, it could be better organized (e.g., bullet points for types and channels) to improve readability for 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 complexity (nested params, no output schema), the description covers all types and delivery options comprehensively. It lacks explanation of error handling or post-subscription usage, but overall provides sufficient context 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?

Despite 100% schema coverage, the description adds extensive value by providing detailed examples and constraints for each parameter (type-specific params, delivery channels with verification and caps). This goes well 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 clearly states the tool creates a proactive monitoring subscription and returns the subscription ID. However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'unsubscribe', but 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 important prerequisites (requires Pipeworx OAuth account) and constraints (sms verification, 10/day cap, webhook auto-disable). It does not explicitly state when not to use this tool or mention alternatives, but the guidance is clear and useful.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations, such as that it returns example questions with exact tool and argument shapes drawn from a live catalog, and that it can be called with no arguments for a full spread. No contradictions.

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

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

The description is front-loaded with common user queries like 'What can I ask Pipeworx?' and is structured clearly. Though somewhat verbose, every sentence serves a purpose: explaining functionality, listing examples, and providing usage guidance.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully explains the return format (category-bucketed example questions with tool+arg shapes), usage scenarios, and relationship to other tools. It is complete for a discovery-oriented tool.

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

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

Schema coverage is 100% (one optional parameter 'topic' with description). The description reinforces the parameter's usage and gives examples of values, but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as the onboarding entry point for understanding what Pipeworx can answer, returning category-bucketed example questions. It uses specific verbs and resources ('returns category-bucketed example questions') and distinguishes itself from siblings like ask_pipeworx, entity_profile, etc., by being the 'FIRST' tool to use.

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 this FIRST when you do not yet know what Pipeworx can do for you' and provides when to omit or pass a topic. It also mentions alternatives like meta-tools and lists specific topics like finance, pharma, etc.

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

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

The description goes beyond annotations by explaining that the subscription is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. Annotations already indicate idempotent and non-destructive behavior, which the description supports.

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 the main action, no wasted words. Every sentence adds essential information.

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

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

The description covers the tool's effect (deactivation, not deletion) and ownership constraint. It lacks acknowledgement of success/error responses or idempotency behavior, but given the simple single-parameter tool and annotation coverage, it is largely 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?

The input schema already provides a description for 'id' ('Subscription id (uuid) returned by subscribe'), which matches the description's mention of 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter semantics beyond the schema.

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

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

The description explicitly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes itself from the sibling 'subscribe' tool by mentioning ownership enforcement and the effect on historical events.

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

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

The description provides clear context: ownership enforcement ('you can only cancel your own subscriptions') and the result (deactivation, not deletion). However, it does not explicitly state when not to use this tool or suggest alternatives like 'list_subscriptions' to find the id.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral nuances: the meaning of 'could_not_verify' (check did not happen, not evidence), 'unsupported' (no source exists), and the routing logic between SEC EDGAR and the grounded pipeline. It also warns callers that 'could_not_verify' must not be shown as a verdict, adding valuable guardrails. 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 long paragraph, but it is densely packed with actionable information and logically sequenced: example queries, use case, routing, output description, and caveats. Every sentence earns its place, and the important error-handling note about 'could_not_verify' is front-loaded near the end but clearly flagged as IMPORTANT. Slightly verbose but not wasteful.

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

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

Despite having no output schema, the description fully explains the return values (verdict types, actual value, citation, reasoning) and edge cases (could_not_verify, unsupported). It also covers the tool's scope (what claim types are handled) and the routing behavior, making it self-contained for a complex tool. This is a complete description.

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% with descriptive text, but the description adds extra semantics: it explains that 'tolerance_pct' overrides the tolerance implied by claim wording and suggests setting 1–2 for hallucination detection. It also provides concrete examples of valid 'claim' inputs, enriching comprehension beyond the bare schema.

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

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

The description clearly identifies the tool as a claim-verification service with specific verbs like 'fact check' and 'verify the claim that', and it differentiates itself from siblings by detailing the structured SEC EDGAR fast path for financial claims versus the grounded pipeline for all others. It even enumerates the exact verdict types returned, leaving no ambiguity about what the tool does.

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

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

The description states explicitly when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and distinguishes between company-financial and other factual claims with separate routing. It further clarifies that 'Replaces 4–6 sequential calls', which helps an agent decide it's the right tool for a complex verification task. No alternative tools are named, but the conditional logic effectively excludes cases where simpler tools would suffice.

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