Brapi

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

The description adds meaningful behavior beyond annotations: it discloses the free default model, the BYO key cost model ('you pay Anthropic directly'), and the response structure (per-model score, confidence, signals, raw_response plus combined view). With readOnlyHint already provided, this additional context is valuable.

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

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

The description is front-loaded with the core purpose, then provides default behavior, cost caveat, response format, and use cases in just two sentences. Every clause adds value with no redundant filler.

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

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

For a tool with 4 params and no output schema, the description is remarkably complete: it explains what the tool does, its output shape, default behavior, optional authentication, and typical use cases. The lack of an output schema is compensated by the described return structure.

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 enriches parameter understanding by noting the default workers-ai model, that Anthropic requires _apiKey, and gives concrete entity examples, going beyond the schema's property 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 function: probing LLMs for knowledge about a business/brand and scoring visibility. This distinguishes it from sibling tools like scan_competitor_ai_presence or entity_profile by specifying the unique visibility score and per-model analysis.

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

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

It explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default free model and optional Anthropic key usage. However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already indicate safe read-only behavior, and the description adds rich behavioral context: it routes to 5,358 tools across 1,395 sources, fills arguments, returns stable citation URIs, and works on every tier. No contradiction with annotations exists, and these details go far beyond the structured hints.

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

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

The description is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and remains highly informative without fluff. Every sentence adds value: use cases, alternatives, example questions, and caveats. Though lengthy, it is efficient for a tool that acts as a gateway to many sources.

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 broad scope and lack of output schema, the description is remarkably complete. It explains what the tool does, how it routes, what it returns (structured answer with citation URIs), when to use it, when to step up to alternatives, and even covers breaking-news use cases. The agent has everything needed to select and invoke it.

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

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

Schema coverage is 100%, with all six parameters (including aliases) described in the schema. The description reinforces that the question is a natural-language request and provides examples, but it does not add new field-level meaning beyond what the schema already defines. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities by routing to authoritative structured data sources. It also differentiates itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and by positioning itself as the default entry point. The verb 'ask' plus resource scope is specific and unambiguous.

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

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

Extremely explicit guidance is provided: 'PREFER OVER WEB SEARCH' for factual questions, 'START HERE for most questions', and 'Step up only when needed' with precise conditions for alternatives. It also lists query phrasings and example questions, leaving no doubt about 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 readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower, but the description adds substantial context: no candidate is active right now, the last was retired on 2026-07-26, it currently matches ask_pipeworx exactly, and it is a live experimental edge compared against stable routing. 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 front-loaded with the beta identity and core functionality, and every sentence contributes useful information about current state, usage, and comparison behavior. It is slightly dense and repeats the 'use exactly like ask_pipeworx' point, but remains well-structured and not bloated.

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

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

Even without an output schema, the description covers the identical response shape, experimental routing behavior, inactive candidate state, and how it relates to ask_pipeworx. Combined with rich annotations and a fully documented parameter schema, this is sufficient for the agent to understand when and how to invoke it.

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

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

The schema already provides 100% coverage with all six aliases documented, so the description only adds that the arguments are the same as ask_pipeworx. This cross-reference is helpful but not necessary for understanding the parameters; the schema carries the semantic weight.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,358 tools, arguments, and response shape. It distinguishes itself as the experimental candidate versus the stable ask_pipeworx, leaving no ambiguity about what the tool does.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It implies the stable version is the non-experimental alternative, but it does not explicitly list when not to use it or mention ask_pipeworx_grounded.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds refusal reasons, return shape, the 'exactly one extra LLM call' cost, and the constraint that extraction uses ONLY the tool result. This gives substantial behavioral context not captured by 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 every sentence earns its place: definition, routing mechanism, success/refusal formats, use cases, and cost tradeoff. It is front-loaded with the core identity and avoids 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?

Without an output schema, the description fully explains the return structure including refusal reasons, covers when to use and when not, and notes the performance cost. It is self-contained for effective agent decision-making.

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 already defines the question parameter with all aliases. The description does not add parameter-specific semantics beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly explains the routing and extraction behavior. It explicitly contrasts with sibling ask_pipeworx by emphasizing grounding answers in tool results only.

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 lists high-stakes examples. It also states the exclusions: 'prefer ask_pipeworx for casual lookups' and mentions the cost tradeoff.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the brapi.dev source and the 'complete list' scope, which is useful context. However, it does not disclose behavior such as response structure, rate limits, or whether the list is dynamic, leaving some gaps.

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

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

The description is a single, front-loaded sentence that immediately conveys the tool's purpose and source. Every word earns its place, with no redundancy or irrelevant information.

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

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

With zero parameters and an output schema present, the description fully captures the tool's role: enumerating supported Brazilian tickers for the quote endpoint. The return structure is presumably documented in the output schema, so the description need not duplicate it.

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

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

The tool has zero parameters, and the schema coverage is 100%, so no parameter semantics are needed beyond what the schema provides. The baseline for no-parameter tools is 4, and the description adds no unnecessary param details.

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

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

The description clearly states a specific verb ('list') and resource ('all available Brazilian market ticker symbols'), and explicitly ties it to the quote endpoint. This distinguishes it from sibling tools like quote and quote_list, which focus on retrieving quotes rather than enumerating valid symbols.

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

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

The description provides clear context by indicating the tool lists symbols supported by the quote endpoint, implying it should be used to discover valid tickers before using quote. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond with detailed behavioral disclosures: low-confidence matching suppresses analysis, closed markets return a blocking status, illiquid wide spreads are flagged, and cancellation-rule parsing quantifies void-settlement EV risk. It also explains fallback behavior for news sources (GDPR 429s/GNews backfill). No contradiction with annotations.

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

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

The description is long, but highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It is front-loaded with purpose and usage in the first two sentences. Every paragraph adds critical operational detail, so the length is justified.

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?

Since there is no output schema, the description carries the full burden of explaining return shapes. It thoroughly details result.market, result.analysis, result.evidence, resolver fields, parent-event data, news source fallback flags, and blocking statuses. It even covers edge cases like wide spreads and cancellation-rule refund scenarios—making the tool fully usable without external docs.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal parameter-level meaning beyond the schema: it reiterates the accepted market formats and gives examples of depth behavior, but does not clarify edge cases or formats beyond what is already in the schema. No need to compensate, so a 3 is appropriate.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which clearly identifies the action (research/pull) and the resource (Polymarket bet/Pipeworx data). It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data-backed research with a single-call fan-out.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear contexts, though it does not explicitly name alternative tools or exclusion criteria, which is a slight gap.

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

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

Annotations already declare readOnly/idempotent, and the description adds substantial context: SEC EDGAR/XBRL and FAERS data sources, off-calendar fiscal year handling, sorting by primary metric, and presence of citation URIs. No contradiction with annotations exists.

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

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

The description is dense and front-loaded with high-value trigger phrases, then explains preference, data specifics, and outputs. It is longer than minimal, but every section serves a purpose and the structure aids quick 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?

Despite having no output schema, the description discloses return shape (paired data + citation URIs), sorting behavior, scope limits (2–5 entities), and type-specific metrics. This is complete enough for an agent to invoke and interpret results confidently.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining what each type parameter retrieves (company financials vs drug counts) and giving concrete examples for values, going beyond the schema's terse descriptions.

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

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

The description opens with concrete trigger phrases and explicitly states it performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This clearly identifies both the action and resource, and differentiates it from sequential lookups and sibling tools like entity_profile.

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

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

It explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. The trigger examples ('which is bigger', 'rank these companies', 'head to head') further clarify the intended use 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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful context by specifying return fields (price, 24h change, market cap, volume) and the data source (Brazilian market), which goes beyond the annotation hints. 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?

The description is a single, front-loaded sentence that immediately communicates the core purpose. No filler words, every clause adds relevant 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?

For a simple two-parameter quote tool, the description covers purpose, parameters, and output fields. The output schema presumably handles return structure. Minor limitations, such as what 'Brazilian market data' specifically means, are not disclosed, but overall the context is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'coin' as a crypto ticker (e.g., 'BTC') and 'currency' with a default of BRL. The schema examples add 'USD' as an alternative, providing sufficient clarity for both parameters.

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

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

The description clearly identifies the action (price quote), resource (crypto coin), and scope (target currency, Brazilian market data). It distinguishes itself from sibling tools like 'currency' and 'quote' by explicitly mentioning crypto and the data source.

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?

Usage context is implied from the name and description, but there is no explicit guidance on when to use this tool versus alternatives like 'currency' or 'quote'. No exclusions or alternative tool references are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context about the return data (bid/ask, daily change) and scope (major pairs against BRL), but does not disclose potential limitations like rate limits or error handling. No contradiction with annotations.

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

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

The description is a single, information-dense sentence that front-loads the core purpose and includes an example. Every part earns its place, with 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?

The tool has an output schema and annotations covering safety, but the description is incomplete due to the ambiguous parameter semantics. It does mention the return values (bid/ask, daily change) and scope, but the confusion about whether the parameter is a single currency or a pair prevents a complete understanding.

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

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

Schema description coverage is 0%, so the description must explain the parameter. It explicitly says 'pair (e.g. 'USD-BRL')', implying the parameter should be a pair string. However, the schema property is named 'currency' with examples 'USD' and 'EUR' (single codes), creating ambiguity and conflicting cues about the required input format.

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

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

The description clearly states the tool's function: 'currency conversion rate for a pair (e.g. 'USD-BRL')' with specific outputs (bid/ask rate and daily change). It distinguishes from siblings like crypto or quote by focusing on fiat currency pairs and mentioning the data source 'brapi.dev'.

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

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

The description implies usage for currency conversion but provides no explicit alternatives or exclusions. It does not mention when to use this tool instead of sibling tools like 'crypto' or 'quote', leaving the agent to infer from the name and context.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by revealing the internal parallel decomposition, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] behavior, contradiction detection, second-hop iteration, semantic excerpting, and latency. 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 quite long and repeats ask_pipeworx guidance at least three times. While nearly every sentence contains useful information (like citation format and latency), it could be tightened to reduce redundancy. It is front-loaded with the account requirement, which is helpful, but overall it is verbose.

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 compensates by explaining return values in detail (findings packet, gaps, contradictions, hop field, citation_uri), behaviors for each depth level, runtime expectations, and prerequisites. It is complete for a complex tool with rich, multi-faceted behavior.

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

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

The input schema already covers all parameters (100% coverage), so the baseline is 3. The description adds meaningful extra semantics, especially for 'depth' by noting that 'thorough' requires a paid plan and clarifying how each depth value affects hop behavior and contradictions, which goes beyond the schema's enum 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 a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources... in ONE call' and 'Decomposes your question into focused facets, routes each to the right one of 5,358 tools IN PARALLEL'. It also distinguishes from sibling tools by explicitly contrasting with ask_pipeworx and noting this is NOT open-web search.

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 questions over structured data' and alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also details account requirements and depth-level tradeoffs, making it easy to select this tool vs 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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: it returns top-N tools with names, descriptions, and full input schemas, and each result is ready to call directly—no second schema lookup. This describes the output contract not present in annotations.

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

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

The description is front-loaded with the core purpose and packs useful information into two sentences: supported domains, return format, and usage priority. The long domain list is justified for a discovery tool and each clause 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?

Despite having no output schema, the description clearly states what is returned (names, descriptions, schemas, curated examples) and that results are directly callable. This fully covers the return behavior for a simple discovery 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 description coverage is 100% with all aliases and limit documented. The description's mention of 'top-N' adds slight relevance-ranking context not fully explicit in the schema, but this is marginal; 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 opens with 'Find tools by describing the data or task,' clearly identifying the verb (find) and resource (tools). It distinguishes this discovery tool from the long sibling list by framing it as the entry point for browsing available capabilities across listed domains.

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 instructs 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This provides clear context and differentiates from direct-answer 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 mark the tool as read-only and non-destructive, and the description adds substantial behavioral context: it fans out across multiple APIs, returns specific fields, and discloses that patents soft-fail due to an API sunset. There is no contradiction with the annotations.

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

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

The description is long but every section contributes: example user phrasings, source fan-out, return fields, and input constraints. It is front-loaded with use-case examples and organized well despite not using formal bullets.

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 enumerates the key result fields and includes fallback behavior (GDELT→GNews, soft-fail for patents), making the tool's capabilities and failure modes clear. It also covers input limitations and prerequisite actions, making it complete for a complex tool.

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

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

The input schema already provides detailed descriptions for both parameters, including ticker/CIK formats and the name restriction, so the baseline is 3. The description repeats these constraints and adds example values but does not materially expand parameter semantics beyond the schema.

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

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

The description clearly identifies a specific verb+resource: it produces a 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from sibling tools like compare_entities by being a single-entity profile and from chaining single-pack lookups by aggregating multiple sources.

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

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

It explicitly states when to use the tool ('when the user asks for a holistic view') and provides guidance to prefer it over chaining individual SEC/XBRL/news lookups. It also gives an exclusion: names are not supported and instructs to use resolve_entity first, naming the alternative tool.

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

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

Annotations already flag destructiveHint and idempotentHint; the description adds specificity by identifying the target as a 'previously stored memory' and mentioning the sensitive-data cleanup use case. 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 concise sentences, front-loaded with the action, followed by usage guidance and related tool pairing. Every sentence earns its place with no filler.

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

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

For a simple one-parameter destructive tool with strong annotations and no output schema, the description fully covers purpose, usage, and related tools. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single 'key' parameter, so baseline is 3. The description adds minimal extra meaning by calling it a 'previously stored memory' but doesn't elaborate on key format or constraints 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 begins with 'Delete a previously stored memory by key' – a specific verb and resource that clearly distinguishes it from siblings like 'remember' and 'recall'.

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

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

Explicitly provides use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with remember and recall, giving practical context, though it doesn't explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral detail by explaining the process ('Fetches the page, extracts title/description/key links') and the output ('single text blob ready to drop at site-root/llms.txt'), which enriches the agent's understanding beyond what annotations convey.

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

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

The description is two sentences, front-loaded with the core function and followed by a compact list of use cases. Every clause adds value—process, output, and target scenarios—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?

For a tool with only 2 parameters and no output schema, the description covers purpose, process, output format, and use cases. It gives the agent enough context to select and invoke the tool confidently without requiring additional details.

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?

Both parameters (url, max_links) have thorough descriptions in the schema, achieving 100% coverage. The tool description does not add significant parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL,' which is a specific verb+resource combination. It further clarifies the tool's role for AI crawlers and names the output format, making it clearly distinct from sibling tools like scan_competitor_ai_presence.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), offering clear context for when to apply the tool. However, it does not explicitly state when not to use it or name alternative tools for similar tasks.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint), so the description doesn't need to restate those. It adds useful behavioral context by explaining that the tool can return monthly readings over time and that the 'historical' flag and date range affect output. This goes beyond the structured annotations, though it omits details about edge cases or output structure, which is acceptable given the read-only nature.

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 source and purpose. There is no fluff or redundant information. Every clause contributes to understanding the tool's function, 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 tool's simplicity, the presence of an output schema, and annotations covering safety, the description is sufficient. It explains the core behavior and key parameters. The omission of sortBy/sortOrder details is minor because the schema examples provide some context, and the tool's purpose (returning monthly inflation data) is clearly conveyed.

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

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

The schema has 6 parameters with 0% description coverage, so the description must compensate. It explains 'historical' and 'start/end' date range, and indirectly 'country' via 'for Brazil or other countries'. However, it does not explain 'sortBy' or 'sortOrder', and does not specify expected formats (e.g., date format, country codes). This adds marginal value but leaves a notable gap for two parameters.

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

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

The description clearly states what the tool does: it provides inflation index series (IPCA/CPI) for Brazil or other countries, returning monthly readings. It distinguishes itself from sibling tools by focusing specifically on inflation data, and the verb 'returns' is implied in the functionality. This is highly specific and does not rely on the title alone.

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?

Usage is implied by the tool's purpose: it is for retrieving inflation data, so an agent would use it when needing inflation indices. However, there is no explicit guidance on when to use it vs. alternatives (e.g., currency, crypto) or any exclusions. The description does not mention alternative tools or provide when-not-to-use context, so it falls short of explicit usage guidelines but is still clear enough to infer.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds value by enumerating the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and emphasizing 'active subscriptions' as the default scope, which complements the include_inactive parameter. 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?

Two concise sentences: the first states the core function and return fields; the second gives practical use cases. No filler, front-loaded with the action, and 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's simplicity (one optional parameter, no output schema, strong annotations), the description is complete. It tells what the tool lists, what it returns, and why to use it, which is sufficient for an agent to select and invoke it correctly. No gaps that hinder usage.

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

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

Schema coverage is 100%: the sole parameter include_inactive is fully described in the input schema. The description does not add further parameter-level detail, but it does refer to 'active subscriptions' which aligns with the parameter's meaning. Baseline 3 is appropriate since the schema handles parameter semantics entirely.

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, specifies the returned fields, and implicitly distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing. The verb 'list' and resource 'subscriptions' are specific and unambiguous.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives concrete scenarios (pre-subscribe review and pre-unsubscribe id lookup) and implies the alternative tools (subscribe/unsubscribe) by context. It's clear when to invoke this tool versus siblings.

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

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

Annotations are all false and offer little safety signal, so the description carries the burden of behavioral disclosure. It adds valuable context: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also notes that 'The team reads digests daily and signal directly affects roadmap,' providing insight into the tool's operational impact. This goes beyond what annotations convey, though it doesn't fully describe all possible side effects (e.g., anonymity).

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, packing purpose, usage guidelines, content rules, and behavioral notes into a few sentences. Each sentence earns its place: the first defines the purpose, the second gives clear use cases, the third sets content guidelines, and the final two clarify rate limits and quota impact. No fluff or repetition.

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

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

Despite having no output schema and simple annotations, the description is remarkably complete for a feedback tool. It covers when to use, what content to provide, rate limits, quota impact, and even downstream consequences (roadmap influence). The nested 'context' object is implicitly explained by 'Describe the issue in terms of Pipeworx tools/packs.' This is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds extra usage semantics by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies how to fill the 'context' and 'message' fields. It also sets typical message length expectations ('1-2 sentences typical'). This supplements the schema meaningfully without duplicating it.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the action (tell), the resource (Pipeworx team), and the scope (feedback about bugs, features, data gaps, praise). This distinguishes it from sibling Q&A tools like ask_pipeworx, making its unique role clear.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides what to include ('Describe the issue in terms of Pipeworx tools/packs') and what to avoid ('don't paste the end-user's prompt'). This is clear, actionable guidance with no ambiguity.

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 supplements the readOnly/idempotent annotations with meaningful details: caching behavior ('Cached 5min-1h depending on window'), PII safety ('no PII'), and the underlying data source ('derived from CF analytics-engine'). This provides a clear understanding of what to expect without contradicting 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 front-loaded with the core purpose, followed by a numbered list of use cases and a final sentence on data characteristics. Every sentence adds distinct value and the structure makes it easy to scan. It is concise while covering all relevant aspects.

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 optional parameter, no output schema), the description is remarkably complete. It explains what is returned, the data format, caching, privacy, and when to use it. There are no significant gaps for an agent to 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 schema description already fully covers the single 'window' parameter (enum values, defaults, and interpretation). The tool description merely repeats the available options without adding new meaning. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a clear question ('What other AI agents are calling on Pipeworx right now?') and then specifies the exact output: 'top tools, top packs, and total call volume.' This clearly distinguishes it from sibling tools like discover_tools by focusing on aggregate usage statistics.

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 three explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs), giving clear context on when to use it. However, it does not explicitly mention any alternative tools or exclusion criteria, so it falls short of a 5.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds extensive behavioral nuance: the semantic anchor threshold (Jaccard ≥0.30), the partition filter with placeholder fraction >20% returning null, the fill check against live CLOB depth, and explicit guidance 'do not trade it' when realizable_edge_pp ≤0. This is highly transparent about internal logic and failure conditions.

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 and packed with detail, but nearly every sentence carries unique information essential to using the tool correctly (modes, thresholds, response structure, fill check). The use of capital labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improves parseability. It is appropriately structured for the complexity, though slightly verbose.

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 explains the return shape ('opportunities[]', 'partition_check', 'skipped_low_similarity', 'theoretical_edge_pp_at_book', 'realizable_edge_pp', 'thin_legs[]') and covers edge cases (placeholders, low similarity, no-arg scan). It also mentions the companion tool for custom sizing, making it contextually self-sufficient. This is as complete as a description can be for such a complex tool.

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

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

The schema already describes both event and topic well, so the baseline is high. The description enhances this with concrete slug examples (e.g., 'fed-decision-may-2026'), clarifies that full URLs are also accepted, and explicitly contrasts the two parameter modes. It adds meaningful usage context beyond the schema, warranting a 4.

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

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

The description opens with a precise verb+resource statement ('Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'), clearly differentiating it from siblings like polymarket_edges or polymarket_fill_risk. It goes on to specify distinct modes (trending_scan, event, topic), making the tool's purpose unambiguous.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing ('use polymarket_fill_risk'), and provides concrete example inputs, giving the agent clear decision criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context beyond those: caching at the KV level for 1 hour keyed on all knobs, a 24h-move warning that flags when recent price movement exceeds the edge, and the nuanced behavior that partition_overround returns kelly_fraction_half=0 at the parent level by design. It also explains why Fed bets are excluded, providing transparency about data limitations and ranking exclusions. No contradictions with annotations.

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

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

The description is long but densely packed with essential information for a complex tool. It is front-loaded with the core purpose and then systematically covers model families, response structure, knobs, diagnostics, and caching. Each sentence carries specific operational detail, but the sheer length and heavy use of technical jargon (e.g., 'GDELT 7d/21d article-volume ratio', 'lognormal barrier from 90d FRED log-returns') may reduce immediate readability for an agent. It is not wasteful, but it could be more concise by trimming some implementation-level detail.

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

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

Given the tool's complexity (three model families, nine optional knobs, nested diagnostics, no output schema), the description is exceptionally complete. It fully specifies the top-level response structure (by_segment, fed_candidates, _diagnostics), explains how to interpret empty segments (via funnel counters and filter_skips), and documents the tradeable-edge knobs. There is no output schema, so the description carries the full burden of explaining the return contract, and it does so thoroughly.

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

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

The input schema already describes all 9 parameters with 100% coverage, so the baseline is 3. The description adds meaningful context for several parameters: it explains why min_kelly does not filter partition_overround opportunities (because parent-level kelly is always 0), provides real-world slippage context ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), and clarifies the semantics of min_liquidity and max_spread_pp as 'Tradeable-edge filters'. This goes beyond simply restating the schema, earning a 4.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes the tool from siblings by naming its unique purpose (discovering discrepancies between Pipeworx data and market price) and further details three distinctive model families (crypto_price, news_momentum, partition_overround). This is far beyond a tautology and clearly separates it from other Polymarket-related tools.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives practical guidance on knob usage (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). However, it never directly contrasts with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving the 'when not to use' implicit rather than explicit.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds crucial behavioral details: history is bounded by a 60-day TTL, snapshots are written on cache-miss so gaps mean no scan, decay uses daily closes not intraday, values are signed (negative = SELL YES), and trend classifications are enumerated. This is exactly the kind of non-obvious behavior an agent needs to know.

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 and dense. It front-loads the purpose, then uses clear labels (Args, RESPONSE, LIMITS) to organize parameter, output, and limitation details. Every sentence adds value, no fluff or repetition.

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

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

With no output schema, the description thoroughly explains the response shape: tracked[], expired[], and snapshot_dates[] with their fields and semantics. It also covers data pipeline quirks (cache-miss snapshots, TTL) and calculation methodology. This is unusually complete for a tool with simple inputs.

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

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

Schema coverage is 100%, so the description has little to add. It restates defaults (days default 14, max 30; window default '1wk') which are already in the schema. It does add a small amount of context by calling window a 'snapshot family' and mentioning the 24hr|1wk|1mo options, but this largely duplicates schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question ('how long has this edge existed and is it shrinking?'). It uses a specific verb+resource ('tracker' for edge persistence) and naturally distinguishes itself from siblings like polymarket_edges by focusing on historical edge decay over time.

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

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

It gives practical usage context: a fresh wide edge and a 3-week-old wide edge are 'different trades,' implying this tool is for assessing edge age/decay. It also tells the user how to interpret results ('the median lifespan is your competition clock'). It does not explicitly name alternative tools, but the sibling context and domain are clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral detail beyond annotations: it walks the order-book ladder, returns specific fill metrics, and explicitly discloses the risk of partial basket fills creating unhedged directional positions. No contradiction with annotations.

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

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

The description is dense but well-structured: a one-sentence purpose, then clear all-caps section markers (SINGLE-MARKET, BASKET) that separate modes. Every sentence adds operational detail—return fields, defaults, risk warnings—with no filler. Appropriate length for a two-mode tool.

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 enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It covers prerequisites, default behavior, and the dominant loss mode, making the tool's invocation and interpretation self-contained.

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

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

Despite 100% schema coverage, the description adds critical cross-parameter semantics: market and event are mutually exclusive modes, side changes meaning depending on mode, and size_usd is interpreted as spend, target proceeds, or settlement notional. It also clarifies the conditional requirement (market OR event) that the schema does not encode, significantly aiding correct invocation.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines the tool's function and distinguishes it from sibling tools (polymarket_arbitrage, polymarket_edges) by emphasizing fill-risk evaluation rather than just edge detection.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when NOT to rely on theoretical overround and warns that partial fills convert arb into unhedged directional risk, giving clear context for alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: compatibility_warning fires in two specific edge cases, temporal_alignment{...} clarifies when spreads are meaningless, and skipped_cross_type/subtype counters explain how leg-pair comparisons are dropped. It also notes that real cross-venue spreads are rarer than the macro-shortcut list suggests. 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?

Although long, the description is exceptionally well-structured with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence delivers unique value: conceptual background, mode mechanics, output details, warning conditions, temporal alignment meaning, and a crucial caveat. There is no redundant restatement of schema or annotations, making the length justified.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning conditions, temporal_alignment fields, and skipped_cross_type/subtype counters. It also addresses real-world limitations and edge cases, making it complete for a tool with only three optional parameters.

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 described in the schema with 100% coverage, including allowed topic values and override semantics. The description goes beyond this by explaining the two modes as a cohesive usage model, reinforcing that explicit identifiers override topic-mapped sides, and listing the exact macro shortcuts. While the schema already does heavy lifting, the description adds contextual structure and example semantics.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', clearly stating the specific resource and action. It distinguishes itself from sibling Polymarket-only tools by emphasizing the cross-venue nature and proceeds to explain two distinct modes, making the purpose unmistakable.

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

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

The description provides clear context on when to use the tool: two modes (pre-mapped topics or explicit event identifiers) and a strong caveat that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'. This guides expectations and when NOT to expect tradeable spreads. However, it does not explicitly name alternative tools (e.g., for intra-venue opportunities), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by specifying the data source (brapi.dev) and that historical flag plus date range returns time-series readings, which is beyond what annotations provide.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's purpose, key options, and output behavior. There is no wasted 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 an output schema present, the description does not need to explain return values. It sufficiently covers the tool's main functionality and how to request historical data. Minor omissions like default behavior or sort options are acceptable given the schema and overall simplicity.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains key parameters: historical flag, start/end date range, and country implication. It does not elaborate on sortBy/sortOrder, but the schema examples help. Overall, it adds meaningful semantics for most parameters despite the gap.

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

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

The description clearly states it returns prime/benchmark interest rate series (Selic/base rate) for Brazil or other countries, and explains that an optional historical flag plus date range gives readings over time. This is a specific verb+resource with scope, distinguishing it from sibling tools like inflation or currency.

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 the tool is for interest rate series and explains the optional historical flag and date range, giving clear context for how to use it. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that quotes are live and lists the data fields, but it does not mention rate limits, authentication, or any additional behavioral constraints beyond what annotations imply.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose, example, and available data options. No redundant or unnecessary words are present.

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

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

The tool has an output schema, so return values are covered, and annotations handle safety. However, the description does not explain all parameters (modules, dividends) and shows inconsistent ticker suffix examples ('PETR4' vs 'IBOV11.SA'), which could confuse an agent selecting inputs.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the tickers format and mentions OHLC range/interval and fundamental data, but leaves 'modules' and 'dividends' unexplained. The example shows dividends but gives no semantic detail, leaving a significant gap.

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 fetches live quotes for Brazilian market tickers, including price, change, volume, and optional OHLC and fundamental data. The example with comma-separated tickers makes the purpose concrete, and the 'Brazilian market' scope distinguishes it from sibling financial tools.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives like quote_list, crypto, or currency. The example implies usage for Brazilian stocks, but there are no exclusions, prerequisites, or direct comparisons to 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?

The description adds behavioral context beyond the readOnlyHint and idempotentHint annotations by specifying pagination behavior and optional filters (search, sector, sort). It also reveals the data source (brapi.dev) and covered asset classes. It does not disclose defaults like page size, but the output schema compensates for return structure, and no contradictions with annotations exist.

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 data provider and core behavior. It avoids filler and every clause contributes to understanding the tool's purpose and usage. Efficiency is exemplary without sacrificing clarity.

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

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

For a directory tool with 7 parameters and no schema descriptions, the high-level overview is helpful but not fully complete. It explains the general capability but omits specifics on parameter values (e.g., type enums, sort options). The existence of an output schema covers return values, but the input side remains partially underdocumented for an agent to use confidently.

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

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

With 0% schema coverage, the description carries the burden of explaining parameters. It mentions 'text search, sector filter, and sort', mapping to search, sector, sortBy, and sortOrder, and implies page/limit via 'paginated'. However, it does not specify allowed values for `type`, `sortBy`, or `sortOrder`, leaving the agent to infer or guess. Partial compensation for the lack of 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 defines the tool as a 'paginated directory of all Brazilian market tickers' with explicit scope (B3-listed stocks, ETFs, FIIs). It distinguishes itself from sibling tools like 'quote' by focusing on enumeration/discovery rather than individual quotes. The phrase 'Use to discover or enumerate' leaves no ambiguity about its 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?

The description explicitly states when to use the tool: 'Use to discover or enumerate B3-listed symbols.' It does not mention alternatives or when not to use it, but the context is sufficient for an agent to differentiate it from sibling tools such as 'quote' or 'crypto'. A clear directive but lacks an explicit exclusion clause.

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 context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieve/list behavior. However, it does not describe return values or error behavior, though these are not heavily needed for this simple tool.

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

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

Three sentences with front-loaded action and no waste. Each sentence adds distinct value: action, usage examples, and scoping/pairing. Concise yet comprehensive.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers the two modes, scoping, and relationship to remember/forget. No critical information is missing for an agent to use this tool correctly.

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

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

Schema description coverage is 100% for the single 'key' parameter, including the omit-to-list behavior. The description adds examples of values ('target ticker, address, research notes') but these are values, not key syntax. Baseline 3 is appropriate given the schema carries the parameter semantics.

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

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

The description clearly states the tool retrieves values saved via remember or lists all saved keys when the key is omitted. It explicitly distinguishes itself from sibling tools by naming remember and forget, making its purpose unambiguous.

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

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

It explicitly states when to use the tool ('look up context the agent stored earlier') and provides exclusionary guidance by pairing with remember to save and forget to delete. This gives clear context relative to 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?

The description explicitly describes mark_read:true as flagging returned events read, which is a side effect. This directly contradicts the readOnlyHint annotation set to true. The tool mutates read state, so it is not purely read-only, creating a serious annotation 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 well-structured, front-loading the main purpose, then providing details on returns, filtering, side effects, and alternative access. Every sentence adds useful information without redundancy.

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

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

Given 5 optional parameters and no output schema, the description is thorough. It explains the return payload, filtering, mark_read effect, polling suitability, and provides an alternative endpoint, making the tool's behavior fully comprehensible for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value with a concrete example for type ('sec_8k'), clarifies since is an ISO timestamp, and explains the effect of mark_read. This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the resource and action. It distinguishes itself by focusing on alerts from a persisted feed, which is distinct from sibling tools like list_subscriptions.

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

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

The description provides context on filtering, mark_read, and polling, and even notes an alternative HTTP endpoint for scripts/dashboards. It does not explicitly say when not to use this tool versus specific siblings, but the guidance is clear enough 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses multi-source fan-out to SEC EDGAR, GDELT/GNews fallback with specific trigger conditions (rate-limited or 5xx), the PatentsView API sunset causing soft-fail, and the return shape (changes[] grouped by source, total_changes count, citation URIs). This is rich behavioral context with 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?

The description is long but every clause earns its place: intents, source logic, fallback behavior, parameter formats, output summary, and the alternative tool. It is front-loaded with user-facing natural language examples and remains dense 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 complex multi-source tool with no output schema, the description covers all necessary aspects: usage, parameters, source behavior, limitations (patent sunset), output structure, and alternatives. The agent has enough to invoke correctly and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the `since` format and value examples but adds no new parameter semantics beyond what the schema already provides (e.g., the '30d' typical-monitoring advice is already in the schema). It remains at baseline.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y'), then defines the tool as a 'change feed for a company in the last N days/weeks/months'. This is a specific verb+resource+scope. It also explicitly distinguishes itself from entity_profile by directing static-profile queries there, which separates it from the closest sibling.

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 clearly states when to use this tool: for temporal change-feed queries ('what's new', 'updates'). It explicitly names an alternative, entity_profile, and explains the difference ('static profile ... regardless of window'). This meets the 5 standard for explicit when-to-use and when-not-to-use.

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

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

Annotations include idempotentHint: true and readOnlyHint: false. The description adds meaningful context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier.' No contradiction with annotations; it enriches them with persistence and scoping details.

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

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

The description is three sentences and highly efficient: it front-loads the purpose, gives usage examples, explains storage behavior, and references companion tools. Every sentence earns its place with no fluff.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, and related tools. It lacks explicit overwrite behavior, but idempotentHint: true covers that. Overall, it is sufficiently complete for the tool's simplicity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds generic context like 'key-value pair scoped by your identifier' but does not provide additional parameter-specific semantics beyond what the schema already documents with examples.

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

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

The description states the tool's purpose clearly: 'Save data the agent will need to reuse later.' It identifies a specific verb and resource (save data) and distinguishes from sibling tools recall and forget by explicitly mentioning them as companions.

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

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

The description provides clear usage context: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives via 'Pair with recall to retrieve later, forget to delete,' though it does not explicitly say when not to use the tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context beyond annotations: it discloses internal cascading through multiple lookup endpoints, auto-disambiguation of ambiguous input, and the exact return payload including citation URIs. This provides valuable transparency about side effects and internal operations.

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

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

The description is front-loaded with example queries that instantly convey purpose, then organizes details under 'SUPPORTED TYPES' for easy scanning. Every sentence adds functional information—no fluff or repetition. It is longer than minimal, but the complexity of the tool warrants the length and the structure is excellent.

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

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

Despite lacking an output schema, the description comprehensively details return values (ticker, CIK, company_name for companies; RxCUI, ingredient, brand for drugs) and citation URIs. It also covers accepted input forms and the internal lookup cascade. Combined with the annotations, the description is fully sufficient 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 schema provides 100% coverage with detailed parameter descriptions for both 'type' and 'value'. The description adds semantic nuance by mentioning auto-disambiguation and flexible input formats (ticker, CIK, or name for companies), which goes slightly beyond the schema-level definitions. This incremental value justifies a score above the baseline of 3.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, using a specific verb and resource. It distinguishes itself from siblings by explaining it provides identifiers that other tools require, and it gives concrete example queries. The supported entity types and their specific outputs are enumerated, making the purpose unmistakable.

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

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

The description explicitly directs use 'FIRST whenever you have a name but need an ID' and lists supported entity types. It suggests using this tool as a preliminary step but does not name alternative tools or explicitly state when not to use it. The context is clear, but explicit exclusion criteria are absent.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds behavioral detail beyond annotations: it probes each entity via ai_visibility_check, ranks by score, and treats the first entity as the subject for narrative. It also discloses return contents (score, confidence, signal density). This is meaningful context, though it could mention potential rate limits or failures.

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

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

The description is three sentences, each serving a distinct purpose: core function, mechanism/use case, and return format. It is front-loaded with the main purpose, avoids repetition, and contains no filler. This is an exemplary balance of detail and brevity.

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

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

With no output schema, the description compensates by specifying the return format: 'ranked list with score, confidence, signal density per entity.' It also explains the internal probe mechanism and the subject/competitor narrative. Some edge cases (e.g., API key failures, model-specific quirks) are not covered, but the tool is well-specified for its complexity.

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

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

Schema description coverage is 100%, so each parameter is documented. The description adds semantic nuance beyond schema: it explains that the first entity is the 'subject' and the rest are competitors, and that context is applied across all probes. These details help the agent understand the intended use of the entities parameter beyond its raw description.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility), and scope (multiple entities), and differentiates from sibling tools like ai_visibility_check by focusing on multi-entity comparison and ranking. The example use case further reinforces the 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?

The description provides clear context for when to use this tool: 'Useful for competitive AI-marketing audits' with an illustrative query. It implies single-entity checks should use ai_visibility_check, but it doesn't explicitly state exclusions or alternatives. The guidance is clear enough for typical 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses partial failure behavior and latency: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also reveals the fan-out architecture, adding valuable context about how the tool operates.

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, starting with purpose, then usage, return fields, scope, and failure behavior. Every sentence provides value, though the length is slightly above the minimum needed. The use of em-dashes and semicolons improves 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?

With no output schema, the description adequately enumerates the return structure (summary block fields, per-advisory detail, links, recent alternative versions). It also covers ecosystem limitations, partial failure behavior, and latency expectations, making it 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 clear descriptions for both parameters (package name and version with default behavior), covering 100% of the parameters. The description does not add additional meaning to the parameters beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a composite check for 'should I add this npm package to my project', explicitly mentioning the resources (deps.dev and bundlephobia) and the specific data points it returns. It distinguishes itself from siblings by being a one-call composite, rather than a single-source 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?

Provides explicit usage triggers ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and an explicit exclusion with alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is clear when-to-use and when-not-to-use guidance.

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

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

The description goes far beyond the annotations by revealing implementation details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows,' a hard cap with 'truncated and flagged,' and output includes 'character offsets' for verification. These behaviors are not present in the annotations and significantly improve the agent's ability to predict tool behavior.

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

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

The description is three sentences with no filler. The first sentence states the core purpose, the second explains the primary use case and benefit, and the third provides key technical constraints. Every sentence carries necessary information, making it dense yet 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?

There is no output schema, but the description explicitly covers the return format: 'top-N passages with character offsets and similarity scores.' It also covers input limits and flagging behavior, making the tool's inputs, outputs, and edge cases adequately specified for an agent to use correctly without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it notes the truncation behavior for long inputs, describes the chunking mechanism (500-char overlapping windows), and explains that results carry offsets and similarity scores. This enriches parameter understanding, though it doesn't alter parameter types or defaults.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It uses a specific verb ('search'), names the resource ('a fetched record'), and distinguishes itself from the sibling 'ask_pipeworx_grounded' by explaining it operates on text already pulled by the agent.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative and pairing instruction: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and avoids confusion with other search 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 indicate readOnly=false and idempotent=true, but the description adds substantial behavioral context: OAuth requirement, return of subscription id, SMS verification and 10/day cap, webhook auto-disable after 10 failures, and one-time signing secret. This goes well beyond the annotation hints.

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

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

The description is long but information-dense, with purpose front-loaded in the first sentence and structured details about types and delivery. For a tool with 5 subscription types and 3 delivery channels, the length is justified and every section serves a purpose.

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

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

With no output schema, the description covers key return value ('Returns the new subscription id'), prerequisites, all supported types with examples, delivery channel behaviors, and limitations (verification, caps, auto-disable). It also references how to consume the always-on feed, making it self-sufficient 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?

The input schema already covers all parameters with 100% descriptive coverage, giving a baseline of 3. The description adds meaning beyond the schema by explaining that 'items:["5.02"]' means officer change and characterizing polymarket_edge as cross-venue mispricings, which enriches parameter understanding.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and it highlights supported types (sec_8k, polymarket_edge, fred_series) and delivery channels.

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 prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and hints at alternative retrieval via 'recent_alerts' or a feed URL. However, it does not explicitly state when not to use the tool versus alternatives (e.g., list_subscriptions or unsubscribe), so it stops short of a full when/when-not guide.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds behavioral context beyond annotations: it explains the response is drawn from a live catalog and structured by category, and that the tool suggests rather than executes. 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?

The description is long but information-dense: it packs example queries, category list, output description, and invocation guidance into a few sentences. It is front-loaded with natural-language triggers and each clause contributes value, though it could be slightly tighter.

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 one-param tool with no output schema, the description fully explains the return value (category-bucketed example questions), invocation modes (no args vs topic), and when to use it. It also names related meta-tools, making it self-sufficient 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?

The schema description covers the single optional `topic` parameter 100%, listing valid values and default behavior. The tool description merely rephrases this with examples ('finance', 'pharma', 'betting'), adding no substantive 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 clearly states the tool is the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It uses a specific verb ('returns') and resource ('example questions'), and distinguishes itself from siblings like discover_tools by focusing on question suggestions and meta-tool guidance.

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

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

It explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It also explains when to pass a `topic` vs. omit it, providing clear context and naming 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?

The description reveals important behavioral traits beyond the annotations: ownership enforcement and the soft-delete behavior ('deactivated, not deleted') which preserves historical events via recent_alerts. These details are not present in the annotations, which only say non-destructive and idempotent.

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 primary action, and the second sentence adds critical behavioral context. No fluff or redundancy exists.

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 single-parameter tool with no output schema, the description is complete: it states the action, the ownership constraint, the side effect (deactivation rather than deletion), and how to access historical events afterward. No important aspect is unexplained.

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 100% parameter description coverage for the id field, stating it is a uuid returned by subscribe. The description merely repeats 'by id' and adds no extra meaning or detail, so it meets the baseline without improvement.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly states the action and scope, and differentiates from sibling tools like subscribe and list_subscriptions by noting the deactivation behavior and linking to recent_alerts for historical events.

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

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

The description gives clear context: it cancels subscriptions by id, and mentions ownership enforcement so users know they can only cancel their own subscriptions. This implies when to use the tool, but it does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context: the exact verdict categories, the fast-path vs. grounded-pipeline routing, verbatim evidence, citation, reasoning, and the claim that it replaces 4–6 sequential calls. This goes well beyond what annotations provide.

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

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

The description is fairly long but front-loaded with purpose and usage, and every sentence contributes either routing logic, return values, or efficiency gains. It is dense but appropriately sized for a tool with complex claim-handling behavior; still, it could be tightened slightly without losing value.

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

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

With no output schema, the description fully compensates by listing the verdict values, the actual value with citation, and reasoning. It also clarifies when to use the tool, the underlying pipelines, and the efficiency benefit, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the tolerance_pct parameter by explaining how it overrides the tolerance implied by claim wording, caps at 5 by default, and is recommended for hallucination detection. This adds meaningful semantics beyond the raw 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 opens with concrete user phrasings and explicitly states the tool performs 'natural-language claim verification against authoritative sources' and checks whether 'something a user said is factually correct.' It clearly distinguishes the tool from siblings by detailing the SEC EDGAR/XBRL fast path for financial claims versus the grounded pipeline for all other claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and it provides clear context by splitting claim types (company-financial vs. any other). However, it does not explicitly name sibling alternatives or state when not to use the tool, so it falls short of the 5-level criteria.

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