Nba

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral details: default model (Workers AI), optional Anthropic key with 'you pay directly' cost note, and return structure (per-model + combined view).

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

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

The description is a single paragraph of 3 sentences, front-loads the core function, and avoids redundancy. Every sentence adds 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?

Despite no output schema, the description adequately details return values (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters, use cases, and key behaviors.

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

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

Schema coverage is 100%, but description adds value by explaining entity as 'thing to ask about', listing supported models, noting _apiKey pass-through, and describing context as disambiguation aid.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes from siblings by specifying AI-marketing audits, pre-launch brand checks, and competitive monitoring as use cases.

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

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

The description gives clear usage context (AI-marketing audits, competitive monitoring) but does not explicitly compare to alternatives like scan_competitor_ai_presence or 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, openWorldHint, idempotentHint, and destructiveHint false, so the basic safety profile is covered. The description adds significant behavioral context: it explains that the tool routes internally to specialized tools and auto-fills arguments, returns structured answers with stable pipeworx:// citation URIs. It avoids contradicting annotations and gives an agent useful expectations about what happens after the call.

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 key 'PREFER OVER WEB SEARCH' and 'START HERE' signals are front-loaded, followed by a sensible progression from functoin to trigger phrases to concrete examples. It is dense and could be slightly tightened—some repetition of 'citations' and 'authoritative'—but every section earns its place in guiding tool selection and invocation.

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?

Description addresses main expected use, the value proposition, and primary sibling routing, which is almost everything the agent needs for selecting and using it. It would ideally describe the response shape in a bit more detail since there is no output schema, but the 'structured answer' + 'citation URIs' line covers the majority. Overall the agent can determine when to use and roughly what to expect.

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

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

Schema coverage is 100% with six aliases for the single 'question' field, so the baseline is 3. The description enhances this by clarifying only natural-language input is needed and that internal routing will fill the arguments — even providing concrete example queries. The tool's 'auto-fill and route' behavior turns the schema aliases into a meaningful 'just ask' contract.

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?

Strongly defined: 'PREFER OVER WEB SEARCH for questions about current or historical data' plus a explicit list of covered domains. It states the function (routes to 5,596 tools, fills arguments, returns structured answer with citations) and gives clear trigger phrases and examples. Distinct from siblings via 'START HERE for most questions' plus named alternatives.

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

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

'Use whenever the user asks "what is", "look up", ... even if web search could also answer it' provides clear positive conditions for use. It also gives alternatives to use instead: 'deep_research' for broad multi-path research and 'ask_pipeworx_grounded'/'validate_claim' for more citation-heavy work. The description also explicitly advises again, making the boundary of this tool 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?

Safety is already covered by annotations (read-only, idempotent, non-destructive). The description adds significant dynamic context: candidate improvements are live only when one is under test, none is currently active, behavior currently matches ask_pipeworx exactly, and it proactively corrects the likely misconception that beta means it might not be a full working router.

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?

Justified length: every sentence contributes some distinct fact — identity, identical scope, current state, usage context, and fallback disambiguation. It is well front-loaded, though the repeated 'same...same...same' phrasing and the slightly awkward 'Falls back to nothing' sentence cost some readability.

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

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

Given the lack of an output schema, the description borrows ask_pipeworx's output contract by promising the 'same response shape', which gives agents a usable reference point. It also covers the current candidate state and the experimental lifecycle. The only gap is that the response envelope structure is never directly described; the agent must know ask_pipeworx to infer it.

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

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

Schema description coverage is 100%; the schema already documents the question parameter and lists q, text, input, prompt as aliases. The description adds only the meta-note 'same arguments' but no new parameter-level semantics, so the 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 identifies the tool as the beta twin of ask_pipeworx: a universal router with the same 5,596 tools, same arguments, and same response shape. It distinguishes itself from stable ask_pipeworx and other siblings by its experimental-edge status, making its role 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 beta: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the A/B purpose (compared against the stable router to decide merges). It doesn't spell out a formal 'when NOT to use' alternative such as stability-first scenarios, but the selection logic is clear enough for an agent to route correctly.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), it describes refusal modes, evidence as verbatim quote, source/fetched_at fields, and the additional LLM cost. It even enumerates refusal reasons like not_in_source and data_truncated. This is rich behavioral disclosure 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 dense but every sentence earns its place: core behavior, response shape, refusal modes, use cases, and cost trade-off. It is front-loaded with the most important distinction ('Hallucination-resistant') and does not waste words on obvious schema content.

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

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

There is no output schema, yet the description still spells out the return contract {answer, evidence, confidence, source, fetched_at, refusal_reason:null}. It also gives enough routing context, source count, comparison to the sibling, and a net cost consideration for the agent to make a sound call decision.

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

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

Schema coverage is 100% and the parameter descriptions already define the aliases, so the description does not need to repeat them. It adds no special parameter guidance beyond the natural-language question intent, which the schema already covers. 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 names a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and contrasts it with its sibling 'Same routing as ask_pipeworx'. It clearly states what the tool does: route to a source, fetch data, extract an answer only from tool results, and return evidence or an explicit refusal.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and gives the selection heuristic: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral detail: safety (low-confidence short-circuits), closed market handling, spread warnings, cancellation rule parsing, news fallback/retry. 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?

Very detailed but verbose; multiple paragraphs. However, well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with purpose. Some details could be condensed or moved to output schema.

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?

Complex tool with many fan-out paths, response shapes, resolver contract, parent event extraction, news fields, safety checks, and resolution-rule risk. Description covers all these comprehensively without output schema. No gaps noted.

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 100% with each parameter described. Description adds context for market parameter (resolve market, classifiers, fan-out examples) and briefly explains depth and include_raw beyond schema. Enriches understanding without repeating 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?

Clear verb 'Research' with specific resource 'Polymarket bet' and explicit inputs (slug, URL, question text). Distinct from siblings like ask_pipeworx by targeting betting edge 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?

Explicitly states when to use ('should I bet on X', 'what does the data say', 'is there edge') and provides numerous examples. Also mentions when not to proceed (low-confidence match, closed markets).

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. Description adds significant behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradiction with annotations.

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

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

Description is slightly long but front-loaded with example queries. Every sentence adds useful information, such as data sources, sorting, and output. No redundancy. Could be more compact, but efficient given the tool's complexity.

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

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

For a comparison tool with two entity types, external data sources, and specific output, the description is thorough. It explains data sources, edge cases (off-calendar fiscal years), sorting behavior, and return format (paired data + URIs). No output schema exists, so description fully covers return value.

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. Description adds value: for 'type', it explains what data each enum pulls; for 'values', it gives examples and constraints (tickers/CIKs vs drug names, 2-5 items). This provides more semantic meaning than schema alone.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs, citing specific examples like 'X vs Y' and 'compare these companies'. It distinguishes from siblings by explicitly preferring over sequential single-pack lookups and noting it replaces 8-15 lookups, differentiating it from entity_profile and deep_research.

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

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

Explicitly tells when to use: comparisons, ranking, head-to-head. Includes 'ALWAYS PREFER over sequential single-pack lookups', giving clear context for optimal usage. While not explicitly stating when not to use, the context implies it's for comparisons only, which is sufficient.

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

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

The annotations declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: retry/decomposition flow, gaps[] instead of invented findings, contradictions[], semantic excerpting, citation_uri fetchability, and expected latency up to ~90s. This is exactly the kind of behavioral context an agent needs.

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

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

The description is dense but every sentence contributes substantive guidance, with high-value routing and account constraints in the opening clause. However, the single wall-of-text paragraph makes some important caveats easy to scan past, so it costs a point on structure.

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 present, the description correctly carries the burden of describing the return packet: evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop. Combined with auth, latency, and alternative-route guidance, this is complete enough for a correct call.

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

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

The input schema already documents both parameters thoroughly, including each depth enum value, paid status, and what 'question' expects. The description repeats much of this and adds latency/account-gating context, but does not add meaningful parameter-level semantics beyond the schema, so the 100%-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 states a specific verb and resource: grounded multi-source research across 1465 STRUCTURED data sources, and explicitly says this is NOT open-web search. It also names ask_pipeworx as the single-lookup alternative, so an agent can immediately distinguish the tool 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?

It provides explicit when-to-use guidance: broad/multi-part questions over structured data, with clear exclusions for single lookups and current-news topics. It also routes signed-out or non-paid users to ask_pipeworx instead of deep_research, covering auth constraints.

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, no destructiveness. Description adds that results include full schemas with examples and are ready to call, plus guidance to use first. No contradictions.

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

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

Two well-structured sentences. The first states purpose, the second lists domains and return details. Slightly long but justified by the exhaustive domain list. Front-loaded.

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

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

Given the simple input and no output schema, the description fully explains what the tool does, when to use it, and what it returns. Annotations cover safety. Complete.

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

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

Schema description coverage is 100% and the description does not add much beyond what the schema already provides. The baseline of 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, and lists specific domains. It distinguishes itself from sibling tools (which are individual data tools) by being a meta-discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context but does not name specific alternatives.

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

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

Annotations already declare read-only and idempotent. Description adds specifics: fans out across sources, soft-fails for patents, returns up to 5 filings, and does not support names. 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?

Description is long but well-structured with examples first, then details. Every sentence adds value; slight verbosity justified by complexity.

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

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

For a complex tool with no output schema, description comprehensively covers inputs, outputs (fields like cik, filings, fundamentals), behavior (soft-fail, sorting), and limitations. Complete enough for correct agent invocation.

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

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

Schema coverage is 100% with descriptions. Description adds context: 'zero-padded CIK', 'names not supported', and enum restriction. Improves clarity beyond schema.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company, with examples like 'tell me about X' and contrasts with chaining single-pack lookups. This distinguishes it from siblings like compare_entities or resolve_entity.

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 ALWAYS PREFER over chaining for holistic views, advises using resolve_entity for name-only inputs, and implies not for single facts. Provides clear when-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about deleting previously stored memories and clearing sensitive data, reinforcing behavioral traits without contradiction.

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

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

Two concise sentences: first sentence states core action, second provides usage guidance. 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?

Simple tool with one required parameter, no output schema, and annotations covering destructiveness. Description fully covers usage context and pairing, making it complete for agent invocation.

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

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

Schema coverage is 100%, and the parameter description 'Memory key to delete' is sufficient. The description does not add new parameter-level details beyond the schema, meeting 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?

Clearly states 'Delete a previously stored memory by key' providing a specific verb and resource. Distinguishes from sibling tools remember and recall by pairing with them.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Mentions pairing with remember and recall for context. No explicit when-not-to-use, but positive guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown format. 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 concise (4 sentences) and well-structured: purpose, process, output, use cases. Every sentence adds value 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?

Given the tool has 2 parameters with full schema coverage, no output schema, and annotations present, the description is fairly complete. It explains what is generated (single text blob) and mentions the format. Minor lack of details about error handling or accessibility requirements, but sufficient for a simple generation 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?

Both parameters are described in the schema (100% coverage). The description adds meaning by specifying the default value (25) and maximum (50) for max_links, which is not in the schema. It also clarifies the URL parameter as 'Full URL of the site to summarize'.

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 generates a production-ready llms.txt file for any URL, identifies the resource (URL) and action (generate), and distinguishes from sibling tools by focusing on AI crawler indexing. No ambiguity.

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

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

Explicit use cases are provided (getting client's site indexed, drafting for own project, auditing competitor). Though no explicit when-not-to-use or alternatives are given, the sibling list contains no similar tool, making the guidance clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds context about return fields and API key requirement, but does not cover pagination or error handling.

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

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

Two sentences, no wasted words, effectively communicates purpose and prerequisites.

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 output schema present, description adequately explains return data. Missing details on pagination or limit behavior, but acceptable for a simple GET tool.

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

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

Input schema covers all parameters with descriptions. Description does not add new meaning beyond what is already in the schema.

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

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

Description clearly states it gets NBA games for a season, returning specific fields. Distinguishes from sibling tools like get_player and get_teams by focusing on games.

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?

Implies usage for retrieving NBA game data but does not mention when to use this versus alternatives like search_players or other game-related 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, idempotentHint, etc. Description adds the critical tier restriction (403 response) and that metadata content overlaps with search_players. No contradictions.

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

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

Two sentences, no filler. First sentence states purpose, second provides usage guidance, tier warning, and alternative. Every word earns its place.

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

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

Given tool simplicity (single lookup by ID), presence of output schema, and annotation coverage, the description covers purpose, usage, and constraints. No significant gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. Description doesn't add much beyond relabeling 'id' as 'BallDontLie player ID' and 'apiKey' as API key, which matches schema. Baseline 3 is appropriate.

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

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

Description clearly states 'direct lookup of a single NBA player by BallDontLie ID'—specific verb, resource, and identifier. Distinguishes from sibling search_players which serves a different use case.

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

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

Explicitly advises when to use this tool vs search_players: prefer search_players on free tier unless paid key is available. Also warns about tier-gated endpoint with specific error code.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds the API key requirement and indicates the static nature of teams. No contradictions.

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

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

Two sentences, no redundancy, front-loaded with action and key details. 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 simplicity (1 param, output schema exists), the description covers purpose, usage, and auth. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a clear description for the _apiKey parameter. The description repeats 'Requires a free BallDontLie API key' but adds no new semantic detail 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?

Description explicitly states 'Get all 30 NBA teams with full names, abbreviations, conference, and division,' providing a specific verb and resource. It clearly distinguishes from sibling tools like get_games and search_players.

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

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

Description advises 'Use to find team info or prepare for get_games queries,' giving clear context. It also specifies the API key requirement. Missing explicit exclusions but sufficient for this simple 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, openWorldHint, idempotentHint, destructiveHint=false. Description adds context that only active subscriptions are returned by default (param to include inactive) and lists return fields. No contradictions.

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

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

Two succinct sentences covering purpose, return fields, and usage guidance. No superfluous 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?

Tool is simple with one optional param and no output schema. Description lists return fields, making it complete enough for an agent to select and call the tool. The param is well-documented.

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

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

Schema has 100% coverage with one boolean parameter (include_inactive). Description implies default behavior (active only) and that the param controls inclusion of cancelled subscriptions, which adds meaning beyond the schema 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?

Description clearly specifies 'List the caller's active subscriptions' and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies when to use (before adding subscriptions or to get an id for cancellation) but does not explicitly state when not to use or list 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?

Despite annotations (readOnlyHint=false, etc.), the description adds critical behavioral context: rate-limiting ('5 per identifier per day'), the claim_token return flow, daily digest reading, and that it is free and 'doesn't count against your tool-call quota.' 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 longer than average but every sentence carries essential information—scope, usage exclusions, feedback types, claim_token mechanics, rate limits, and cost. It is front-loaded with the core purpose and organized logically, with no redundant fillers.

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 (async feedback, claim_token flow, exclusions, rate limits), the description covers all necessary context. No output schema exists, but the description explains the claim_token return and resolution status, so the agent understands the full interaction lifecycle.

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 covers all parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying that reading a reply requires no other arguments, which is beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and distinguishes itself from siblings by explicitly scoping to Pipeworx tools only, unlike ask_pipeworx or other query 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?

It provides explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and explicitly excludes tools from other MCP servers with an alternative ('file it with that server instead'). It also instructs what to include (Pipeworx tools/packs, not user prompts) and how to use claim_token for follow-up.

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 valuable behavioral details: caching (5min-1h), data source (CF analytics engine), no PII, and self-aggregating nature. 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 concise with three clear sentences: main purpose, use cases, and technical details. Every sentence adds value, and the structure is front-loaded with the primary function.

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

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

Despite lacking an output schema, the description adequately explains what is returned (top tools, top packs, total call volume). It also covers caching behavior and data privacy, making it complete for a simple read-only tool with one parameter.

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

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

The single optional parameter (window) has an enum and schema coverage is 100%. The description enriches the enum values by explaining that shorter windows surface hot trends while longer windows show steady-state demand, adding 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 returns trending data (top tools, top packs, call volume) over specified windows. It uses specific verbs and resources, and the purpose is distinct from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming popular tools, checking use case alignment). It does not explicitly mention when not to use or contrast with siblings, but the context is clear enough for an AI agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds extensive behavioral details: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (realizable edge), and response structure. This goes well beyond what annotations provide.

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

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

The description is thorough but verbose, with several paragraphs of details that could be condensed. While structured with headings, it includes precise thresholds (e.g., 0.30 Jaccard, 3pp, 20%) that may be more than needed for initial understanding.

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

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

Given the absence of an output schema, the description thoroughly explains the response format (opportunities array, partition_check object, fill_check details). It also covers both input modes and edge cases, making it complete for agent 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?

The input schema already describes both parameters with 100% coverage. The description adds value by providing example values, explaining that full URLs are accepted, and clarifying the behavioral difference between event and topic modes.

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

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

The description explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and clearly distinguishes three modes (no args for trending scan, event for specific market, topic for cross-event). This differentiates it from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode and includes warnings about fill checks and when not to trade. However, it does not directly compare to alternative tools or state when to avoid using this tool.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, no destructiveness. The description adds significant behavioral context: caching (1h KV-level), model details, edge calculation, diagnostics output. 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 verbose and dense, including detailed model formulas and output structure. While well-structured with sections and front-loaded purpose, it could be more concise. A 3 reflects adequate but somewhat excessive length.

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

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

With no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields. It handles edge cases like empty segments via filter_skips. For a complex tool, this is remarkably complete.

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

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

Schema coverage is 100%, so the input schema already documents each parameter. The description adds some context via 'Tradeable-edge knobs' and mentions knobs, but does not substantially enhance semantics beyond the 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with the explicit purpose 'what should I bet on today'. It distinguishes itself from siblings by detailing unique model families and segments, making the purpose specific and actionable.

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: 'agents discover opportunities without paging hundreds of markets' and explains when to use tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or provide 'when not to use' guidance, hence a 4.

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 extensively discloses behaviors: history bound by 60-day TTL, snapshot gaps due to cache misses, decay calculated from daily closes (not intraday), and detailed response structure. This adds significant context beyond the annotations (readOnly, idempotent, openWorld), which already indicate safety. No contradictions.

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

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

The description is front-loaded with the key purpose and each subsequent sentence adds value, but it is somewhat verbose with detailed response fields. It could be slightly more concise without losing clarity, but overall well-structured for a complex 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?

Given the tool's complexity and lack of output schema, the description fully details the response arrays (tracked, expired, snapshot_dates) with field explanations and limitations (60-day TTL, cache-miss gaps, intraday vs daily close). It is complete for agent invocation.

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

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

Schema coverage is 100% with descriptions already explaining defaults and clamping for days, and the window family for window. The description reiterates defaults and lists example values but does not add substantial new meaning beyond the schema, earning the baseline 3.

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

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

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

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

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

The description implies usage context by contrasting fresh wide edges with old wide edges, highlighting the tool's value for assessing edge decay. However, it does not explicitly state when to use this tool over alternatives (e.g., polymarket_edges) or provide conditions to avoid, so some guidance is left implicit.

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 and idempotentHint, but description adds significant behavioral details: walks the ladder, returns top_of_book, vwap_fill_price, slippage, verdict, thin_legs, forced_directional_risk. No contradiction; description enriches beyond annotations.

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

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

Description is verbose (two long paragraphs). While it front-loads purpose and modes, it could be more structured with bullet points or shorter sentences. Every sentence adds value, but overall density is high.

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

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

No output schema, but description thoroughly lists return fields for both modes and explains verdict and risk legs. Provides context on when to use and potential pitfalls. Missing explicit exchange mention but implicit from name and sibling tools.

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

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

Schema coverage is 100% (baseline 3), but description adds important semantics: explains how size_usd is interpreted for basket mode (settlement notional), side auto-detection for basket, and default values. Adds value beyond schema.

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

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

Description clearly states it checks realizable-vs-theoretical edge against live order book depth, with two distinct modes (single-market and basket). It strongly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fillability, not just theoretical edge.

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

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

Explicitly tells when to use: before acting on polymarket_arbitrage signals or trades above ~$500. Explains why: theoretical overround on thin books is not capturable and partial fills cause directional risk. Provides clear context and exclusions.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral context: compatibility_warning triggers, temporal_alignment field, skipped_cross_type counters, and the rarity of real spreads. No contradictions.

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

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

Description is lengthy but well-organized with sections for modes, response fields, and safety fields. Every sentence contributes, though slight trimming could improve conciseness.

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

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

No output schema exists, so description must cover return values. It thoroughly explains leg prices, top_spreads_pp, safety fields, and warning conditions, providing complete context for agent decision-making.

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

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

Schema coverage is 100%, so description need not repeat. The description adds value by explaining the two modes and the overriding behavior of explicit tickers over topic shortcuts.

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 computes cross-venue spread between Kalshi and Polymarket, detailing two modes (topic shortcuts and explicit tickers) and output format. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on venue comparison.

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

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

Explicitly explains when to use (comparing same question across venues) and warns that most pre-mapped topics yield compatibility warnings. Provides detailed conditions where spreads are meaningful vs. not, such as temporal alignment and bet shape equivalence.

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, so the description adds value by explaining the listing behavior when key is omitted and the scoping to user identifier. No contradictions.

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

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

The description is efficient: three sentences, front-loaded with the core action, and no extraneous information. Every sentence contributes meaning.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and thorough annotations, the description fully covers purpose, usage, scoping, and behavior. No gaps.

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

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

The input schema covers all parameter details (100% coverage), but the description adds important nuance: omitting the key lists all saved keys. This goes beyond the schema's 'omit to list all keys' comment by explaining the behavioral effect.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when the key argument is omitted. It provides concrete use case examples (ticker, address, research notes), making the purpose 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?

The description explicitly tells when to use the tool ('to look up context stored earlier') and mentions pairing with 'remember' and 'forget' for save/delete operations. It lacks an explicit comparison to alternatives but the context is clear enough.

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

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

Annotations declare readOnlyHint=true, but the description states mark_read:true flags events as read, which is a write side effect. This is an annotation contradiction, severely reducing transparency score despite the description being otherwise clear.

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

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

The description is concise—three sentences that start with purpose, add key details, and end with alternative access. Every sentence adds value and is 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?

Given no output schema, the description covers return fields (source, citation_uri, payload) and the mark_read side effect. It also mentions polling compatibility and an alternative URL. However, the 'raw event payload' is vague, and the response format could be more explicit.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving an example for type ('sec_8k') and specifying since as ISO timestamp, but these are minor additions beyond the schema's own 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 'Pull fired events from your subscription feed,' specifying a clear verb and resource. It also identifies key return fields (source, citation_uri, payload). However, it does not differentiate from sibling tools like list_subscriptions, which may serve a similar 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 usage guidance: mentions an alternative endpoint for scripts/dashboards, explains mark_read usage for sequential polling, and clarifies that polls work fine. It does not explicitly state when to use this tool over siblings but offers practical 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 indicate safe, idempotent behavior. Description adds valuable context: multi-source fan-out, GDELT-to-GNews fallback, PatentsView soft-fail, and return structure including pipeworx:// URIs.

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

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

Description is a single paragraph but well-structured, starting with purpose and usage examples. Every sentence contributes information; no fluff. Slightly long but appropriate for the tool's complexity.

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

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

Given the complex multi-source nature and no output schema, the description adequately explains return structure (changes[], total_changes, citations), fallback logic, and limitations (PatentsView soft-fail). Complete for agent use.

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

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

Schema covers all parameters. Description enhances understanding by explaining accepted formats for 'since' (ISO date or relative shorthand) and providing example values for 'value' (ticker or CIK). Minor extra value.

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

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

Description clearly defines the tool as a change feed for companies, listing specific sources (SEC, news, patents) and explicitly distinguishes it from entity_profile, which provides static profile data.

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

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

Description provides explicit guidance on when to use this tool (dynamic changes) versus entity_profile (static profile), and includes example queries and fallback behavior explanation.

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

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

Description adds details beyond annotations: key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users (persistent vs 24-hour retention). No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Single paragraph is well-structured, starting with purpose, then usage, then technical details. Every sentence adds value; no wasted words.

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

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

Given no output schema, the description fully explains input, behavior (persistence rules), and pairing with other tools. No gaps remain for the tool's intended use.

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

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

Schema coverage is 100%, with key and value descriptions already clear. Description adds examples and context like 'any text' for value, but adds minimal meaning beyond schema. Baseline 3 applies.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'Save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by mentioning pairing, and provides concrete examples of use cases.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and gives examples. It doesn't include when not to use, but contrasts with recall and forget, providing sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context beyond annotations: graceful degradation when GLEIF/OpenFIGI are unavailable, cascading internal lookups, explicit treatment of unresolved identifiers, and the fact that it replaces 2-3 manual lookups. 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 front-loaded with query examples and key guidance ('Use FIRST'). While it is lengthy, each clause adds valuable information (supported sources, edge case handling, output structure). Minor redundancy in listing identifier types but overall earns its length.

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

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

Despite no output schema, the description comprehensively covers what the tool returns (canonical IDs with source labels, unresolved field) and handles edge cases (graceful degradation, ISIN-to-LEI mapping for non-US issuers). Given the tool's complexity (multiple lookup engines, two entity types), the description is fully sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by elaborating on the 'company' type (cross-source identity spine, supported input formats like ISIN) and the 'drug' type (returns RxCUI + ingredient + brand with citation). It also provides concrete examples for the 'value' parameter, adding practical context beyond the schema.

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

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

The description starts with concrete example queries (ticker, CIK, LEI, RxCUI) and clearly states the tool's purpose: resolve a name to canonical identifiers required by other tools. It explicitly lists supported types (company, drug) and implicitly distinguishes from siblings by positioning itself as the first step when an ID is needed.

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

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

The description gives clear usage guidance: 'Use FIRST whenever you have a name but need an ID.' It provides numerous example queries showing when to invoke it. However, it does not explicitly mention when NOT to use it or name alternative sibling tools (e.g., search_within, entity_profile) for edge cases.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds valuable behavioral context: it probes each entity using 'ai_visibility_check', ranks by score, and returns a list with score, confidence, signal density. No contradiction with annotations.

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

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

Five sentences, each earns its place. Front-loaded with the main purpose, then explains how it works, gives a use case, and specifies return value. No redundant or vague phrasing.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). The tool complexity (4 params, composite with another tool) is well covered. Minor omission: no mention of error cases or rate limits, but not essential.

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

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

Although schema coverage is 100%, the description adds critical nuance: 'First entry treated as the subject for narrative; rest are competitors.' It also clarifies the purpose of the 'context' parameter with an example. This goes beyond the schema's basic type descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, ranks them, and identifies the most/least recognized. It distinguishes itself from the sibling 'ai_visibility_check' by being a composite batch tool for competitive 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 says it's useful for competitive AI-marketing audits and gives a concrete question example. It does not explicitly mention when not to use it or list alternatives, but the context of comparing multiple entities is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: partial failure handling (bundlephobia timeout up to 30s, sources_failed listed), and the return format (summary block with specific fields, advisories, links, alternatives). 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, front-loading the main purpose and then adding behavioral and usage details. Every sentence provides necessary 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 the tool's complexity (composite check across multiple sources), lack of output schema, and rich annotations, the description is comprehensive. It explains the return format (summary block with specific fields, advisories, links, alternative versions), failure modes (graceful partial failures), and ecosystem limitations.

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% (both package and version described in schema). The description adds context beyond schema: scoped packages are accepted, and version defaults to latest published. This extra guidance improves 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 it's a composite check for npm packages combining deps.dev and bundlephobia data. It uses specific verbs and resources ('scan_dependency', 'fans out across deps.dev... and bundlephobia'), and distinguishes from siblings by noting 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides guidance on alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Discloses exactly what is returned (position, height, weight, etc.) and what is NOT (per-game averages, career stats). Aligns with annotations (readOnly, idempotent, non-destructive). Adds context about API key tier and external endpoint limitation.

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

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

Description is well-organized with examples, but slightly verbose with multiple example phrases. Each sentence adds value (purpose, exclusions, API key note). Could be more concise without losing 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?

Given the tool's search nature and output schema existence, the description fully explains the return values, limitations, and prerequisites (API key). The warning about missing stats ensures the agent understands the scope.

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

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

Schema covers all parameters with descriptions (limit, query, _apiKey). The description adds no additional parameter-level details beyond the schema, but it does note that the free _apiKey works. Since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description clearly states it searches NBA players by name on BallDontLie, lists returned fields (position, height, weight, etc.), and distinguishes itself by noting that per-season averages are not included. Examples like 'Find NBA player [name]' clarify usage.

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

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

Explicitly says when to use (search players by name) and when not (if stats needed, use /season_averages endpoint not exposed). Mentions free-tier _apiKey works and provides example queries. Differentiates from siblings by stating what data is absent.

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

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

Description adds behavioral details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' No contradiction with annotations (readOnlyHint, etc.).

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

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

Two sentences effectively conveying purpose and key technical details. Front-loaded with purpose, but includes implementation specifics that are relevant.

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 3 parameters and no output schema, the description covers input constraints, pairing with sibling, embedding model, window size, truncation, and return components (passages with offsets and similarity scores). Very complete.

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

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

Schema coverage is 100% with parameter descriptions. Description repeats the same info for 'text' and 'query', and does not mention 'limit' parameter. No additional value beyond schema, so baseline 3.

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

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

Description clearly states 'Semantic search INSIDE a fetched record,' specifying the resource (fetched record) and action (semantic search). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and grounding over passages.

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: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Clearly explains when to use and suggests alternative.

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

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

The description discloses behavioral traits beyond annotations: requires OAuth, phone verification for SMS, rate limit of 10/day, and delivery channels. Annotations already indicate it is not read-only and not destructive. However, it does not clarify idempotency behavior despite the idempotentHint annotation, missing an opportunity.

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 relatively long but well-structured: purpose, requirements, types, and delivery details are clearly separated. Front-loaded with key information, though slightly verbose; every sentence adds value.

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

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

Given the tool's complexity (multiple types, nested params, no output schema), the description covers most aspects but lacks details on the response structure beyond returning a subscription id. It does not specify whether the response includes status, errors, or additional metadata, which would be helpful.

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

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

Schema coverage is 100%, and the description adds significant value with detailed examples for each subscription type and delivery option. It explains type-specific params (e.g., sec_8k items, polymarket_edge topic) and delivery constraints (e.g., webhook signing secret, SMS verification).

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 creates a subscription to a live-data event stream and returns the subscription id. It specifies the verb 'Create' and the resource 'proactive monitoring subscription', differentiating it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use the tool, including the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist. It implies alternatives (e.g., recent_alerts for pulling) but does not explicitly state when not to use or compare with all 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the tool returns category-bucketed example questions with exact tool+argument shapes, and is drawn from a live catalog. No contradictions.

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

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

Well-structured: starts with common queries, states purpose, lists categories, explains arguments, and gives usage order. Every sentence adds value; 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 an onboarding tool with no output schema, the description fully explains what the tool returns (example questions with tool+argument shape) and covers all necessary context. Agent can decide to use it immediately.

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 covers 100% and gives topic options. Description adds value by explaining what happens when omitted (full spread) and gives additional examples, but mostly reinforces schema. Slightly above baseline due to clear omission behavior.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns example questions with tool call shapes. It distinguishes itself from siblings (like discover_tools, ask_pipeworx) by focusing on suggesting questions rather than executing them.

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

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

Explicitly tells when to use ('Use this FIRST when you do not yet know what Pipeworx can do') and provides guidance on arguments ('Call with no arguments for the full spread, or pass topic'). Mentions meta-tools as related.

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 mutation but not destruction; description adds that row is deactivated not deleted, preserving historical events. Also discloses ownership enforcement.

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

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

Two sentences, no wasted words, front-loaded with action and clear structure.

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

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

Simple tool with one parameter; description explains behavior (deactivation, history preservation) adequately despite lack of output schema.

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

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

Schema covers 100% of parameters with description; description adds that id is returned by subscribe, which is useful context beyond schema.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Specifies ownership enforcement and that id must come from subscribe. Provides clear context for when to use, though no explicit when-not or alternative mention.

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

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

Beyond the read-only, idempotent, open-world annotations, the description reveals detailed behavior: the two execution paths, the exact verdict vocabulary, the distinction between could_not_verify (technical failure) and unsupported (no source), and the presence of citation and reasoning in the output. This is substantial behavioral context that annotations alone do not 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 fairly long but dense with useful information: examples, routing logic, return semantics, and a critical caller note. Each sentence serves a purpose, and the structure is logical, though slightly heavier than a minimal tool description would require.

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 and the absence of an output schema, the description fully compensates by explaining the return value structure, verdict types, error semantics, and the 'replaces 4-6 sequential calls' efficiency benefit. It is complete enough for an agent to successfully invoke 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?

The input schema already describes both parameters with 100% coverage. The description adds extra meaning for tolerance_pct by explaining it overrides wording-derived tolerance and recommending values for hallucination detection, and it provides illustrative examples for the claim parameter. This goes beyond the schema's baseline.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with a specific verb ('validate') and resource (claims). It distinguishes itself from general search/research tools by focusing on verdicts and explicitly contrasts the financial (SEC EDGAR) and grounded pipelines.

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

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

It provides explicit usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes internal routing logic for financial vs. non-financial claims, giving clear guidance on when to use the tool. However, it does not explicitly name sibling alternatives 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.