Brapi

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: returns per-model {score, confidence, signals, raw_response} + combined view, passes API key directly to Anthropic, and notes the free default model. 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?

Single paragraph with clear frontloading: main action first, then defaults, parameter notes, return format, use cases. Every sentence adds necessary information without redundancy or fluff.

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

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

Given 4 params (1 required), no output schema, the description covers purpose, all parameters, return format (per-model and combined), and use cases. Lacks explicit error handling or rate limits but annotations are sufficient. Could add detail about 'signals' or confidence, but overall complete for intended usage.

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

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

Schema coverage is 100% (baseline 3). Description adds value: explains that '_apiKey' is for Anthropic and cost implications ('BYO key — you pay Anthropic directly'), describes 'models' supported values, and gives example for 'context' parameter (e.g., 'Boston restaurant'). Exceeds 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 uses specific verb 'probe' and resource 'LLMs for visibility', clearly stating it scores visibility (0-100) per model. It distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on brand/topic knowledge probing across multiple LLMs.

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 cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Mentions default model and API key requirement for Anthropic, but lacks explicit when-not-to-use or alternative tool guidance, though context signals help.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the routing mechanism, citation URIs, fast execution, and that it works on all tiers. 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 somewhat long but well-structured with a front-loaded 'PREFER OVER WEB SEARCH' and clear sections for usage guidance and examples. Slight redundancy but overall effective.

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

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

Given the complexity of siblings and many possible queries, the description covers what it does, output format (structured with citations), and when to use alternatives. No output schema but return type is sufficiently described.

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

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

Schema coverage is 100% with all parameters described as aliases for question. The description does not add extra meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to specialized tools across many sources, returning structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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 'START HERE for most questions' and provides clear when-to-use guidance for alternatives (ask_pipeworx_grounded for hallucination-resistant single answer, deep_research for broad multi-part questions). Lists query types and examples.

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, open-world, idempotent, non-destructive behavior. The description goes further by detailing the internal process (tool selection, argument filling, data fetching, answer extraction) and the exact return structure, including success and refusal formats. No contradiction with annotations.

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

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

The description is a single paragraph of moderate length, but every sentence serves a purpose. It starts with the core value proposition and proceeds logically. Minor improvement possible with bullet points, but still effective.

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

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

Without an output schema, the description fully explains the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It covers the tool's behavior, trade-offs, and usage context comprehensively.

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

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

Input schema has 100% coverage on descriptions, but the description adds value by explaining that the primary parameter 'question' accepts multiple aliases and should be in natural language. This contextualizes the schema's alias list.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, and explicitly distinguishes it from its sibling 'ask_pipeworx' by describing the grounded extraction process and the trade-off in cost.

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

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

The description provides explicit guidance: use when answers will be quoted, cited, or acted on, and prefer 'ask_pipeworx' for casual lookups. It also notes the cost of one extra LLM call.

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, and openWorld hints. Description adds that the list is from brapi.dev and supported by the quote endpoint, providing context but not additional behavioral traits beyond what annotations indicate.

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?

Single sentence front-loading the source and purpose. No unnecessary words, 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?

Simple tool with no parameters, comprehensive annotations, and an output schema. Description adequately completes the picture by specifying the source and scope of the data.

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

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

No parameters in input schema, so baseline is 4. Description does not need to add parameter details; it correctly indicates no inputs are required.

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

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

Description clearly states it provides a 'complete list of all available Brazilian market ticker symbols' for the quote endpoint. Verb and resource are specific, and it distinguishes from sibling tools like 'quote' and 'quote_list' by focusing on the set of supported symbols.

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

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

No explicit guidance on when to use vs alternatives. Implies use when you need the full list of tickers, but lacks exclusion cases or references to related tools like 'quote_list' for retrieving quotes for specific symbols.

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

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

The description goes far beyond the annotations by detailing the resolver contract (market_match_confidence, suggestions), fan-out logic per category, parent event extraction, news fallback behavior, safety short-circuits for low-confidence or closed markets, and resolution-rule risk. This provides full behavioral context for an agent to safely invoke the tool.

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

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

The description is extremely detailed and well-organized but overly long. While every sentence adds value, the length may overwhelm an agent. The front-loading of the main purpose is good, but the sheer volume of detail (classifiers, fan-out examples, response shapes, safety mechanisms) could be more concise without losing critical information.

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

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

Given the complexity (classification, multi-source fan-out, safety checks, no output schema), the description covers all necessary aspects: input handling, response fields (market, analysis, evidence), resolver contract, parent event extraction, news fallback, safety flags, and cancellation rules. It handles edge cases like closed markets, wide spreads, and low-confidence matches thoroughly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds further value by providing examples for 'market' input (slug, URL, question), explaining 'depth' levels ('quick = 2-3 evidence sources, thorough = full fan-out'), and clarifying 'include_raw' behavior and size implications. This extra context raises the score.

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 researches Polymarket bets by pulling Pipeworx data. It specifies the input types (slug, URL, question), the process (resolving, classifying, fanning out), and the output (evidence packet, comparison). This is specific and distinguishes the tool from siblings like 'polymarket_arbitrage' or 'polymarket_edges' by its comprehensive data-gathering approach.

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 provides usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of fan-out per category. However, it does not explicitly mention when NOT to use this tool or list alternatives, missing a small but valuable exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral specifics: what data each entity type pulls (company: 10-K financials with correct fiscal year handling; drug: FAERS adverse events, approval counts, trial counts), sorting by primary metric, and return of paired data with citation URIs. This exceeds annotation coverage 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 paragraph but is front-loaded with example triggers. Every sentence adds value (examples, data details, efficiency claim). It could be slightly more concise by omitting the 'replaces 8-15 sequential lookups' claim, but overall it is efficient and well-structured.

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

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

Given the tool has 2 parameters, no output schema, and read-only annotations, the description covers input behavior (data sources for each type) and output format (paired data, sorted, with citation URIs). It also specifies entity count limits. Minor gaps: no mention of error handling or fallback, but overall sufficiently complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context beyond the schema: it explains the 'type' parameter (company vs drug) with detailed data sources, and the 'values' parameter with examples and constraints (tickers/CIKs for company, drug names). It also clarifies behavior for each type, enhancing understanding.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example queries (e.g., 'X vs Y', 'which is bigger') and explicitly distinguishes from siblings by stating it should be preferred over sequential single-pack lookups, and noting it replaces 8-15 lookups. This differentiates it from tools like entity_profile.

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

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

The description gives explicit instructions on when to use: when the user asks comparisons like 'compare X and Y', 'rank these companies', etc. It includes an imperative 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear context and exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds context about the data source (Brazilian market data) and default currency (BRL), but does not elaborate on other behavioral traits beyond annotations.

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

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

The description is a single, well-structured sentence that is front-loaded with the source and purpose. No unnecessary words.

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

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

Given the tool's simplicity (2 parameters, output schema exists), the description covers purpose, return fields, and data source. It lacks error handling or edge case info but is sufficient for basic usage.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'coin' is a cryptocurrency symbol (e.g., BTC) and 'currency' is target currency with default BRL. However, it does not provide formal parameter descriptions or constraints.

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 provides crypto price quotes for a coin in a target currency, with examples and details on what data is returned (price, 24h change, market cap, volume). This distinguishes it from sibling tools like 'currency' or 'inflation'.

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 getting crypto quotes but does not explicitly state when to use this tool over alternatives (e.g., 'quote' or 'currency'). No exclusions or prerequisites mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by detailing the output (bid/ask rate, daily change) and scope (major pairs against BRL and other currencies). 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?

Single sentence front-loads key info with precise details. 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?

Describes output structure and coverage, but parameter ambiguity reduces completeness. Output schema exists but not relied upon.

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 0%, so description must compensate. It mentions 'pair' but parameter examples show single currency code 'USD', causing ambiguity. Does not fully clarify how to format the parameter.

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 provides currency conversion rates for a pair, with an example (USD-BRL) and specifies the output includes bid/ask rate and daily change. It distinguishes from sibling tools like crypto or inflation.

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

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

No guidance on when to use this tool versus alternatives (e.g., crypto, prime_rate). No explicit when-to-use or when-not-to-use advice.

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

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

Discloses full behavior: parallel tool routing, return format (findings with evidence, confidence, source, citations, gaps, contradictions), depth levels with specific behaviors (gap recovery, iterative hops), time expectations, and that it doesn't invent answers. Exceeds annotation hints with 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?

Although long, every sentence is informative and well-structured. Starts with prerequisites and alternatives, then core explanation, detail on depth levels, and time expectations. No redundant content.

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

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

Given the schema and annotations, the description fully covers the tool's purpose, usage, behavior, parameters, and output. No missing elements; it even explains the return format despite no output schema.

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

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

Schema covers both parameters (100% coverage). Description adds meaning by explaining the enum values (default 'standard', paid 'thorough') and the behavior of each depth level, going beyond the schema's descriptions.

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

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

The description clearly states it performs grounded multi-source research across 1293 structured data sources, using parallel decomposition. It distinguishes itself from sibling tools like ask_pipeworx (single lookup) and for breaking news topics.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not (breaking/news topics, prefer ask_pipeworx). Also notes account requirement and paid plan for 'thorough' depth, providing an alternative tool.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N most relevant tools with full input schemas and examples, ready to call directly. This goes beyond annotations.

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

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

The description is front-loaded with the main purpose and usage. It lists many domains, which may be slightly verbose, but each sentence serves a purpose.

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

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

The description covers purpose, usage, return format (names, descriptions, schemas with examples), and positioning relative to other tools. No output schema exists, but the description adequately describes what the tool returns.

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 does not add new parameter-level information beyond what's in the schema, but schema already includes examples and aliases.

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 the tool finds tools by describing data or task, and lists many specific domains (SEC filings, financials, etc.). It distinguishes from siblings by positioning itself as a meta-tool to call first when exploring available tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: fans out across multiple sources, soft-fail for patents, returns specific fields like CIK, filings, fundamentals, etc. 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 detailed but each sentence adds value. It front-loads with examples and purpose. Slightly long but necessary for completeness; could be trimmed marginally but still effective.

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

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

Given complexity (multiple data sources, no output schema), the description is very complete. It explains return fields, data sources, caveats (patents sunset, name resolution), and even provides output format hints like URIs.

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 both parameters are well-described. The description adds extra meaning: ticker or zero-padded CIK, explicitly states names not supported, and provides examples.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and lists example user queries. It distinguishes from sibling tools by explicitly preferring over chaining single-pack lookups and mentioning resolve_entity for name resolution.

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

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

The description explicitly says when to use (holistic view) and when not (names not supported, use resolve_entity first). It also provides alternatives like chaining single-pack lookups vs. 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?

Description says 'Delete' aligns with destructiveHint=true. Annotations also have idempotentHint=true, which is reasonable for a delete operation. Description adds context about clearing sensitive data, but does not clarify behavior for non-existent keys (idempotent). Still, with annotations doing most of the work, the added value is solid.

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

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

Two concise sentences. The first states purpose, the second provides usage context. No filler; 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 simple tool with one parameter and no output schema, the description covers purpose, usage, pairing, and behavioral implications (via destructiveHint). Annotations fill remaining gaps. Complete information for an AI agent.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. Description echoes this but adds no new constraints or formatting details beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key.' The verb 'Delete' combined with 'memory' as resource is specific. Distinguishes from siblings (remember, recall) by indicating this is the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember and recall', providing clear guidance on tool 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 indicate readOnly and idempotent. The description adds that the tool fetches the page and extracts content, clarifying its read-only network behavior. It doesn't mention potential rate limits or error handling.

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

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

Two concise sentences plus a use-case list. Every sentence adds value: defines purpose, explains process, and gives output format. 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?

The tool has 2 parameters and no output schema. The description explains output as a text blob ready to drop. It covers the core functionality but omits error cases (e.g., unreachable URL). Still fairly complete for a simple 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 baseline is 3. The description adds little beyond schema: it mentions 'key links' but doesn't elaborate on max_links semantics. No additional constraints or examples.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, detailing the process (fetches, extracts, emits) and output format. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than visibility analysis.

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

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

The description lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitor) which imply appropriate contexts. However, it does not explicitly state when not to use or mention alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description adds value by specifying that it returns monthly inflation readings over time and can be for Brazil or other countries. No contradiction with annotations.

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

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

The description is a single sentence that conveys essential information efficiently, but could be better structured for readability. It is front-loaded with the tool name and core functionality.

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 six optional parameters, no required fields, and an output schema exists, the description adequately covers the core purpose and main parameters. However, it lacks detail on sorting, country selection, and how the optional parameters interact, which is necessary for full contextual completeness given the 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It only mentions 'historical flag', 'start', and 'end' dates, leaving out 'country', 'sortBy', and 'sortOrder'. This partial coverage fails to fully clarify the purpose of all six parameters.

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

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

The description clearly states the tool retrieves inflation index series from brapi.dev for Brazil or other countries, specifying the resource (inflation data) and action (returns monthly readings). While it does not explicitly differentiate from sibling tools, the unique name and specific data context make its purpose clear.

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

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

The description implies usage for fetching inflation data with optional parameters, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools among the many sibling financial tools.

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

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

Annotations already indicate readonly, idempotent, and non-destructive behavior. The description adds that it lists only the caller's subscriptions and mentions the optional include_inactive parameter, providing useful context 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 two sentences, efficient, and front-loaded with the verb 'List.' Every sentence adds value without redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It covers purpose, return fields, usage guidance, and the optional parameter behavior.

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

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

Schema coverage is 100% for the single parameter include_inactive, which is well-described in the schema. The description doesn't add new meaning to the parameter beyond what the schema provides, so 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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It effectively distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using this to review monitored items before adding more or to find an ID for cancellation, providing clear when and why to use the tool.

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

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

Annotations indicate it is a write (readOnlyHint false) but no other hints. Description adds rate limits, free usage, no tool-call quota, and that the team reads digests daily. 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?

Five sentences, all necessary, no fluff. Front-loaded with purpose, then usage guidance, then behavioral notes. Efficient and clear.

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

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

Given the tool's simplicity and well-described schema with 100% parameter coverage, the description covers all necessary aspects: purpose, usage, rate limits, behavioral traits. No output schema needed as feedback tools typically return simple acknowledgments.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the type enum in detail, describing the context object's structure, and providing instructions for the message field. Goes beyond what the schema alone conveys.

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

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

The description clearly states the tool sends feedback to the Pipeworx team and enumerates specific use cases: bug, feature request, data gap, praise. It distinguishes itself from sibling tools by being a feedback mechanism, not a query or action 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?

Explicitly states when to use (bug, feature request, etc.) and when not to (e.g., don't paste end-user prompt). Also includes rate limits (5 per identifier per day) and quota information (free, doesn't count against tool-call quota).

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), which goes 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?

Concise and well-structured: first sentence states core function, followed by bullet-like use cases, then data details. No wasted words.

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

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

Despite no output schema, the description fully explains return contents (top tools, packs, volume), caching, and data provenance. Complete for a trending tool.

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

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

Schema coverage is 100% with a single enum parameter. The description adds semantic meaning by explaining the trade-off between short and long windows, enhancing understanding beyond the schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over a window. However, it does not explicitly differentiate from sibling tools like 'discover_tools', though the purpose is distinct.

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

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

Explicitly lists three use cases and explains when to use shorter vs longer windows, providing clear guidance without mentioning alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: the semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slug removal), fill check (theoretical vs realizable edge), and the cross-event search mechanism. 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 front-loaded with a clear summary, then uses bullet-like sections for modes, semantic anchor, partition filter, and fill check. While it is somewhat verbose, every sentence adds value for the complex functionality. A slightly tighter structure could improve conciseness.

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

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

Despite lacking an output schema, the description explicitly details the response structure: opportunities array with fields and the partition_check object in event mode. The fill check behavior is also described. For a complex arbitrage tool, this provides sufficient completeness for an agent to understand inputs and outputs.

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

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

Schema description coverage is 100%, and the description adds substantial meaning: it explains how event mode checks ordering and partition sum, and how topic mode searches across events and flattens markets. Examples of slug formats and topic questions are provided, going far 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 starts with a clear, specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools (e.g., polymarket_edges, polymarket_fill_risk) by detailing its unique approach and modes.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and mentions polymarket_fill_risk for custom sizing, but does not provide explicit when-not-to-use 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 declare readOnlyHint, idempotent, openWorld, and not destructive. The description adds extensive behavioral context: caching at 1h, detailed model family mechanics, slippage assumptions, knob effects, and diagnostic output. 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 very long and detailed, almost a mini-manual. While every sentence adds value, the length may overwhelm agents for quick selection. A more structured, front-loaded summary would improve conciseness.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, fed_candidates, diagnostics) and why segments may be empty. Combined with detailed parameter semantics and behavioral transparency, completeness is high.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant context beyond schema, such as explaining slippage_pp costs, the purpose of min_partition_leg_kelly for partition arbs, and details on min_liquidity and max_spread_pp as tradeable-edge filters.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It specifies three model segments, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool for discovery, how the three segments work, and even includes diagnostics for why segments may be empty. However, it doesn't explicitly contrast with siblings like polymarket_arbitrage, so it's clear but not exhaustive.

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

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

Annotations declare readOnlyHint and idempotentHint; description adds rich behavioral context: explains response structure (tracked, expired, snapshot_dates), meaning of negative edge values, and computation details (daily closes, decay from |edge_pp_net|). No contradictions. Exceeds annotation baseline.

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

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

Description is well-structured: purpose, response fields in detail, limitations. Every sentence adds value without redundancy. Efficient use of length for 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 no output schema, description thoroughly explains the return values (tracked, expired, snapshot_dates with subfields) and limitations (TTL, no intraday). Fully sufficient for an agent to understand the tool's output and constraints. No gaps.

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

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

Schema coverage is 100%; description adds default values (days=14, window='1wk'), clamping info (days 2-30), and explains window as 'snapshot family' with examples. Adds meaning beyond schema descriptions.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and shrinkage. It distinguishes from sibling tools like polymarket_edges by focusing on historical trends. The verb+resource combination is specific and unambiguous.

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

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

Description explains the use case by contrasting fresh vs old edges, implying when to use this tool. It also provides limits (history depth TTL, no intraday) but does not explicitly exclude alternatives like polymarket_edges for current edges. Somewhat clear, but could be more direct.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, and the description consistently presents a non-mutating check operation. It adds substantial behavioral context beyond annotations: it details what the tool does internally ('walks the ladder'), lists specific return fields, and warns about risks like thin books and partial fills, which is critical for an agent to understand the tool's 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 structured with clear sections (SINGLE-MARKET, BASKET) and bullet-style lists of return fields. While it is lengthy, every sentence serves a purpose given the tool's complexity. It could be slightly more concise, but the structure aids readability and the verbosity is justified by the need to explain two modes and many outputs.

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

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

With no output schema, the description fully documents expected return fields for both modes, including edge cases like 'thin_legs' and 'forced_directional_risk'. All 4 input parameters are thoroughly explained, including their interactions (requires one of market or event). The description is complete for an agent to correctly invoke the tool 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?

Schema description coverage is 100%, yet the description adds significant extra meaning. For 'size_usd', it clarifies dual interpretation (single-market: max spend/target proceeds vs. basket: settlement notional per leg). For 'side', it explains defaults and auto behavior. For 'market' and 'event', it clearly separates the two modes. This goes well beyond what the schema alone provides.

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

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

The description specifies a 'realizable-vs-theoretical edge check against live CLOB order-book depth', clearly identifying the verb ('check') and resource ('fill risk'). It distinguishes two distinct modes (single-market and basket), and the purpose is differentiated from sibling tools like polymarket_arbitrage and polymarket_edges by being explicitly a pre-trade risk assessment.

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

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

The description explicitly instructs to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the consequences of not using it (partial basket fills convert an arb into an unhedged directional position), providing clear when-to-use and when-not-to-use guidance.

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

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

Adds detailed behavioral context beyond annotations: explains compatibility_warning triggers, temporal_alignment field, and skipped_cross_type/subtype counters. No contradiction with annotations (readOnlyHint, idempotentHint are consistent).

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

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

Description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds pertinent information. Could be slightly more terse, but no wasteful content.

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

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

Given the tool's complexity (3 optional params, no output schema, multiple warning/mode conditions), the description is remarkably complete: it explains return structure, edge cases, and field semantics, leaving minimal ambiguity for an agent.

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

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

Schema coverage is 100% and parameters are well-described, but the description adds value by explaining how topic maps to events and how explicit tickers override, plus provides examples. Slight redundancy with schema but still useful.

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

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

Clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. Differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by being venue-specific.

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 describes two usage modes (topic shortcuts vs. explicit tickers), and warns that most pre-mapped topics currently return compatibility_warning rather than tradeable spreads, helping agents avoid false expectations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety. The description adds that the tool returns 'rate readings over time' and explains the role of historical flag and date range. No contradictions.

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

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

The description is a single, efficient sentence that conveys the core functionality without unnecessary words.

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

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

Given 6 optional parameters and no schema descriptions, the description is incomplete. It does not explain the effect of all parameters or the output structure (though an output schema exists). It provides the essential idea but lacks detail for effective 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?

With 0% schema description coverage, the description must compensate. It only mentions 'historical flag' and 'start/end date range', leaving parameters like 'sortBy', 'sortOrder', and 'country' inadequately explained beyond their names. The country is vaguely implied by 'for Brazil or other countries'.

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

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

The description clearly states it retrieves prime/benchmark interest rate series for Brazil or other countries, which is a specific resource. However, it does not explicitly distinguish from sibling tools like 'crypto' or 'currency', though the name and context make the distinction clear.

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

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

The description gives no guidance on when to use this tool versus alternatives. It mentions 'for Brazil or other countries' but does not specify when to prefer this over other financial data tools like 'inflation' or 'crypto'.

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 destructiveHint=false, so the description adds moderate value by specifying the data source (brapi.dev) and optional features. However, it does not discuss rate limits, data freshness, or other behavioral traits beyond what annotations cover.

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

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

The description is a single, information-dense sentence that front-loads the source and purpose. It uses an example and clearly lists data types, but it could be slightly more structured with bullet points for readability.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers the main functionality and optional parameters adequately, though it lacks edge cases or limitations. Overall, it provides sufficient context for a well-annotated 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?

With 0% schema description coverage, the description compensates by mentioning tickers (comma-separated) and optional OHLC history and fundamental data, supported by examples. However, it omits the 'modules' parameter and does not describe each parameter in detail, leaving some ambiguity.

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: providing live quotes for Brazilian market tickers (comma-separated format) with price, change, volume, and optional OHLC history and fundamental data. It specifies the data source (brapi.dev) and example tickers (PETR4,VALE3), making it distinct from sibling tools like quote_list.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for Brazilian tickers but does not mention when not to use it or provide comparisons with siblings such as quote_list or crypto.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'paginated directory' and mentions optional filters, which provides some behavioral context beyond annotations, but not significantly more than what annotations convey.

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

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

The description is a single sentence, front-loaded with the data source and purpose, with no redundant information. Every word adds value.

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

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

The description covers the core purpose, main filters, and pagination. With an output schema present, return values are not needed. The parameter count and optionality are reasonable, and the description sufficiently frames the tool's use case.

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

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

With 0% schema coverage, the description must compensate. It mentions 'text search, sector filter, and sort', corresponding to 'search', 'sector', 'sortBy', 'sortOrder', and 'paginated' implies 'page' and 'limit'. However, 'type' is not described, and parameter specifics (e.g., valid values for 'type') are missing.

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

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

The description clearly states the verb (discover/enumerate) and resource (Brazilian market tickers: stocks, ETFs, FIIs) with specific context (B3-listed symbols). It distinguishes itself from sibling tools like 'quote' and 'crypto' by specifying its scope.

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

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

The description gives a direct usage context ('Use to discover or enumerate B3-listed symbols'), implying when to use. However, it does not explicitly mention when not to use or provide alternatives, though the sibling list and tool name hint at alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds useful scoping context (scoped to anonymous IP, BYO key hash, or account ID) without contradicting 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 concise sentences, front-loaded with the action, and every sentence adds critical information without redundancy.

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

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

For a simple read tool with one optional parameter, rich annotations, and no output schema, the description fully covers behavior, scoping, and integration with sibling tools.

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 description explains behavior beyond the schema: omitting the key lists all saved keys. Schema coverage is 100% and description adds meaningful usage context.

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

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

The description uses specific verbs 'Retrieve' and 'list', specifies the resource 'a value previously saved via remember', and distinguishes from siblings like 'remember' and 'forget' by mentioning them.

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

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

It explicitly states when to use the tool (to look up stored context without re-deriving) and mentions pairing with remember and forget, but does not explicitly state when not to use it.

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

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

The description states that setting mark_read:true flags returned events as read, modifying state. However, the annotation declares readOnlyHint=true, indicating no side effects. This is a direct contradiction, making the description misleading. The description adds behavioral context, but the contradiction invalidates its reliability.

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 with two sentences, each earning its place. The first sentence states purpose and output, the second explains parameters and usage. Information is front-loaded, 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 simple read tool with 5 optional parameters, the description covers the typical use cases: polling, filtering by type/since, marking read, and unread only. It also provides an alternative endpoint. Without an output schema, it still describes return fields adequately.

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

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

Schema coverage is 100%, and the description adds substantial meaning beyond the schema: it provides examples (type 'sec_8k'), clarifies the since parameter, explains the effect of mark_read on subsequent calls, and describes the return fields (source, citation_uri, raw payload). This enriches the schema significantly.

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 specifies the resource (fired events, subscription feed) and the verb (pull/returns). It distinguishes from sibling tools like 'list_subscriptions' by focusing on 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 provides clear context on when to use the tool (e.g., 'Polls work fine') and offers an alternative (HTTP endpoint). It explains filtering options (type, since, mark_read, unread_only). However, it does not explicitly state when not to use it or compare to other tools beyond the HTTP endpoint.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: fans out to SEC EDGAR, GDELT→GNews (with fallback rationale), USPTO (with sunset note and soft-fail behavior). It also describes the return structure (grouped changes, total count, citation URIs). No contradictions with annotations.

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

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

The description is a single coherent paragraph that effectively front-loads purpose, then details behavior, parameters, and sibling differentiation. While clear, it could be slightly more structured with bullet points or separate sections for parameter details and source behaviors.

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

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

Given the tool's complexity (multiple sources, fallback logic, parameter formats) and absence of output schema, the description is remarkably complete. It explains what is returned (structured changes, count, URIs), highlights limitations (USPTO sunset), and provides parameter examples. No critical gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains 'since' as window start with examples and typical monitoring values, clarifies 'type' is limited to 'company', and specifies 'value' accepts ticker or CIK. This enriches the schema definitions with practical usage context.

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

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

The description starts with clear user intents ('What's new with X', 'latest on Y') and states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes from sibling tool 'entity_profile', making the purpose unique and well-defined.

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

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

The description lists when to use the tool (news/updates queries) and explicitly tells when to use 'entity_profile' instead ('static profile regardless of window'). It provides parameter guidance: acceptable formats for 'since' (ISO date or relative shorthand), typical values like '30d', and explains fallback behavior between GDELT and GNews, including rate limiting. This gives clear decision 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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are consistent. The description adds behavioral context: storage scoped by identifier, persistent vs 24-hour memory. No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words. Clearly structured: what, when, details.

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

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

Given the simplicity of the tool (2 params, no output schema), the description fully informs an agent. Sibling tools are mentioned, and annotations cover behavioral hints.

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

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

Schema covers 100% of parameters with descriptions. The description adds contextual examples of key-value pairs and underlying scope, providing value beyond schema.

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

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

The description clearly states the tool saves data for reuse, with specific examples and scope (across conversation/sessions). It distinguishes from siblings recall and forget by naming them.

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

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

Explicitly says when to use ('discover something worth carrying forward') and pairs with recall/forget. However, it does not explicitly state when not to use the tool, though context implies it.

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

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

Annotations already indicate readOnly, idempotent, openWorld. The description adds that each call cascades through multiple lookup endpoints and replaces 2-3 manual lookups, providing valuable context beyond annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core action and then efficiently covers types and internal behavior. It could be slightly more concise, but it's effective.

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

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

Given no output schema, the description fully explains what is returned for each entity type, the internal cascade, and the overall value. It leaves no ambiguity about the tool's function or outputs.

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 description adds significant meaning beyond the schema: for each type it details the return fields (e.g., ticker + CIK + company_name for company; RxCUI + ingredient + brand for drug) and notes auto-disambiguation. This greatly aids correct parameter understanding.

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

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

The description clearly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifier'. It lists example queries and specifies supported types (company, drug) with concrete outputs, making the action unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not explicitly mention when not to use it, but the directive is strong enough to differentiate from 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 declare readOnlyHint and idempotentHint true; the description adds value by explaining the tool is a wrapper that probes each entity with ai_visibility_check and describes the output structure, but does not explicitly discuss potential variability 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 two sentences, front-loaded with the main action, and every sentence serves a purpose—no wasted words.

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

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

Given the annotations and full schema coverage, the description adequately covers purpose, process, output structure, and use case. It lacks edge-case handling but 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% with all parameters described. The description adds marginal value by clarifying the first entity as subject, but does not substantially 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 compares AI visibility across multiple entities side-by-side, uses specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces', and distinguishes from sibling tool ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description provides clear context for use (competitive AI-marketing audits) and implies alternatives via mention of single-entity probing, but lacks explicit when-not guidance or direct naming of alternative tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This explains potential delays and error handling, which is crucial for an agent.

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 yet packed with essential information. It front-loads the core purpose and then efficiently covers scope, return structure, and caveats. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (composite, multiple sources, partial failures) and the lack of an output schema, the description thoroughly explains what the tool returns: 'a summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions.' It also covers limitations and error handling.

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

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

Schema coverage is 100% with both parameters described. The description adds extra context: 'Scoped packages (e.g. "@types/node") are accepted.' This goes beyond the schema. However, the description does not repeat or expand on the version default behavior already in the schema.

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

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

The description clearly states the tool's purpose: 'Composite "should I add this npm package to my project" check in ONE call'. It specifies the data sources (deps.dev and bundlephobia) and what aspects are checked (license, advisories, version history, bundle size, ESM/tree-shake support). It also distinguishes itself from sibling tools by noting the NPM-only scope and directing to deps.dev:version for other ecosystems.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear when-to-use guidance. It also explains when not to use it: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' However, it does not explicitly name alternative tools from the sibling list for those cases.

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

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

Discloses embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and output structure (passages with offsets and scores). Adds significant value beyond annotations that only declare idempotent/read-only.

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?

First sentence gives core purpose, then benefits, then sibling pairing, then technical details. Every sentence is informative; no redundancy. Efficient for 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?

Covers return format, technical limitations (200K chars, truncation flag), and integration with sibling tool. No output schema exists, so description carries full burden and succeeds.

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. Description adds examples for query and confirms limit default and text cap, but does not substantially extend beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs semantic search inside a fetched record, with examples (SEC 10-K body, article) and benefit (saves context, returns passages with offsets). It distinguishes from sibling tools like ask_pipeworx_grounded by specifying its role in the workflow.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. While it doesn't list when not to use, the context implies appropriate usage.

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

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

Adds significant context beyond annotations: delivery channel details, webhook signing, SMS cap, phone verification requirement. However, idempotentHint=true contradicts description's implication that each call creates a new subscription id.

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

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

Well-structured with main purpose first, then requirements, types, delivery. Each section is informative. Slightly verbose but efficient for 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?

Covers authentication, types, delivery, and return value (subscription id). Missing error conditions (e.g., OAuth missing, phone not verified, duplicate subscription). Adequate but not 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%, but description adds rich examples for each type's params and delivery options, including webhook HMAC details and SMS limits. Adds substantial meaning beyond schema.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb (create) and resource (subscription). Returns id. Distinct from siblings like list_subscriptions (list) and unsubscribe (remove).

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 requires Pipeworx OAuth account, and describes supported subscription types with examples. No explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: it's an onboarding tool, returns category-bucketed examples with tool+argument shapes, no 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?

Description is front-loaded with alternative phrasings and structured with categories. It is moderately concise, though a few sentences could be trimmed 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 read-only onboarding tool with no output schema, the description fully explains the output format, usage context, and parameter behavior. No additional info needed.

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

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

Schema coverage is 100% with a clear description of the 'topic' parameter. Description adds value by explaining the effect of omitting topic vs passing it, but schema already covers the parameter semantics.

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

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

The description uses specific verbs and resources: 'returns category-bucketed example questions' and 'shows exact tool + argument shape'. It distinguishes from siblings like 'discover_tools' by positioning itself as the onboarding 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 to use this first when unsure what Pipeworx can do, and describes when to pass 'topic'. Could better contrast with similar tools like 'discover_tools'.

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

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

The description adds significant context beyond the annotations: ownership enforcement (only cancel own subscriptions) and that the row is deactivated, not deleted, preserving history. Annotations confirm non-destructive, idempotent behavior 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 three sentences, each adding essential information: purpose, ownership, and side effects. No wasted words, and the purpose is stated first.

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 one parameter, no output schema, and is straightforward, the description covers all necessary aspects: purpose, constraints, and data impact. It is fully complete for its complexity.

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

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

With 100% schema coverage, the schema already describes the 'id' parameter. The description does not add extra meaning beyond what the schema provides, meeting the baseline expectation.

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 'Cancel a subscription by id', specifying the verb, resource, and method. This distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description implies when to use (to unsubscribe) and notes ownership enforcement, but does not explicitly discuss when not to use or mention alternatives. However, for a simple tool like this, guidance is adequate.

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

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

Annotations already indicate readonly, open-world, and idempotent behavior. The description goes beyond by detailing the specific data sources (SEC EDGAR + XBRL), the exact return verdict types (confirmed, refuted, etc.), structured form, citation format, and percent delta. 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 information-dense but front-loads key examples and usage context. While slightly verbose, every sentence adds value. Could be trimmed slightly, but overall well-structured.

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

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

Despite lacking an output schema, the description fully explains the return types (verdict, structured form, value with citation, percent delta), the domain coverage, and the efficiency benefit (replaces 4-6 calls). The description is complete for an agent to understand tool capabilities and results.

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

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

The single 'claim' parameter has 100% schema description coverage with examples. The tool description does not add additional parameter details beyond the schema, so baseline 3 is appropriate.

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

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

The description starts with natural-language examples and explicitly states it is for 'natural-language claim verification against authoritative sources'. It specifies the domain (company-financial claims) and contrasts with siblings by noting it replaces 4-6 sequential calls, making the purpose very clear and distinctive.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines the domain limitations. It does not provide explicit when-not-to-use instructions or list alternatives, but the context is sufficient for appropriate tool selection among siblings.

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