Ibge Br

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds behavioral context: returns time series keyed by period and mentions auto-encoding of brackets in localities. 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-load the purpose, then provide examples and return format. No redundancy, 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?

Given full schema coverage and absence of output schema, the description is complete: explains all parameters, provides examples, and states return type (time series keyed by period).

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 and examples. The description adds further value by providing concrete examples (e.g., aggregate 1737 variable 63 for IPCA) and linking to list_aggregates, enhancing understanding beyond the schema.

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

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

The description clearly states the tool pulls official IBGE/SIDRA statistical series (inflation, GDP, population). It uses specific verbs and resource references, and distinguishes itself from siblings like list_aggregates by focusing on data retrieval.

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 common examples and directs users to list_aggregates for discovering aggregate IDs, offering clear usage context. However, it does not explicitly mention when not to use this tool or suggest alternatives beyond list_aggregates.

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, openWorldHint, idempotentHint true, destructiveHint false. The description adds that the default model is free, requires a BYO key for Anthropic, and details the return structure (per-model and combined). 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 paragraph that efficiently conveys purpose, usage, and return format. It is not overly verbose, but could be slightly more structured (e.g., bullet points) for easier scanning.

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 moderate complexity, no output schema, and 100% parameter coverage, the description provides complete context: it explains the scoring range, return fields (score, confidence, signals, raw_response), and combined view. 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 description coverage is 100%; each parameter has a description. The tool description adds context beyond schema, e.g., default model name, free usage, and that _apiKey is passed directly to Anthropic. This enriches 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 probes LLMs for knowledge about an entity and provides a visibility score (0-100) per model. It specifies the default model and the ability to add Anthropic. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general visibility rather than just competitors.

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 outlines use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the default vs. Anthropic model. However, it does not explicitly contrast with the sibling tool 'scan_competitor_ai_presence' for overlapping scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context such as routing to 5,358 tools, filling arguments, returning structured answers with stable citation URIs, and being a fast, tier-universal default entry point.

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

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

The description is long but well-structured, front-loaded with 'PREFER OVER WEB SEARCH' and clearly organized sections. It includes many examples and alternatives; while each sentence earns its place, it could be trimmed without losing essential guidance.

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

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

For a complex tool with no output schema, the description covers purpose, scope, usage guidance, examples, sibling differentiation, routing behavior, and citations—arguably everything needed for correct invocation. It also explains the 'step up' escalation path, making the context 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% but only describes aliases and 'natural language' for the question parameter. The description compensates by providing rich guidance on what to ask: domains (SEC, FDA, FRED, patents, etc.), signal phrases ('what is', 'look up', 'find'), and concrete examples ('current US unemployment rate', 'Apple's latest 10-K'). This far exceeds the literal 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: it routes factual questions to the appropriate source among 5,358 tools and returns structured answers with pipeworx:// citations. It distinguishes itself from siblings by positioning itself as the default entry point and explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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

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

It provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...') and when-not-to-use with named alternatives ('Step up only when needed: for ... use ask_pipeworx_grounded; for a broad/multi-part ... use deep_research'). It even clarifies breaking-news routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds important context: that this is an experimental edge, that no candidate is currently active so behavior matches ask_pipeworx exactly, and that it is a full working router (not a fallback). This goes beyond annotations without contradicting them.

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

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

The description is concise but information-dense, front-loaded with the core definition, and every sentence contributes context (beta status, current state, usage instruction, fallback status). No waste.

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

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

The description covers purpose, operational state, relationship to the stable sibling, and usage. It is sufficient for a beta variant with no output schema, though it could briefly mention what happens when a candidate is under test (behavior changes), but the statement about 'enabled live' implies that.

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 alias descriptions, so the description has little added work. It does mention that arguments are identical to ask_pipeworx, reinforcing the schema, but provides no deeper semantics. Baseline 3 for high coverage.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with an identical universal router, explicitly naming the sibling it mirrors. It distinguishes itself by describing the live candidate routing improvements and current inactive state, so the purpose is unambiguous and well-scoped.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable alternative (ask_pipeworx) and explains the comparison process, giving the agent a clear decision framework.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals rich behavioral traits: refusal reasons (not_in_source, no_tool_match, etc.), evidence requirement, and the extra LLM call cost. No contradiction with annotations.

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

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

Four dense sentences, each adding unique value: definition, mechanics/return format, usage context, and cost comparison. Information is front-loaded with the key differentiator in the first sentence, and there is no redundant text.

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

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

With no output schema, the description fully specifies the return structure including success fields (answer, evidence, confidence, source, fetched_at) and refusal reasons. It also explains the tool's internal routing and behavior when data doesn't directly answer, making it self-sufficient.

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

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

Schema coverage is 100% with detailed alias descriptions, meeting the baseline. The description adds no parameter-specific syntax or constraints, though it does contextualize what kind of questions are appropriate (high-stakes) at the tool level rather than parameter level.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (extracts answers) and resource (tool results). It distinguishes itself from sibling 'ask_pipeworx' by explicitly contrasting its grounded extraction and refusal behavior.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' Names the alternative (ask_pipeworx) and explains the cost trade-off.

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?

Extensively describes behaviors beyond annotations: fan-out patterns, response shapes, resolver contract, parent event extractor, news fallback, safety mechanisms, resolution-rule risk. No contradictions with annotations (readOnlyHint etc. 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?

The description is long but well-structured with clear headings and examples. Every section provides essential information for a complex tool. Some redundancy could be trimmed, but it is appropriately detailed for the tool's depth.

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

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

Given the tool's complexity, 3 parameters, no output schema, and many siblings, the description is remarkably complete. Covers edge cases, error states, response format, and practical usage guidance.

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 good parameter descriptions. The tool description adds significant context about how parameters affect behavior (e.g., depth controls fan-out, include_raw controls verbosity), which goes 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 verb 'Research' and the resource 'Polymarket bet', and explains how it pulls Pipeworx data in one call. It is specific and distinct in purpose, but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides clear context but does not include when NOT to use or mention 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 indicate read-only, idempotent, open-world behavior. Description adds specifics: for companies, it pulls latest 10-K data with correct off-calendar handling; for drugs, FAERS counts. Results sorted by primary metric. 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 dense without being overly long. Examples are front-loaded, but some detail (e.g., off-calendar) could be more concise. Still efficient for the information conveyed.

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 format (paired data + citation URIs) and data sources. It covers all necessary context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by explaining the data sources (SEC EDGAR, FAERS) and the meaning of the 'type' parameter for sorting. A slight deduction for redundancy with schema.

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

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

The description uses specific verb+resource (compare entities, side-by-side comparison) and provides concrete example queries. It clearly distinguishes from siblings like entity_profile by emphasizing efficiency over sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives clear when-to-use examples. The description covers both entity types, making usage unambiguous.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond this by adding account/auth prerequisites (including paid 'thorough' depth), latency expectations (15-90s), gap[] handling ('never invented'), semantic excerpting of large records, hop-based iteration, contradictions[] scanning, and the caveat that news topics yield empty gaps. This is exceptionally transparent.

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

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

The description is long but every sentence earns its place, covering auth, function, alternatives, depth modes, output structure, latency, and limitations. It is front-loaded with the critical account requirement and core purpose. While a bulleted layout would improve scannability, the compact prose is justifiable for a tool of this 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?

Despite no output schema, the description fully enumerates what the findings packet contains (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]). It covers input expectations, depth semantics, performance trade-offs, limitations, and sibling-tool relationships. No significant contextual gaps remain for an agent to select and invoke this tool correctly.

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

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

The input schema already documents both parameters fully: question is described as broad/multi-part natural language, and depth has a detailed enum description covering facet counts, hops, and contradictions scanning. The description largely restates this depth behavior and adds the paid-plan constraint, which is useful but not a substantial new parameter-semantics contribution. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description precisely states that deep_research performs multi-source research across 1,395 structured data sources, decomposes questions into facets, routes to 5,358 tools in parallel, and returns an evidence-backed findings packet. It also explicitly contrasts with open-web search ('this is NOT open-web search') and differentiates from ask_pipeworx, making its unique function 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?

Provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, while single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx, and unsigned-in users should use ask_pipeworx. It names the alternative tool directly and gives clear exclusion conditions.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint=false. The description adds valuable context: it returns top-N tools with names, descriptions, and full input schemas including curated examples, and states that results are ready to call without a second schema lookup. 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 purpose, then provides a comprehensive list of example topics and behavior. It is slightly lengthy but every sentence serves a purpose, and the examples are informative for an agent. Could be trimmed but remains efficient.

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

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

Given no output schema, the description adequately explains what is returned (top-N tools with schemas and examples). It covers when to use, behavior, and constraints (max 50 results). The complexity is moderate, and the description provides sufficient context for an agent to invoke it correctly.

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

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

Schema description coverage is 100% across all 6 parameters, each already well-described. The description does not add new semantic detail beyond the schema; it mentions aliases which are already documented. 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 states 'Find tools by describing the data or task', providing a specific verb ('discover') and resource ('tools'). It clearly distinguishes from sibling tools, which are domain-specific data tools, by positioning discover_tools as a meta-selection 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 advises 'Call this FIRST when you have many tools available and want to see the option set', giving clear context for when to use it. It does not list exclusions, but the 'first' directive implicitly guides against calling when the target tool is already known.

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 safe, read-only, idempotent behavior. The description adds valuable context: fans out across multiple sources, mentions patents soft-fail due to USPTO sunset, and details return structure. 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 lengthy but well-structured, front-loading with examples. Every sentence adds value, though it could be slightly more concise. Still highly effective.

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

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

No output schema exists, but the description comprehensively explains return fields (CIK, filings, fundamentals, patents, news, LEI) and notes limitations like patent soft-fail. Covers prerequisites and edge cases, making it fully complete for a read-only tool.

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

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

Schema has 100% parameter description coverage. The description adds practical guidance: value accepts ticker or zero-padded CIK, and type is restricted to 'company'. This enriches meaning 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 provides a full cross-source profile of a US public company, with example queries like 'tell me about X' and specific return fields. It distinguishes itself from chaining single-pack lookups and references resolve_entity for names, showing differentiation from siblings.

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

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

Explicitly states when to use: for holistic views and always prefer over chaining single-pack lookups. Also specifies when not to use: names not supported, directing to resolve_entity first. This provides clear context for 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 provide destructiveHint=true and idempotentHint=true. Description reiterates 'delete' and 'clear sensitive data' but adds no behavioral details beyond what annotations convey (e.g., behavior if key missing).

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

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

Two sentences, zero wasted words. Core action in first sentence, usage guidance in second. Front-loaded and 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 (1 param, no output schema) with good annotations. Description covers purpose, usage, and sibling pairing – 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?

Only parameter 'key' with schema description 'Memory key to delete' – schema coverage 100%. Description adds no additional 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 specifies 'Delete a previously stored memory by key' – a specific verb-resource pair. Distinguishes from siblings 'remember' and 'recall' which are for storage and retrieval.

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 (stale context, task done, clear sensitive data) and mentions sibling tools. Does not provide explicit when-not-to-use scenarios, 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 idempotent and non-destructive behavior. The description adds that it fetches the page and extracts content, but does not disclose potential failures (e.g., access restrictions) or rate limits. It adds value but not significantly beyond annotations.

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

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

Three sentences in a logical order: purpose, process, use cases. Front-loaded with the action verb. No superfluous information.

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

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

The tool is simple with two parameters and no output schema. The description explains the output ('single text blob') and the process, making it complete for an agent to understand invocation and result.

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 (url and max_links) with descriptions, achieving 100% coverage. The description does not add additional semantic meaning beyond what the schema provides, hence baseline 3.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the purpose ('for any URL so AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools, none of which perform this specific function.

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

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

Explicitly lists use cases (client site indexing, own project drafting, competitor auditing) but does not provide when-not-to-use guidance or alternatives. Since no sibling tool overlaps, the absence of exclusions is acceptable but still leaves a gap for edge 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?

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the agent knows it's safe. The description adds that results are grouped by subject and allows discovery, but doesn't add significant behavioral details like pagination or output format.

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

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

Two sentences, no wasted words, purpose front-loaded. Highly concise.

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

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

For a simple browse/discovery tool with one parameter and full annotation coverage, the description adequately covers purpose, usage, and outcome (discovering IDs). Lacks output structure details but functional given context.

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

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

Schema coverage is 100% with the acronym parameter description. The description restates that it's optional and for filtering, adding no new semantic meaning beyond the schema.

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

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

The description clearly states the tool browses a catalog of IBGE/SIDRA aggregate tables grouped by subject, with the purpose of discovering aggregate IDs to pass to aggregated_data. This distinguishes it from the sibling aggregated_data 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 use case: discover aggregate IDs for aggregated_data. Also mentions optional filtering by acronym. While not exhaustive about when not to use, the guidance is clear and sufficient for this role.

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, and destructiveHint. The description adds return format and examples but no additional behavioral traits (e.g., pagination, rate limits). Since annotations cover safety, the description adds modest value beyond them.

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

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

The description is two sentences, front-loaded with the main action, and includes a helpful example. No extraneous words. Highly concise and 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's simplicity (one parameter, no output schema), the description fully covers what the tool does and returns. No additional context is necessary.

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

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

Schema description coverage is 100%, providing clear parameter description. The description adds an example ('uf="RJ"') but does not significantly enhance meaning 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?

The description clearly states the verb 'List', resource 'municipalities', and constraint 'for a given state (UF)'. It specifies the return values (7-digit IBGE id and name) and distinguishes from siblings like list_states and lookup_municipality.

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 does not explicitly state when to use this tool versus alternatives. The example and mention of UF imply usage, but no when-not or alternative tools are mentioned. Includes a comparison threshold but not full 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specific output details (fields and example) and confirms the fixed set of 27 states, complementing annotations without contradiction.

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

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

Two sentences, front-loaded with core action and output, followed by usage hint. No redundant 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 simple tool (one optional parameter, no output schema), the description fully explains what it returns and its purpose. It is complete for an agent to use correctly.

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

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

Schema already describes the single parameter 'orderBy' with 100% coverage. The description does not add extra parameter semantics beyond what the schema provides.

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

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

The description clearly states the verb 'list' and resource 'states', specifying it lists all 27 Brazilian states with fields (id, sigla, name, region) and gives an example. It distinguishes itself from sibling tools like list_municipalities.

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 indicates it is useful for resolving state names/codes before querying municipalities or regional data, providing context. However, it does not explicitly mention when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety. It adds behavioral context by specifying that the tool returns active subscriptions of the caller and lists the exact fields in the response.

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

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

The description is two sentences long, with the first specifying functionality and output, and the second providing usage guidance. No extraneous information, making it highly concise 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 simple nature of the tool (one optional parameter, no output schema), the description is complete. It states what is returned, the caller scope, and usage context. Minor gap: no mention of pagination or limits, but not necessarily 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 the parameter 'include_inactive' fully described in the input schema. The description adds no additional information about parameters, so it meets the baseline of 3 for high coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It differentiates from sibling tools like subscribe and unsubscribe by mentioning using it to review subscriptions before adding more or to find an id to cancel.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use this tool. While it doesn't explicitly state when not to use it, the positive guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context by specifying the return includes 'full hierarchy (micro/mesoregion, state, region)', which goes beyond the schema. No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core action. The example is placed efficiently, and 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 lookup tool with one parameter and no output schema, the description covers purpose, input format, and return structure. A minor gap is the absence of error handling (e.g., what happens if code is invalid), but annotations with openWorldHint partially mitigate this. Overall, it is nearly complete for the tool's complexity.

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

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

The input schema already provides a full description of the 'code' parameter (7-digit IBGE municipality code with examples). The description repeats this example but does not add new semantic depth beyond that. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states 'look up a single municipality by its 7-digit IBGE code', specifying the verb, resource, and scope. It distinguishes from siblings like 'list_municipalities' by focusing on a single entity, and provides an example that clarifies the input format.

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 implicitly indicates when to use this tool (to look up a single municipality) but does not explicitly state when not to use it or mention alternatives. The sibling context, including 'list_municipalities', suggests the broader use case, but the description could be improved by adding an explicit alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds temporal scope ('since 1930') and special behavior for 'ranking' parameter, which goes beyond annotations without contradiction.

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

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

Two sentences, 28 words, front-loaded with purpose and examples. Every word contributes meaning with no redundancy.

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

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

No output schema exists, but the description indicates the return type (registration frequency by decade or top names). While further detail on response format would be helpful, the tool's simplicity makes this adequate.

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

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

Schema coverage is 100% with descriptions for all 4 parameters, including the special 'ranking' value. The description restates these with examples but does not add new semantic meaning beyond the schema.

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

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

The description clearly states it provides Brazilian census name statistics, specifying the verb 'get' (implied) and resource 'registration frequency' or 'top names'. It distinguishes itself from sibling tools by being specific to name frequency lookup.

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

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

The description gives clear usage with examples ('name="maria"', 'name="ranking"') and optional filters (sex, state, decade). It lacks explicit when-not conditions but is sufficiently specific for typical use.

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

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

Annotations are all false, so no contradictions. The description discloses that writes are involved (not read-only), rate-limited, and free. Adds context about how feedback is processed (digests, roadmap impact) beyond what annotations provide.

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

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

Description is a single paragraph but well-structured, front-loading purpose, then usage, then constraints. Every sentence adds value; 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?

Comprehensive for a feedback tool: covers purpose, when/how to use, parameter details, constraints (rate-limit, free), and output expectations (team reads digests). No output schema 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%, but description adds significant value by explaining enum values in detail and providing guidance on message content (be specific, avoid pasting end-user prompts, 1-2 sentences typical).

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, with specific categories (bug, feature, data_gap, praise). It distinguishes itself from sibling tools which are primarily data retrieval or analysis tools.

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

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

Explicitly outlines when to use the tool for bugs, feature requests, data gaps, or praise. Also provides a clear exclusion ('don't paste the end-user's prompt') and mentions rate limits (5 per identifier per day) and free usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: self-aggregating signal, derived from CF analytics-engine, no PII, and caching (5min-1h). This goes well beyond the annotations.

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

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

The description is a clear paragraph with bullet points for use cases. It is informative without being excessively long, though it could be slightly more concise. No wasted sentences.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers what the tool returns, its caching behavior, and use cases. Nothing is missing for an agent to use it correctly.

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

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

With 100% schema coverage and a single parameter (window), the description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the trade-offs between enum values, enhancing 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 returns 'top tools, top packs, and total call volume' over a window, with a specific verb ('return') and resource ('trending usage on Pipeworx'). It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on aggregate usage from other AI agents.

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

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

Three explicit use cases are given: discovering hot data sources, confirming canonical tools, and checking use-case alignment. While it doesn't explicitly say when not to use, the guidelines are clear and help an agent decide when this tool is appropriate.

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 and idempotentHint both true, which the description aligns with. It adds rich behavioral details: scanning top ~200 markets, child market traversal, partition checks, semantic anchor, fill check against CLOB depth. No contradictions.

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

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

The description is lengthy but well-organized with clear sections and bullet points. It could be slightly more concise, but each sentence adds value and the structure aids 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?

Despite no output schema, the description extensively covers return fields (opportunities[], partition_check, fill_check details) and safety checks (semantic anchor, partition filter, fill check). It also references custom sizing via another tool, ensuring completeness for a complex arbitrage tool.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds meaning: event accepts slug or full URL, topic is a seed question, and explains output behavior per 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and uses specific verbs and resources.

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

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

The description explicitly states when to use each mode: no args for trending_scan, event for a specific market slug, topic for cross-event scanning. It also provides guidance on when not to trade (realizable_edge_pp ≤ 0) and mentions fill_check and custom sizing.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral details: cache duration, model families (crypto_price, news_momentum, etc.), response segmentation, diagnostic output, and knob effects. 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 thorough but verbose, spanning over 500 words. It is well-structured with sections and bullet-like enumeration, but could be more concise to reduce token usage while retaining essential details.

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

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

Given the tool's complexity (9 parameters, multiple model families, no output schema), the description covers output structure (by_segment, diagnostics), knob effects, and caching. It is largely complete, though some internal model details could be summarized.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates the purpose of knobs like min_liquidity and max_spread_pp in context but does not add significant new meaning beyond the schema.

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

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

The description starts with a clear action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately conveys the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreements.

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 frames the tool for 'what should I bet on today' agents and explains how it discovers opportunities without manual paging. It also describes the cached nature and knobs, but does not explicitly contrast with siblings like polymarket_edge_tracker.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral traits beyond annotations: it explains data freshness (60-day TTL, daily snapshots), the source of decay numbers (daily closes, net of slippage), and potential gaps in data due to cache misses. 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 efficiently structured: first sentence states purpose, then details response fields, then limitations. Every sentence adds essential information with no fluff. It is front-loaded with the key concept, making it easy to scan.

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

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

Given no output schema, the description fully explains return values (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers limitations (TTL, snapshot gaps). For a tool with only two parameters and no nested objects, the description is exceptionally complete and actionable.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining how parameters affect the response (e.g., 'days' lookback, 'window' snapshot family) and provides context like default and max values. It also describes the response structure, helping users understand parameter impact. This exceeds the baseline 3 given full schema coverage.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides context on when to use this tool: 'a fresh wide edge and a 3-week-old wide edge are different trades...'. It implies that for current edges, one should use polymarket_edges. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, non-destructive. The description adds behavioral details such as walking the order book ladder, returning specific verdicts (clean|degraded|cannot_fill), clamping size to 10-1,000,000, and naming forced_directional_risk legs that could strand the user. 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 lengthy due to covering two modes with detailed output fields, but it is well-structured with clear sections for single-market and basket, and uses bold headings and bullet‑like lists. It is front-loaded with the core purpose. While every sentence is necessary, it could be slightly 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?

Given the tool's complexity (two modes, no output schema), the description comprehensively lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict) and explains the significance of each. It covers size limits and default behaviors. Minor gaps like exact data types or example values are acceptable without an 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 description coverage is 100%, but the description adds significant meaning: it clarifies the dual-mode interpretation of parameters (e.g., size_usd as spend vs target proceeds vs settlement notional), explains default side logic for baskets (auto from partition sum), and reiterates defaults and constraints. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, listing specific outputs for each, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by explaining its pre-trade risk assessment role.

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

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

The description explicitly tells when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why—theoretical overround on thin books is not capturable, and partial basket fills convert arb to unhedged positions—providing clear when-not-to 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?

Goes beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing compatibility_warning conditions, temporal alignment checks, and skipped cross types. 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?

Description is fairly long but well-structured: starts with purpose, then modes, response format, and safety fields. Every sentence provides necessary information. Could be slightly trimmed but remains 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?

No output schema, so description must explain return values. It does so thoroughly, covering leg-by-leg prices, spread output, safety fields (compatibility_warning, temporal_alignment), and skipped leg counts. Handles edge cases and sets expectations.

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

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

All three parameters are documented in the schema (100% coverage). Description adds value by explaining parameter interactions (overrides), describing the two modes, and providing context for the topic shortcuts. Baseline 3 raised due to meaningful extra context.

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

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

Description clearly states the tool computes cross-venue spread between Kalshi and Polymarket, specifies two modes (topic shortcuts and explicit tickers), and distinguishes from related tools. It's specific about the verb (compute spread) and resource (price differences).

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

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

Provides explicit guidance on when to use topic mode vs explicit parameters, warns that most pre-mapped topics currently return compatibility warnings, and explains safety fields. Lacks direct comparison to sibling tools, but the context is sufficient for an agent to decide.

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

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

Annotations already show readOnlyHint and idempotentHint, so bar is lower. Description adds context about identifier scoping and pairing with remember/forget, providing useful behavioral detail beyond annotations.

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

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

Three concise sentences that front-load the core purpose, with no wasted words. Information is 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?

For a simple key-value retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationships with sibling tools completely.

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

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

Schema coverage is 100% and the schema description already explains the parameter. The description adds the listing behavior but no new parameter meaning.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, using specific verb+resource. Distinguishes itself from siblings 'remember' and 'forget'.

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

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

Explicitly tells when to use (look up context stored earlier) and references alternatives (remember, forget). Provides scoping info and how to omit key for listing.

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 that mark_read:true mutates state by flagging events as read, but annotations declare readOnlyHint=true and destructiveHint=false, creating a contradiction. Per guidelines, contradiction yields score 1.

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

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

Concise with front-loaded purpose. A few sentences cover functionality, but could be slightly more structured. 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?

Describes return content (source, citation_uri, payload), gives filtering examples, and mentions polling and alternative endpoint. Does not explain limit or unread_only, but schema has descriptions. Overall adequate for a read-focused tool without 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?

Adds value beyond schema by explaining effects of mark_read on subsequent calls and providing example for type filter. Schema coverage is 100%, so the description enriches 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?

Clearly states 'Pull fired events from your subscription feed', specifying the action and resource. Details what each event carries (source, citation_uri, payload), distinguishing it from siblings like 'list_subscriptions'.

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

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

Provides filtering options (type, since) and explains mark_read usage. Mentions polling works fine and gives an alternative endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the parallel fan-out to multiple sources, the fallback mechanism from GDELT to GNews when rate-limited or 5xx, and the soft-fail for USPTO due to API sunset. It also describes the return structure (changes[] grouped by source, total_changes, citation URIs).

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 lengthy but every sentence adds value, starting with clear examples and ending with a comparison to 'entity_profile'. It is well-structured and front-loaded.

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

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

Despite no output schema, the description fully explains the return structure (changes grouped by source, total_changes, citation URIs). It covers input parameters, behavioral details (sources, fallback, soft-fail), and usage guidance. This is comprehensive for a data aggregation 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 extra context: it explains the 'since' format with examples and recommends '30d' or '1m', clarifies 'value' as ticker or CIK, and notes 'type' currently only supports 'company'. This practical guidance justifies a 4.

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

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

The description explicitly states the tool provides a 'change feed for a company' by fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It uses specific verbs and resources and distinguishes itself from 'entity_profile' by mentioning when to use that sibling tool instead.

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

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

The description gives clear example queries ('What's new with X', 'latest on Y'), specifies the window parameter usage, and explicitly advises using 'entity_profile' when a static profile is needed instead of a time-bound feed. It also explains the fallback behavior from GDELT to GNews.

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

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

The description adds behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This discloses persistence rules and scoping. Annotations (idempotentHint=true, destructiveHint=false) are consistent with the description.

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

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

Four sentences, all essential and well-organized. The first sentence captures purpose immediately. Subsequent sentences add usage context, persistence rules, and pairing with other tools. No wasted words.

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

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

For a simple write tool with no output schema, the description adequately explains the operation, persistence, and related tools. It doesn't describe the return value (e.g., confirmation), but that is minor for a storage operation. The description is complete enough 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?

Schema coverage is 100% with good parameter descriptions (examples for key, 'any text' for value). The description reinforces the key-value nature but adds no new semantic detail beyond what schema provides. A slight deduction for not adding new meaning.

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

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

The description uses a specific verb ('Save data') and resource ('data the agent will need to reuse later') and provides examples (resolved ticker, target address, user preference). It clearly distinguishes from sibling tools (recall, forget) by naming them explicitly.

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

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

The description explicitly states when to use the tool: 'when you discover something worth carrying forward'. It also provides context about scope (conversation or across sessions) and names related tools for retrieval and deletion. No exclusions are needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also details the return components per type (ticker, CIK, RxCUI, etc.) and citation URIs, providing behavioral insight 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 tightly written with no redundancy. It front-loads example queries to quickly convey purpose, then efficiently covers usage, supported types, and internal behavior. 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?

Given the tool has only two parameters and no output schema, the description adequately covers return components (ticker, CIK, RxCUI, etc.) and cites citation URIs. It does not specify the exact JSON structure of the response, but the openWorldHint suggests variability. Minor gap: response formatting could be hinted.

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

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

Schema description coverage is 100%, but the description adds meaning by providing concrete examples for the 'value' parameter (e.g., ticker AAPL, CIK 0000320193, drug names like 'ozempic') and clarifying that input is auto-disambiguated. This enhances the schema's minimal 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 begins with concrete example queries ('What's the ticker for...'), then explicitly states the verb 'resolve' and the resource 'name to canonical identifier.' It clearly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID,' and the sibling list contains alternative tools like 'entity_profile' and 'compare_entities'.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It lists supported entity types and what they return, making the context clear. However, it does not explicitly state when not to use this tool or mention specific siblings as 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 mark readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: probes each entity, ranks, surfaces most/least recognized. No contradiction with annotations.

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

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

Two sentences, front-loaded with main action, then outcome. Every sentence adds value. No wasted words.

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

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

No output schema, but description fully explains return: ranked list with score, confidence, signal density per entity. Covers tool's behavior and usage context 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%, so baseline 3. Description adds minimal new parameter info aside from clarifying 'context' disambiguates common names. Does not introduce new constraints beyond schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from siblings like compare_entities and ai_visibility_check by specifying the multi-entity comparative ranking purpose.

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

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

Provides explicit use case: competitive AI-marketing audits. Mentions it uses ai_visibility_check internally. Lacks explicit when-not-to-use or alternatives, but context sufficient for typical scenarios.

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 read-only, open-world, idempotent, non-destructive. Description adds beyond: partial failures (bundlephobia first measurement can take 5-30s, sources_failed list if times out), graceful degradation. No contradiction with annotations.

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

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

Description is informative but slightly verbose. Front-loaded with purpose, then details on fan-out, usage, output, limitations. Well-structured but could be tightened.

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

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

No output schema, so description thoroughly explains return values (summary block fields, advisory detail, links, alternative versions) and partial failure behavior. Complete for a composite 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?

Input schema has 100% coverage with descriptions for both parameters. Description adds context: 'version' defaults to latest, scoped packages accepted for 'package'. Adds value beyond schema.

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

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

Description clearly states tool checks if an npm package should be added, using data from deps.dev and bundlephobia. It specifies license, advisories, version history, bundle size, etc. Distinguishes from siblings by being a composite check across two services; no sibling tool appears similar.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Notes NPM-only in v1 and directs other ecosystems to deps.dev:version. Provides clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description goes beyond by detailing embedding model (BGE-base-en), window size (500-char overlapping), similarity (cosine), character cap (200K) with truncation and flagging. This adds significant behavioral context.

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

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

Description is front-loaded with the key action and use case. The second sentence packs technical details (embedding, window size, cap) which are useful but somewhat dense. Could be slightly more concise without losing information.

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

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

Despite no output schema, description fully explains return values (passages with offsets and similarity scores) and mentions truncation flag. For a tool with 3 parameters and moderate complexity, this is complete and anticipatory of agent needs.

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% description coverage with clear descriptions. Description adds value by providing example queries for the 'query' parameter and clarifying that 'text' is the document to search. However, schema already covers core meaning, so not a 5.

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?

Title and description clearly state it performs semantic search inside a fetched record. The verb 'Search' and resource 'Within a Source' are specific. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly advises using when 'the record is too big to cram into the prompt' and suggests alternatives: 'fetch with the gateway, ground over the relevant passages instead of the whole document'. Provides clear when-to-use and pairing with a sibling 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?

Despite annotations already indicating mutation (readOnlyHint=false) and idempotency (idempotentHint=true), the description adds crucial behavioral details: subscription persistence limitations, webhook secret single return, SMS cap, auto-disabling of webhooks after failures, and phone verification requirement. 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 informative and front-loaded, but it is relatively long. However, every sentence adds necessary detail, and the structure (listing types and delivery options) aids readability. Minor improvement could be more explicit separation of sections.

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 subscription types, nested params, delivery options with constraints), the description covers all essential aspects: creation, return value, prerequisites, limitations, and error conditions. No output schema exists, but the return value is adequately 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?

With 100% schema coverage, the description goes well beyond the schema by providing concrete examples for each subscription type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and detailing delivery channel constraints (SMS phone verification, email validation, webhook signing mechanism).

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

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

The description begins with a clear action and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It explicitly states the return value ('Returns the new subscription id.'), distinguishing it from siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides context on when to use the tool (proactive monitoring) and prerequisite requirements (Pipeworx OAuth account, not for anonymous/BYO). It also mentions alternatives for pulling alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'), though it does not explicitly exclude other 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, idempotentHint, and destructiveHint=false. The description adds context about output structure (category-bucketed example questions with tool + argument shape) and invocation options, 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?

The description is dense but well-structured, front-loading the purpose. Every sentence adds value, though it could be slightly 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?

Despite no output schema, the description thoroughly explains the return format (categories, examples with tool+arguments), invocation patterns, and use cases. No gaps remain for an onboarding 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% and describes the topic parameter with possible values. The description adds usage nuance: omitting gives full spread, passing topic focuses. Baseline 3 is elevated due to clear guidance.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and identifies the resource ('onboarding entry point'), clearly distinguishing from siblings like ask_pipeworx, discover_tools, etc.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic. Does not explicitly state when not to use, but the context is clear.

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

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

Discloses deactivation behavior (not deletion) and that historical events remain via recent_alerts. This adds context beyond annotations. Annotations show idempotentHint=true, which aligns with deactivation. No contradiction.

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

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

Three concise sentences with no wasted words. Front-loaded with main action, then adds ownership and behavioral 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 simple tool with one parameter and no output schema, the description completely covers purpose, usage constraint, and behavioral outcome. 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% and description of id parameter is clear but does not add substantial meaning beyond the schema's description. Baseline 3 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling subscribe by mentioning cancellation and ownership enforcement.

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

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

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' Also explains that the row is deactivated not deleted, guiding agents on when to use and what to expect.

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

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

The description adds significant behavioral context beyond the annotations: it explains the two processing pathways (structured SEC EDGAR for financial claims, grounded pipeline for others), the exact steps performed (NL parsing, entity resolution, etc.), and the return components (verdict, value with citation, reasoning). Annotations already indicate read-only, open-world, idempotent, and not destructive, and the description reinforces this 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 front-loaded with concrete user examples, then explains the two routing paths and the return value. Every sentence contributes essential information with no redundancy. It is appropriately sized for the tool's complexity 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?

The description covers the tool's input (claim types), processing (fast path vs grounded pipeline), output (verdict with evidence and reasoning), and usage context (replaces multiple calls). Despite no output schema, it fully explains what the agent can expect, making it complete for a tool of this 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?

Although the input schema has 100% coverage and provides descriptions for both parameters, the description adds substantial value: it explains how 'tolerance_pct' overrides the default implied by wording, gives example values like 1-2 for hallucination detection, and notes the default cap at 5. This provides practical guidance beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It starts with concrete user phrases like 'fact check' and 'verify the claim that...', and distinguishes between company-financial claims and other factual claims, specifying different processing paths. This provides a specific verb+resource with clear 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This is a clear when-to-use directive. It also mentions replacing 4-6 sequential calls, implying efficiency. However, it does not explicitly state when not to use or provide direct comparisons to sibling tools for exclusion.

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