Fintech Intel

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds valuable extra context: the free default model (Workers AI) and the cost implication of using Anthropic (BYO key, pay Anthropic directly). This goes beyond the structured metadata and is important for the agent to understand cost/behavior.

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 compact and front-loaded with the core action, then adds key context (default model, cost, return structure). Every sentence earns its place without fluff. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description compensates by explicitly listing the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). All parameters are described in the schema with examples, and the description covers the key use cases. The tool is fully understandable without additional documentation.

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 minimal extra semantics beyond the schema, such as noting the default model is free and the _apiKey is 'passed straight through'. This is helpful but not substantial enough to raise the score above the baseline.

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

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

The description clearly states the action ('Probe one or more LLMs'), the target ('a business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from sibling tools by specifying AI-marketing audits and pre-launch brand checks, which is unique among the listed siblings.

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

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

The description provides clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention when not to use this tool or name alternative tools for comparative scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it routes to 5,564 tools, fills arguments, returns 'stable pipeworx:// citation URIs', and is a 'one fast call' that works on every tier. 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 long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured logically: use cases, examples, then escalation paths. Every sentence adds useful information, though it could be tightened slightly without losing value.

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

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

For a meta-router tool with no output schema, the description is thorough: it explains the routing behavior, output format (structured answer with citations), when to use it, and when to use alternatives. It fully equips an agent to decide and invoke correctly.

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

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

Schema covers 100% of parameters (all aliases for question), so baseline is 3. The description adds value by providing concrete examples of appropriate questions, clarifying the intended natural-language input beyond the bare schema definitions.

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

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

The description clearly states the tool's purpose: it routes factual questions to the right source tool among 5,564 tools and returns structured answers with citations. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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' and provides detailed when-to-use guidance, including trigger phrases and example questions. It also names alternatives for when to step up (ask_pipeworx_grounded, deep_research), giving clear exclusion conditions.

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, openWorld. Description adds valuable context: candidate improvements are 'enabled live whenever one is under test', no candidate is currently active, and it 'Falls back to nothing — this IS a full working router'. No contradiction with annotations.

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

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

Three sentences packed with relevant details: versioning, active candidate status, equivalence to stable router, and experimental purpose. The mention of the retired date is slightly extra but adds transparency.

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 universal router with no output schema, the description mentions 'same response shape' but never specifies that shape, relying on the agent knowing ask_pipeworx. It does provide enough context about scope (5,564 tools) and current behavior, but falls short of fully standalone completeness.

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

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

Schema covers 100% of parameters, including all six aliases for 'question'. Description adds no parameter-specific detail beyond saying 'same arguments' as ask_pipeworx, so schema carries the burden.

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 identifies tool as 'Beta version of ask_pipeworx' and explains it is an 'identical universal router' with 'candidate routing improvements', distinguishing it from the stable sibling. It also clarifies it is 'just the experimental edge', leaving no ambiguity about its role.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. While it doesn't list when not to use it, this is sufficient guidance for an experimental variant.

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

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

Beyond the read-only annotation, the description discloses additional behavioral details: it is hallucination-resistant, uses only the tool result to extract answers, and returns explicit refusal reasons when data is insufficient. These are important behavioral traits not covered by 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 well-structured with clear sections and lists, but it repeats the note about the extra LLM call and preference for ask_pipeworx twice. This slight redundancy keeps it from being perfectly concise, though it 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?

The description provides sufficient context for the tool's behavior, including its refusal modes and the fact that it returns evidence and confidence. It does not rely on an output schema but explains the return fields adequately. Overall, it is complete given the tool's complexity.

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

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

The input schema has 100% coverage with descriptions for all parameters (e.g., 'question' and its aliases). The description does not add further semantic meaning to the parameters; it only references 'question' in the context of natural language. Since schema coverage is high, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains that it extracts answers only from tool results and provides refusal reasons, distinguishing it from the standard ask_pipeworx tool.

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

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

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also advises against casual use: 'prefer ask_pipeworx for casual lookups.' This provides clear guidance on when to choose this tool over its sibling.

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

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

The annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail: low-confidence matches short-circuit, closed markets return a blocking status, wide spreads get tradeability flags, news fallback behavior is disclosed, and resolution-rule risk (e.g., 'refund_50_50') is documented. This exceeds the annotation baseline and even warns about recurring pure-rules losses.

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 accepted inputs, and sections like RESOLVER CONTRACT and SAFETY are clearly labeled with CAPS. It is long, but most content earns its place given the tool's complexity and absence of an output schema. A slightly tighter list of fan-out examples would make it more concise.

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

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

There is no output schema, so the description must explain return shapes and edge cases. It does so thoroughly: response shapes, market_match_confidence/score/alternatives, parent_event extraction, news fallback fields, closed-market status, low-confidence suppression, illiquid wide-spread tradeability, and cancellation-rule risk. This is complete for a complex research 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 the schema already documents market, depth, and include_raw. The description re-emphasizes the accepted 'market' input formats but does not add meaningful semantics beyond the schema. It also does not explain the depth enum or include_raw beyond what the schema already states, so it stays at the baseline.

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

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

The description opens with a specific, observable action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies accepted inputs (slug, URL, question text) and the core output (evidence packet + market-vs-model comparison), which distinguishes it from siblings like polymarket_edges or validate_claim.

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

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

The description gives clear 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 a classifier list and fan-out examples that help the agent choose when to call. However, it does not explicitly state when not to use it or name alternative tools for exclusion, so it stops short of a 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), specific data fields (revenue, net income, adverse-event counts), off-calendar fiscal year handling, sorting behavior, and output format (paired data + citation URIs). This is far beyond what annotations provide and includes 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 compact yet information-dense, beginning with intuitive user phrasing, then a clear core statement, followed by type-specific details and output notes. Every clause earns its place—there is no filler or repetition. The use of em-dashes and parallel structure keeps it scannable.

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 two-parameter tool with no output schema, the description thoroughly covers input semantics, data sources, per-type behavior, sorting, and return format, while explaining why this tool is preferable to alternatives. It is entirely sufficient for an agent to invoke it correctly across the full range of supported use cases.

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

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

The schema only names 'type' and 'values' with minimal descriptions. The description enriches both parameters by explaining exactly what each type retrieves ('type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt') and what values should contain (2–5 tickers/CIKs or drug names). It also adds fiscal year nuance that neither schema nor annotations cover.

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

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

The description opens with concrete query examples ('Compare X and Y', 'which is bigger') and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sibling single-entity tools like entity_profile by emphasizing that it replaces 8–15 sequential lookups.

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

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

The description provides explicit trigger phrases and a strong directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives type-specific guidance for company vs. drug and explains that comparisons are sorted by primary metric, giving the agent confidence in when and how to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior; the description adds substantial context beyond those: account tier requirements, parallel decomposition across 5,564 tools, response shape (findings packet with evidence, confidence, source, fetched_at, citations), explicit gaps[] for unanswered facets, contradictions[] for deeper depths, semantic excerpting, latency expectations, and the guarantee that citations are always fetchable. No contradiction with annotations.

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

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

The description is long, but nearly every sentence earns its place given the tool's complexity: auth, use cases, limitations, response format, depth semantics, and latency are all covered. It is front-loaded with an important account prerequisite, though the single dense paragraph could benefit from structural bullets. Slightly overlong 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?

With no output schema, the description carries the burden of explaining return values — and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers auth, latency, and exclusions. For a tool with this complexity and no output schema, the description is remarkably 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% and the schema already documents both parameters well. The description adds meaning beyond the schema by explaining how depth levels behave ('depth:"standard" re-angles unanswered gaps... depth:"thorough" additionally chases the best leads'), clarifying that the question can be broad/multi-part, and highlighting that decomposition is the core purpose. This exceeds the baseline 3 without being redundant.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call. It also clearly distinguishes itself from siblings, particularly ask_pipeworx ('For a single lookup use ask_pipeworx'), and lists concrete example use cases like 'compare X and Y's regulatory + financial exposure'.

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: 'Best for broad/multi-part questions over structured data.' It also provides clear exclusions and alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It even covers account/auth requirements, noting that unsigned-in users should use ask_pipeworx instead.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations and helps the agent understand the output format and immediate usability.

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 slightly long but efficiently structured. It opens with the core purpose, then provides usage context, lists applicable domains, explains the return format, and ends with strategic advice. Every sentence adds value; the domain list is lengthy but informative. It earns a 4, not 5, due to the somewhat verbose enumeration.

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

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

For a discovery tool, the description is quite complete. It explains what the tool does, when to use it, what it returns (names, descriptions, full schemas, examples), and how to call it first. Despite lacking an output schema, the description covers the output shape sufficiently. Annotations cover safety/profile. The only minor gap is the absence of a concrete example response, but that's not necessary.

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 some context by saying queries should 'describ[e] the data or task' and lists example domains. However, these examples are already in the schema (e.g., 'analyze housing market trends', 'look up FDA drug approvals'). The description doesn't significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and differentiates itself from sibling tools by positioning as the discovery/meta-tool among domain-specific tools. The explicit list of domains and the phrase 'Call this FIRST' further distinguish it.

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

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

The description provides clear use cases: 'Use when you need to browse, search, look up, or discover what tools exist...' and strategic guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lacks an explicit 'when not to use' but the guidance implies if you already know the specific tool, this isn't needed.

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 (readOnlyHint, idempotentHint, etc.), the description reveals rich behavioral details: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific data structures; notes the patent API sunset and soft-fail behavior; and explains the GDELT→GNews fallback. This adds meaningfully to what annotations alone convey, without contradiction.

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

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

The description is a single dense paragraph containing numerous details, examples, and caveats. It is information-rich and front-loaded, but its run-on structure makes it harder to scan. A bulleted list or shorter sentences would improve clarity without losing value.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It enumerates the exact components returned (cik, recent_filings with URIs, fundamentals, patents, news, LEI), including limits like 'up to 5' and sort order. It also addresses edge cases (names not supported, USPTO sunset) making it 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?

The input schema already documents both parameters and covers 100% of them. The description reinforces with concrete examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') and explicitly excludes names, adding format-level guidance that goes beyond the schema's enum and type 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 opens with concrete query examples and a clear definition: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings by explicitly comparing to single-pack SEC/XBRL/news lookups and referencing resolve_entity for name inputs, so the agent knows exactly what this tool uniquely provides.

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 when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to ('names not supported — use resolve_entity first if you only have a name'). It also names the alternative (resolve_entity), providing clear decision boundaries.

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 false, so the safety profile is clear. The description adds useful behavioral context by listing the types of data returned (FDIC data, balance sheets, compliance status, failure risk, consumer complaints), which helps the agent set expectations. 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, well-structured sentence that front-loads the action ('Assess') and includes the key output categories. No filler or redundancy.

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

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

Given the tool's simplicity (one parameter, strong annotations, output schema present), the description provides adequate context including expected return content. It doesn't mention potential limitations like US-only coverage or data availability, but these are minor given the FDIC reference. Overall, it's complete for typical use.

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

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

The input schema already fully describes the single parameter (bank_name) with 100% coverage. The description merely adds an example and restates 'by name', which adds marginal value beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Assess') and resource ('bank's financial health, risk profile, and regulatory status'). An example is provided. However, it does not distinguish this tool from sibling tools like 'fintech_company_deep_dive' or 'entity_profile', so it falls short of a 5.

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

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

The description implies usage for bank health assessment by name, but provides no explicit guidance on when to use this tool versus siblings such as 'fintech_company_deep_dive' or 'entity_profile'. No exclusions or alternative recommendations are given, so it only meets the baseline for implied usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds the specific output categories but does not disclose additional behavioral traits such as rate limits, authentication requirements, or how the multiple data sources are aggregated. This is acceptable given the annotation coverage but not particularly rich.

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 concise sentence, front-loaded with the action and resource. It uses a clear list structure for return types and contains no redundant or filler text. Every word earns its place.

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

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

Given a rich output schema and annotations, the description adequately summarizes the tool's scope and return value categories. It could be more explicit about how this deep dive differs from sibling tools like fintech_bank_health_check, but the combination of description, schema, and output schema covers the essential context 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 description coverage is 100%, with each parameter (ticker, _avKey, _fredKey) meaningfully described. The description reiterates the ticker input and provides an example ('AAPL'), but adds no new information beyond what the schema already offers. The baseline of 3 applies because the schema carries the full semantic load.

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

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

The description opens with a specific action 'Analyze' and clearly specifies the resource ('a fintech company's financials, risk profile, and regulatory history') and the input method ('by stock ticker'). It enumerates concrete return types (SEC filings, income statements, stock quotes, consumer complaints, company overview), making the tool's purpose distinct from more generic research tools.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like fintech_bank_health_check or fintech_market_snapshot. There are no exclusion criteria, alternative references, or context signals indicating preferred scenarios, leaving the agent to infer usage from the tool's name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context (e.g., data freshness, rate limits, or that it returns a snapshot rather than historical data). It does not contradict annotations.

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

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

The description is a single, front-loaded sentence with a clear verb and an enumerated list of outputs. Every word contributes meaning, with no redundancy or filler.

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

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

Given the simple, read-only nature of the tool, the presence of an output schema, and the optional parameter already documented in the schema, the description is largely complete. It lacks context like update frequency or data sources, but for a snapshot tool with good annotations and schema coverage, it is adequate.

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

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

Schema description coverage is 100% for the single optional parameter (_fredKey), which is already described as 'FRED API key (optional, for macro rates)'. The description itself does not mention the parameter, but since the schema fully covers it, the baseline of 3 applies.

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

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

The description uses a specific verb ('Check') with a clear resource ('current financial market conditions') and enumerates exact outputs (complaint trends, banking sector summary, rates, yields, curve, spreads, VIX). This distinguishes it from sibling tools like fintech_bank_health_check, which focuses on bank-specific health, and fintech_company_deep_dive, which drills into individual companies.

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 no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states what it returns, leaving the agent to infer usage from the tool name and output list.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate this. It adds usage context but does not disclose behaviors like what happens when the key doesn't exist or whether deletion persists across sessions. This is adequate given annotation coverage, but not rich.

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 short sentences: first states the core action, second provides usage scenarios, third references complementary tools. No redundant wording or unnecessary detail.

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

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

The tool is very simple: one parameter, no output schema, and annotations already cover safety. The description covers purpose, usage, and tool relationships. It does not mention error conditions or return values, but for a destructive action with idempotentHint, this is a minor gap in an otherwise 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 fully covers the single parameter 'key' with description 'Memory key to delete' (100% coverage). The description repeats 'by key' without adding new constraints or syntax details, so a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory' with the mechanism 'by key'. It clearly distinguishes this from siblings like remember and recall by focusing on removal.

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

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

The description explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and also names related tools ('Pair with remember and recall'), providing clear context for when to select 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 annotations (readOnlyHint, idempotentHint, etc.), the description discloses that the tool 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It adds network-fetch behavior and output format, which is useful context, though it doesn't cover edge cases like error handling or rate limits.

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

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

The description is concise and front-loaded: the first sentence states the primary purpose, followed by a brief process explanation and concrete use cases. Every sentence adds value with no redundancy, making it highly efficient.

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

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

For a 2-parameter tool with no output schema, the description is remarkably complete. It explains the process, explicitly states the return format ('single text blob'), and provides usage scenarios. Combined with safe annotations, an agent has enough context to invoke and interpret the tool correctly.

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

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

The input schema already describes both parameters with 100% coverage, so the baseline is 3. The description does not add extra meaning beyond what the schema provides; it only restates that it works 'for any URL' without elaborating on max_links or syntax.

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

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

The description explicitly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL' and explains the process (fetches, extracts, emits). It clearly distinguishes this tool from siblings like ai_visibility_check or scan_competitor_ai_presence, which focus on checking visibility rather than generating the file.

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 use cases via 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives explicit contexts for when to use the tool, though it does not name alternative tools or state exclusions, so it stops short of a 5.

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

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 well-covered. The description adds value by specifying the exact fields returned, but it does not disclose behavior like default filtering of inactive subscriptions (though the schema covers the include_inactive parameter). This is a reasonable addition beyond annotations but not extensive.

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, front-loaded with the core action, and includes a concise return-field list plus a practical usage tip. Every word earns its place with no waste.

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

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

This is a simple read-only tool with rich annotations and a self-explanatory schema. The description clarifies the return format and typical use cases, which is sufficient for an agent to invoke it correctly. The lack of an output schema is mitigated by the explicit field list.

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% description coverage for its single parameter (include_inactive), with a clear description in the schema itself. The tool description does not add further parameter semantics, but the schema already provides sufficient meaning, so this meets the baseline.

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

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

The description clearly states it lists the caller's active subscriptions and even enumerates the fields returned (id, type, params, etc.), making its purpose unmistakable. It also differentiates itself from sibling tools like subscribe/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 provides explicit context: it is for reviewing current monitoring before adding more subscriptions or for finding an id to cancel. It does not explicitly name alternatives, but the use case is clear and practical, effectively guiding 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?

The description discloses several behaviors not inferable from annotations: the tool is rate-limited to 5 per day per identifier, it returns a claim_token for later retrieval, and it does not count against the tool-call quota. It could have been more explicit about the immediate response format, but it clearly covers side effects and follow-up behavior without conflicting 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 longer than average but every sentence contributes specific guidance (scope restrictions, token mechanism, rate limit). It is well-structured with imperative instructions and caveats, earning its length without being bloated.

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 feedback tool with no output schema and optional parameters, the description covers the full workflow: when to use, what to include, what to avoid, how to claim and read follow-ups, and operational limits. It is suitably complete for the tool's complexity.

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

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

Schema coverage is 100%, providing baseline semantics for all parameters. The description adds extra value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and warning against pasting the end-user's prompt, giving deeper context that the schema does not.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by stating it is ONLY for tools served by this Pipeworx connection and explicitly excludes feedback for other vendors' connectors.

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

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

Provides explicit when-to-use conditions (bug, feature/data_gap, praise) and when-not-to-use (other MCP servers) with instructions to file elsewhere. Also guides the user on how to determine if a tool belongs to Pipeworx and how to structure the feedback, making the trigger logic unambiguous.

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 the annotations by revealing the data source ('derived from CF analytics-engine'), the privacy guarantee ('no PII'), the payload shape ('just (pack, tool, count)'), and the caching behavior ('Cached 5min-1h depending on window'). This complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is concise and front-loaded: the first sentence states the core function, followed by a practical uses list, then data provenance and caching. Each sentence adds value, and the structure makes it easy to scan.

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 single optional parameter and no output schema, the description provides sufficient context: it names the output elements (top tools, top packs, total call volume), the data format ((pack, tool, count)), and the typical use cases. This is complete enough for an agent to decide 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?

The input schema already fully describes the single 'window' parameter, including its enum values and the trade-off between short and long windows. The description only repeats these options without adding new detail, so the baseline of 3 applies.

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

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

The description opens with a clear statement of what the tool does: 'What other AI agents are calling on Pipeworx right now' and specifies the returned data ('top tools, top packs, and total call volume'). It clearly distinguishes this from sibling tools like discover_tools by focusing on agent call patterns and aggregation.

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 'Useful for' list provides three concrete scenarios when to use the tool, such as 'discovering what data sources are hot for current events' and 'confirming a popular tool is the canonical choice.' However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals rich behavioral detail: fill-check logic (theoretical_edge_pp_at_book vs realizable_edge_pp at 1000 shares/leg), threshold deviations (>3pp), placeholder filtering (>20% returns null), semantic similarity threshold (≥0.30 Jaccard), and the returned signal structure. It even cautions 'do not trade it' when realizable edge ≤0, which is critical behavioral context.

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

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

The description is long but every sentence adds critical operational detail. It is front-loaded with a one-line summary and then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) which aids scanning. Slight deduct for being somewhat sprawling and using ALL-CAPS separators rather than a more standard structure, but the density and relevance justify the length.

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

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

The tool has no output schema and complex behavior across three modes, but the description covers all key aspects: mode selection, input examples, comparator logic, filters, fill-check pricing, return shape (opportunities[] with gap_pp, suggested_trade, reasoning), and edge-case semantics. It also cross-references sibling tools, making this description effectively self-sufficient for an 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?

Although schema descriptions already cover 100% of parameters, the tool description adds substantial semantic value: it explains how the event slug ('fed-decision-may-2026') or topic seed question ('Strait of Hormuz traffic returns to normal') maps to different algorithms, provides recommended usage, and describes the scanning behavior each parameter triggers. This goes well beyond the schema's basic 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by describing three modes (trending_scan, event, topic) and explicitly contrasts with tools like polymarket_fill_risk. The methodology and output types are specified, 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 provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also gives concrete examples for each mode, explains what cross-event mode catches that single-event misses, and directs users to polymarket_fill_risk for custom sizing. This is model-tier usage 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 goes far beyond the annotations. It details three model families, response segments, edge calculations, slippage assumptions, Kelly caps, tradeable-edge knobs, diagnostics with funnel counters, the 24h-move warning, why Fed bets are excluded, and even the 1h KV cache. This is exceptional behavioral disclosure with no contradiction to the readOnly/idempotent hints.

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

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

The description is exceptionally long and dense, though organized with ALL-CAPS section labels. Every sentence carries technical weight, but it is not concise; an agent must parse a large block of text to extract actionable guidance. It is appropriately structured for its complexity but would benefit from tightening.

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 a complex response structure, the description fully compensates by detailing the top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), explaining why segments may be empty, and describing the caching behavior. It gives agents enough context to interpret results and troubleshoot empty responses.

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 coverage is 100%, so baseline is 3. The description adds meaningful semantic context beyond the schema, such as explaining that min_partition_leg_kelly applies per-leg because parent-level kelly is always zero for partition arbs, and clarifying slippage expectations ('Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp per trade').

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

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

The description clearly states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also defines the use case ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling tools such as polymarket_arbitrage or polymarket_edge_tracker; its differentiation is implied through its unique internal structure rather than stated directly.

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

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

The description provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This tells an agent when to use it. It does not explicitly mention alternatives or when-not-to-use cases, but the context is strong enough to guide selection.

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 safe read-only, non-destructive, idempotent behavior. The description adds substantial context: snapshot write semantics (cache-miss), TTL limits, data gaps, and that decay is computed on daily closes not intraday. 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?

Structured into purpose, Args, RESPONSE, and LIMITS, with each sentence carrying unique information. Slightly long but appropriate for the complexity; could be tightened without losing substance.

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

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

Despite no output schema, the description fully specifies response fields (tracked, expired, snapshot_dates) and their semantics, plus important limitations like TTL and daily-close-based decay. Complete for a read-only telemetry tool.

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

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

Schema covers both params with defaults and clamps. The description goes beyond by explaining window families (24hr|1wk|1mo), the response structure, and the meaning of days as lookback. This adds value beyond the 100% schema coverage.

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

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

The description states precisely that the tool tracks edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It clearly differentiates from sibling tools like polymarket_edges by focusing on time-series telemetry rather than current edge values.

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

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

Provides clear context for when to use: to distinguish fresh vs aged edges before trading, noting that a 3-week-old wide edge is a different trade. It implies alternatives (e.g., polymarket_edges for current edges) but does not explicitly name them or state 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 readOnly/idempotent/non-destructive, but the description adds substantial context: it walks the order-book ladder, returns a verdict, and warns that partial basket fills convert an arb into an unhedged directional position—a non-obvious operational risk. This goes well beyond the structured hints.

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

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

The description is dense and front-loaded, using SINGLE-MARKET/BASKET labels to structure the two modes. It contains almost no fluff, but the long paragraphs and many return-field names make it a bit heavy to scan quickly. Still, every sentence earns its place.

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

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

For a complex two-mode tool with no output schema, the description is remarkably complete. It enumerates return fields, explains defaults, size interpretation, and the key risk of partial basket fills, so an agent can predict behavior and invoke it correctly without further information.

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

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

Schema covers 100% of parameters (baseline 3), but the description richly enriches semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market and settlement notional in basket; side defaults differ by mode; market vs event selects the mode. This is meaningful added meaning 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 names a specific, well-scoped operation: a realizable-vs-theoretical edge check against live CLOB order-book depth. It clearly distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by targeting fill risk and explicitly frames when it should be invoked.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing a concrete gate. It also differentiates single-market and basket/partition modes, including their separate side handling and size semantics.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description richly discloses behavioral nuances: compatibility_warning triggers with specific conditions (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), temporal_alignment meaning when aligned:false, and skipped_cross_type/subtype counters for dropped comparisons. This goes far beyond what annotations provide, giving the agent critical insight into how matches are validated and why results may be empty.

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

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

The description is long and dense, but it is well-structured: it opens with the core purpose, then uses 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' as clear navigational markers. Every sentence introduces new operational or behavioral information; however, some phrasing is overly technical (e.g., 'cross-type = metric_type mismatch like MoM vs YoY; cross-subtype = inequality mismatch') which could be simplified without losing meaning.

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

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

Given the tool has no output schema and high complexity, the description thoroughly covers inputs, response structure (leg-by-leg prices, top_spreads_pp with calculation formula), and critical caveats (temporal alignment, compatibility warnings). It even explains what the absence of matches means, so the agent can interpret empty results correctly. This is comprehensive for a tool with these parameters and no formal output schema.

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

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

The schema already has 100% parameter coverage with descriptions, so the baseline is 3. The description adds value by defining the two modes (topic vs explicit), explaining the override relationship ('Overrides the topic-mapped Kalshi side'), and listing the exact topic shortcut values. This clarifies the interaction between parameters, though the schema alone already provides most of the necessary semantics for individual params.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which names a specific verb (spread calculation) and distinct resources (Kalshi, Polymarket). It clearly distinguishes from sibling tools focused on single-venue analysis or other cross-venue arbitrage tools by emphasizing the cross-venue nature and the explicit matching logic.

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 two clear usage modes: 'topic' shortcuts and explicit ticker/slug pairings, with examples. It also gives a strong caveat: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which warns when not to use the shortcut. However, it does not explicitly reference alternative sibling tools (e.g., polymarket_arbitrage) or state when to prefer those, so it misses an explicit exclusion/alternative statement.

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

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

Annotations already cover read-only, idempotent, and non-destructive traits. The description adds meaningful behavior beyond those: scoping to the user's identifier (IP, key hash, account ID) and the behavior of omitting the key to list all keys. It stops short of describing return shape, but adds value over annotations.

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

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

Two sentences, front-loaded with the verb and resource, with no wasted words. Each clause contributes: retrieve/list behavior, use-case examples, scoping, and pairing with remember/forget.

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-optional-parameter tool with no output schema, the description covers purpose, usage context, scoping, and lifecycle pairing. The lack of return-format details is not a gap here because the operation is inherently simple and the context signals are rich.

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

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

The schema already documents the 'key' parameter with 100% coverage. The description adds crucial semantics: omitting the key lists all keys, and the value was stored via 'remember,' clarifying what a key refers to. This exceeds the schema's baseline.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys when the key is omitted. It names the specific source ('remember') and distinguishes from siblings ('forget' deletes), making the read operation 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?

It gives clear context: use it to look up previously stored context (ticker, address, research notes) without re-deriving it. It also references how it pairs with 'remember' and 'forget,' but does not explicitly state when not to use it or identify alternative tools for similar lookups.

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

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

The description explicitly states that setting mark_read:true flags events as read and affects future calls, which is a state-modifying behavior. This directly contradicts the annotations' readOnlyHint=true. Per the rule, a description contradicting annotations scores 1. This is a serious inconsistency.

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

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

The description is a 5-sentence paragraph, but every sentence carries useful information: purpose, return contents, filtering, mark_read, polling, and alternative endpoint. It is front-loaded and efficient, though slightly longer than the highest-performing examples.

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 5 optional parameters and no output schema, the description is remarkably complete: it explains return payload, filtering options, mark_read side-effect, polling suitability, and an alternative access URL. It doesn't cover error cases or edge behaviors, but the core usage is well explained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving an example for type (e.g. 'sec_8k'), explaining mark_read semantics, and clarifying the since parameter as ISO timestamp. This goes 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?

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It uses a specific verb (pull), identifies the resource (subscription feed), and mentions return contents. It distinguishes itself from siblings like list_subscriptions by focusing on alerts/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 gives usage context (polling, filtering, mark_read) and even mentions an alternative HTTP endpoint for scripts/dashboards, but it does not explicitly contrast with sibling tools or state when to use this tool over alternatives. It implies usage for reading alerts 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 readOnly/openWorld/idempotent, but the description adds substantial behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback with a failure trigger ('rate-limited or 5xx'), USPTO soft-fail due to PatentsView API sunset, and a grouped changes return format with pipeworx:// citation URIs. This goes well beyond the annotations.

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

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

The description is dense but efficiently organized: opening query patterns, then source fan-out details, then parameter behavior, then return value, then explicit alternative. Every sentence carries essential information, and the most actionable guidance is front-loaded. No filler or 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?

This is a multi-source, complex tool with no output schema, so the description must carry the burden of explaining behavior and returns. It covers the sources, fallback logic, failure modes, date formats, return structure, and the key sibling alternative. The description is fully sufficient for an agent to invoke this tool correctly and interpret results.

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

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

All three parameters are already fully described in the schema with the same examples (ISO date/relative shorthand, ticker/CIK, company-only enum). The description does not add meaning beyond the schema—it simply restates the same semantics in prose. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description opens with concrete query patterns ('What's new with X' / 'latest on Y') then states its core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It names explicit output (changes[], total_changes, citation URIs) and differentiates from entity_profile by contrasting dynamic changes vs static profile.

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

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

It gives clear when-to-use signals via natural-language examples and a time-window scoping ('in the last N days/weeks/months'). It also provides an explicit alternative: 'Use entity_profile instead when you want the static profile...' This directly guides tool selection and prevents misuse.

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 adds key behavioral details: key-value pair scoping by agent identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. It discloses retention and scoping, which are not covered by the annotations, and does not contradict any hints (idempotentHint=true aligns with the nature of saving).

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, front-loaded with the core purpose, and each sentence adds distinct value: definition, usage, storage semantics, and pairing with sibling tools. There is no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description covers all essentials: what it does, when to use it, how data is stored, persistence behavior, and related tools. The low complexity means this is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already fully describes both parameters (key and value) with examples. The description adds semantic context by giving specific examples of what to store (resolved ticker, target address, user preference), which helps the agent choose appropriate keys and values, providing value 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 clearly states the tool saves data for later reuse across conversations or sessions, using the specific verb 'save' with the resource 'data'. It distinguishes itself from sibling tools by explicitly naming recall and forget as counterparts for retrieval and deletion.

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

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

It provides concrete when-to-use guidance with examples like 'a resolved ticker, a target address, a user preference' and explains the alternative tools ('Pair with recall to retrieve later, forget to delete'). This makes the usage context unambiguous relative to its siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so agent knows it's safe. The description goes beyond annotations by detailing cascading lookup behavior, graceful degradation if GLEIF/OpenFIGI are unavailable, disclosure of unresolved identifiers under an 'unresolved' field, and that each call replaces 2-3 manual lookups. This is rich behavioral context. Only minor gap: doesn't mention response format details, but output schema absence makes that a small miss.

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 packed with useful information but is structured as one long paragraph without clear breaks. It front-loads examples followed by details on supported types. Every sentence adds value, but the lack of structure (bullets or line breaks) for a lengthy description reduces scannability. Still concise 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?

Given the tool has 2 params, no output schema, no nested objects, and annotations cover safety/idempotency, the description provides complete context. It explains input formats, resolution logic, supported identifiers, error behavior (graceful degradation), and how it relates to other lookups. Nothing essential is missing for a practical understanding.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how the 'value' parameter works in context (e.g., 'ticker (AAPL)', 'CIK (0000320193)') and how ISINs resolve via GLEIF. For the 'type' parameter, it provides real-world examples of when to use each. The description clearly enhances understanding beyond the schema, earning 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 uses specific verbs like 'resolve', 'look up', and provides concrete examples ('ticker for...', 'find the CIK for...'). It clearly identifies the resource as user-spoken names to canonical/official identifiers. It distinguishes itself from siblings by mentioning it replaces 2-3 manual lookups, and sibling tools like 'compare_entities' or 'entity_profile' have different purposes.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It also covers supported entity types and indicates when LEI/FIGI enrichment may degrade gracefully. It doesn't need to state when-not-to-use because the context makes it obvious this is for entity resolution, not for other tasks.

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 detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also discloses that using 'anthropic' model requires an API key passed to api.anthropic.com, which is 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, front-loaded with the primary action, and every sentence adds value. No redundancy with schema or annotations.

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

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

For a tool with no output schema, the description covers the return format (ranked list with score, confidence, signal density) and the probing behavior. It lacks potential limitations like rate limits or error handling, but given the rich annotations and full parameter descriptions, 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining that the first entity is treated as the 'subject' for narrative, and clarifies that context is shared across probes. This helps disambiguate common entity names.

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

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

The description uses a specific verb 'Compare AI visibility across multiple entities side-by-side' and clearly distinguishes itself from the single-entity sibling ai_visibility_check by describing the comparative, ranked output. Example use case and return details further clarify purpose.

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

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

It provides a clear use case ('competitive AI-marketing audits') and implies when to use it over single-entity probes. However, it does not explicitly name alternatives or exclusion criteria like when not to use it (e.g., for single-entity analysis).

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 the readOnly/openWorld/idempotent annotations: it describes composite data sourcing, graceful partial failures, timeout behavior, and a 5-30s first-measurement caveat. 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 efficient and front-loaded with the core purpose. Each sentence earns its place: purpose, use cases, return fields, ecosystem limits, and performance caveat. Despite moderate length, it is tightly structured with no fluff.

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

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

For a complex composite tool, the description is remarkably complete. It lists the return summary fields, alternative version details, ecosystem restrictions, failure behavior, and performance expectations. Since there is no output schema, this explanatory text is essential and thorough.

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 minimal parameter meaning beyond the schema—'package' and 'version' are already described with defaults and examples. It does reinforce npm-only scope but provides no extra syntax or format details.

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

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

The description states a specific verb+resource+scope: 'Composite should I add this npm package to my project check' that fans out across deps.dev and bundlephobia. It clearly distinguishes from siblings by focusing on npm dependency evaluation, contrasting with other analysis 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?

Explicit use cases are given: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion and alternative: '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?

The description discloses the underlying mechanism (BGE-base-en embeddings, cosine, 500-char overlapping windows), the output format (character offsets and similarity scores), and truncation behavior with a 200K char cap and flagging. This goes well beyond the annotations which only indicate read-only/idempotent, adding meaningful operational context.

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

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

The description is front-loaded with the core action and delivers additional detail in compact sentences. Every clause earns its place: the usage scenario, the pairing, and the technical specifics are all relevant and non-redundant.

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

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

Given the absence of an output schema, the description thoughtfully covers return values (passages with offsets and scores), input constraints (text cap and truncation), and integration with sibling tools. It provides enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context beyond the schema: 'Pass the text you already pulled' clarifies that `text` is a pre-fetched record, and 'get back the top-N passages' directly maps to `limit`. It also provides example queries, but the schema already documents parameter meanings thoroughly, so only a modest improvement.

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 'Semantic search INSIDE a fetched record', specifying the verb (search) and resource (a fetched record). It distinguishes from siblings by noting it 'Pairs with ask_pipeworx_grounded' and implies a workflow of fetching then searching inside, clearly separate from other sibling tools that do broader research or grounding.

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

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

It provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and describes the pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent not only when to use but also how it relates to an alternative/complement.

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?

Annotation contradiction: the idempotentHint=true token conflicts with the description's 'Returns the new subscription id', implying each invocation creates a new subscription (non-idempotent). The description does provide rich behavioral details (OAuth requirement, phone verification, 10/day SMS cap, webhook signing secret, auto-disable), but the contradiction forces a score of 1.

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

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

The description is long but information-dense, with every sentence earning its place. It structures content logically (purpose, requirements, types, delivery), and while it could be broken into separate paragraphs, it remains free of 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?

Given no output schema, the description explicitly states the return value (new subscription id). It covers authentication, all subscription types, delivery options, verification steps, limits, and webhook failure behavior. No obvious gaps remain for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, and the description adds substantial meaning beyond the schema. It gives concrete examples for each type (e.g., 'items:["5.02"] = officer change', 'params:{topic:"fed"}', 'series_id:"UNRATE"') and details delivery channel semantics (verified phone, 10/day cap, webhook signature verification). This far exceeds the baseline.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream', clearly stating the verb and resource. It then enumerates the supported types (sec_8k, polymarket_edge, fred_series), distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 specifies a prerequisite (requires a Pipeworx OAuth account) and explains that the feed is always on, with retrieval via recent_alerts or a GET endpoint. This gives clear context for when to use this tool versus reading alerts, though it doesn't explicitly mention alternatives like list_subscriptions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable post-conditions: it returns category-bucketed examples drawn from the live catalog, including associated tool/argument shape. It doesn't disclose any failure modes or rate limits, but the annotation coverage is strong, so a 4 is appropriate.

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 somewhat long but front-loaded with natural-language intents. It uses a clear cause-and-effect structure and communicates many use cases without wasted words. The list of example categories adds context but could be shorter without losing meaning.

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

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

For a tool with one optional parameter, no output schema, and rich annotations, the description is remarkably complete: it explains the return payload (category-bucketed examples with tool+argument shape), the invocation modes (no args vs topic), and the intended first-time-user scenario. It fully covers what an agent needs to invoke it correctly.

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

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

Schema coverage is 100% and the one optional parameter `topic` has a clear description with enumerated example values. The description repeats the topic examples but adds no new meaning beyond the schema. Baseline 3 is correct since the schema does the heavy lifting.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape needed. It distinguishes itself from siblings by framing it as the 'getting started' / 'what can you ask' tool, and explicitly lists the meta-tools it helps you learn (ask_pipeworx, entity_profile, compare_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?

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also clarifies the optional topic parameter to focus, and implies when not to need it (once you already know what to ask). This distinguishes it from discovery alternatives in 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?

The description adds significant behavioral context beyond the annotations. It reveals that the row is deactivated but not deleted, ensuring historical events remain available, and it explains ownership enforcement. These details go beyond the readOnlyHint and destructiveHint annotations, giving the agent a clear mental model of the operation's side effects.

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

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

The description is exceptionally concise, using three short sentences that each convey essential information: purpose, ownership restriction, and deactivation behavior. It is front-loaded with the core action and contains no filler.

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

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

The tool is simple (one parameter, no output schema). The description covers purpose, ownership, and the exact effect on data (deactivation vs deletion). This is sufficient for the tool's complexity, and the sibling tools provide additional context for selection.

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 describes the id parameter with 100% coverage, including its type and source ('returned by subscribe'). The description mentions 'by id' but does not add new semantics. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Cancel a subscription by id.' It also specifies that only your own subscriptions can be canceled, which differentiates it from subscribe and list_subscriptions. The verb 'cancel' and resource 'subscription' are explicit 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 clear context for when to use the tool: when you need to cancel a subscription. It also explains an important constraint (ownership enforcement) and the effect on historical events via recent_alerts, which helps with usage decisions. It does not explicitly list alternatives or exclusions, but the context is clear enough.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses the two processing paths (SEC EDGAR + XBRL vs. grounded pipeline), explains the meaning of verdicts, and crucially differentiates 'could_not_verify' (check did not happen) from 'unsupported' (no source exists). It also notes the replacement of sequential calls, providing rich behavioral context. No contradiction with annotations.

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

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

Although the description is long, it is densely packed with essential information and front-loaded with concrete example queries. Every sentence adds value—covering paths, return values, error semantics, and efficiency benefit—without fluff. The structure is logical and easy to scan.

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

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

Given the tool's complexity (two pipelines, multiple verdict types, error handling) and the absence of an output schema, the description is remarkably complete. It explains what the tool returns (verdict, actual value with citation, reasoning), clarifies the critical distinction between could_not_verify and unsupported, and specifies the supported claim types. No gaps remain.

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

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

The input schema already documents both parameters thoroughly (100% coverage). The description adds further nuance: tolerance_pct overrides the claim's implied tolerance, is capped at 5, and can be set to 1–2 for hallucination detection. It also clarifies that the claim is a natural-language statement. This enriches the 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 clearly states the tool's function: 'natural-language claim verification against authoritative sources' and provides specific trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from siblings by focusing on claim verification and explicitly noting it replaces 4–6 sequential calls, setting it apart from broader tools like deep_research or ask_pipeworx_grounded.

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

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

The description gives a clear use case: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). However, it does not explicitly mention when not to use this tool or name alternative siblings, so it falls short of a 5.

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