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 cover the read-only, open-world, idempotent, and non-destructive profile, so the safety burden is already handled. The description adds meaningful behavior beyond annotations: it routes the question to the right tool among many, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This helps the agent set expectations for output and sourcing.

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

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

The description is longer than average, but nearly every sentence earns its place: preferred use cases, example queries, and concrete alternatives. It is front-loaded with the core 'prefer over web search' instruction and stays organized by moving from general behavior to specific examples to exclusions. A small amount of repetition could be trimmed, but it is not excessive.

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 broad natural-language routing tool with one required parameter and no output schema, the description provides sufficient context: what kind of questions qualify, example questions, expected return format, and alternative tools to select. Nothing essential is missing for an agent to decide when to invoke this 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%, and the schema already documents the single semantic parameter 'question' plus its aliases. The description adds useful examples and question categories, but does not materially change parameter-level semantics beyond what the schema already provides, so the high-coverage baseline of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx routes natural-language questions to a large catalog of verified data tools and returns structured answers with stable citation URIs. It names explicit domains and tells the agent to prefer it over web search for factual questions, making its purpose unmistakable and distinct from siblings.

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

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

The description gives explicit when-to-use guidance, including 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and examples. It also names when-not-to-use alternatives: ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, quote/quote_list/resolve_entity, and search_within. This is fully explicit routing 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful runtime context beyond those: no candidate routing is currently active, matching ask_pipeworx exactly, and it is a full working router with no fallback. This helps the agent understand current behavior and the experimental nature of the tool.

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

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

The description is front-loaded with the tool's identity and core behavior, then gives current status, usage, and fallback caveat. It contains some redundancy around 'matches exactly' and 'use it exactly', plus possible extra date detail, but it remains useful and well organized.

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

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

For a tool with no output schema and a fully documented input schema, the description successfully communicates how it behaves: currently identical to ask_pipeworx, experimental when a candidate is active, and fully functional. It references ask_pipeworx for response shape, which is generally sufficient if the sibling is known, but it does not itself specify the return format.

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

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

The schema already has 100% description coverage and documents the question parameter plus all aliases. The description only repeats that arguments match ask_pipeworx, so it does not meaningfully add to what the structured schema already provides.

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

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

The description clearly states that this is the beta version of ask_pipeworx, a universal router with the same 5,596 tools, same arguments, and same response shape. It differentiates itself from the stable ask_pipeworx sibling by being the experimental edge version.

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 the agent wants the newest routing, and notes that results are compared against the stable router. It does not explicitly state when not to use it, but the beta/experimental framing makes the intended choice situation clear.

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

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

Beyond the annotations, the description discloses important behavioral details: it returns an evidence quote, provides confidence, gives a fetched_at timestamp, and uses a structured refusal mechanism with specific refusal_reason values. It also clearly states that answers are extracted only from what the tool result contains, which directly satisfies the promise of grounded 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 dense but purposeful: it states the mode, explains the mechanism, spells out the exact success and refusal shapes, gives explicit usage guidance, and notes the cost tradeoff. No sentence is filler, and the most decision-relevant detail (grounded answer + when to use it) is laid out clearly and early.

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 fully compensates by documenting both the success return object and all possible refusal reasons. It also explains the routing behavior and compares the tool to its sibling for lookup purposes. An agent has enough information to know when to call it and how to interpret the result. The complexity of this tool is high enough that this level of coverage is necessary and is provided.

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

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

Schema description coverage is 100%, and the only relevant parameter is documented as a natural-language question with aliases. The description adds no parameter-level information; it focuses on internal routing and output behavior. Since the schema already fully covers the parameter meaning, a 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 defines this as a hallucination-resistant, grounded answer mode and states its core behavior: routing, fetching, and extracting the answer strictly from tool results. It also names 'ask_pipeworx' as the sibling it shares routing with, distinguishing it by the grounded extraction guarantee.

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

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

It gives explicit when-to-use guidance: any time the answer will be quoted, cited, or acted on, and the agent must avoid inventing facts. It also explicitly names the alternative, ask_pipeworx, and says to prefer it for casual lookups, while explaining the added cost of an extra LLM call.

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

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

Annotations already declare 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?

Annotations already mark readOnly, openWorld, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: parallel decomposition, never-invented gaps, latency expectations (15-60s, up to ~90s), contradiction analysis on certain depths, citation_uri only when fetchable, and semantic excerpting of large records. No contradiction with annotations appears.

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

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

The description is long, but nearly every sentence contributes distinct operational or routing information. It front-loads the critical account requirement and then organizes behavior, alternatives, latency, and return characteristics. Slightly dense, but not padded or repetitive.

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: it describes the findings packet, per-fact evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], and hop field. It also covers account requirements, latency, depth options, and routing exclusions, so an agent has enough to select, call, and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already fully documents both question and depth. However, the description adds useful semantic context about what the depth levels actually do, including the gap-recovery hops, contradiction scan, and paid tier requirement for thorough. That is valuable beyond the schema definitions.

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

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

The description states a specific verb (research) and resource (Pipeworx's structured data sources), and explicitly positions it as NOT open-web search. It differentiates itself from siblings by naming ask_pipeworx as the alternative for single lookups and for non-structured/open-world questions, making selection easy.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data. It also gives explicit when-not-to-use guidance: signed-out users should use ask_pipeworx, single lookups should go to ask_pipeworx, and breaking/open-world topics should prefer ask_pipeworx. No ambiguity about routing.

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

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

Annotations already 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?

The description discloses key behaviors not fully covered by annotations: rate limiting (5 per identifier per day), no quota impact, the claim_token mechanism for checking resolution status, and the team's daily digest review. Annotations only provide hints, so the description carries substantial behavioral transparency.

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

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

While lengthy, every sentence provides essential details: purpose, use cases, exclusions, token flow, rate limits, and roadmap signal. The description is front-loaded with the core purpose and flows logically, with no unnecessary 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?

For a tool with no output schema, the description comprehensively covers return values (claim_token), usage context, limitations, and escalation path. It fully compensates for the lack of an output schema and provides complete operational 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 coverage is 100%, so a baseline of 3 is appropriate. The description adds meaningful guidance beyond schema, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies message semantics. It also reinforces claim_token usage, adding context not present in the schema.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team something is broken, missing, or needs to exist. It uses a specific verb ('Tell') and resource (Pipeworx team), and effectively distinguishes it from sibling tools like ask_pipeworx by emphasizing this is for feedback, not for asking questions.

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

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

Explicitly describes when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion: feedback for tools from other MCP servers should not be filed here. It also explains the claim_token workflow, giving concrete usage guidance beyond mere description.

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 readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: cascading lookups, graceful degradation (GLEIF/OpenFIGI unavailability), and explicit unresolved identifier reporting. No contradictions with annotations.

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

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

The description is front-loaded with examples and key usage, but it is verbose (details like 'cross-source identity spine' and 'degrades gracefully' add length). Several sentences could be trimmed without losing essential information.

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

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

Given the tool's complexity (two entity types, multiple identifiers, cascading lookups, graceful degradation) and no output schema, the description covers the main aspects: supported types, input formats, enrichment behavior, and unresolved handling. It is fairly complete, though exact output structure is not described.

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

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

Schema description coverage is 100% (baseline 3). The description adds value beyond the schema by explaining the types with examples, detailing what identifiers are resolved for each type, and noting that input for company can be ticker, CIK, ISIN, or name. This enriches 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 opens with concrete example queries, then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly specifies the verb (resolve) and resource (names to identifiers), and distinguishes from siblings like compare_entities and entity_profile by focusing on ID lookup.

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

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

The description includes 'Use FIRST whenever you have a name but need an ID' – an explicit usage directive. It also notes that the tool replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or point to alternative tools for cases where an ID is already known.

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

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

Annotations 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?

Goes far beyond the readOnly/idempotent annotations by detailing critical behavior: could_not_verify means the check did not happen and carries verification_error, while unsupported means no source was found. It also describes the exact percent-delta math for financial claims and the verdict values returned.

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 longer than typical, every sentence earns its place: trigger phrases, routing logic, return format, and a critical caller warning. It is well-structured with clear paragraphs and front-loaded with examples, making it dense but not wasteful.

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

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

Given there is no output schema, the description fully covers return values (verdict, actual value, citation, reasoning), error modes (could_not_verify vs unsupported), and the two distinct processing paths (financial vs other). It is sufficiently complete for an agent to invoke and interpret results correctly.

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

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

The input schema already provides complete descriptions for both claim and tolerance_pct, including examples, ranges, and defaults. The description adds context about percent-delta math and tolerances but mostly reinforces schema information rather than introducing new parameter semantics beyond 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 performs natural-language claim verification against authoritative sources, with trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from siblings by explaining it replaces 4–6 sequential calls and covers both structured financial and grounded fallback paths.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates when to use the structured SEC EDGAR path vs the grounded pipeline for any other factual claim, guiding tool selection clearly.

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