Nhl

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds operational context: default model is free, Anthropic requires a passed-through API key, and the tool returns per-model scores with raw responses. It does not contradict annotations and provides useful behavioral traits beyond the schema.

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

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

The description is three sentences, each serving a purpose: first sentence defines the action and scoring, second details model options and API key usage, third describes return structure and use cases. It is front-loaded with the core purpose and contains no fluff.

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

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

The description covers return format (per-model and combined), parameter descriptions, and use cases. Given no output schema and moderate complexity, it is fairly complete. Could mention error handling or rate limits, but it provides sufficient context for an agent to understand the tool's function and output.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds significant meaning: it explains the scoring range, that the default model is free, that _apiKey is only needed for Anthropic, and that context disambiguates entities. This enriches the parameter semantics substantially.

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 brand visibility and scores them 0-100. It identifies the specific resource (LLMs), action (probe and score), and distinct use cases (AI-marketing audits, pre-launch checks, competitive monitoring), differentiating it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description lists use cases and explains default model vs BYO key for Anthropic, providing context on when to use it. However, it does not explicitly state when not to use it or contrast with sibling tools, leaving some room for ambiguity.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: routes to one of 5,313 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. 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 the key directive (prefer over web search) and well-organized. It is somewhat long due to the extensive example list and tier notes, but every section earns its place by clarifying usage. Slightly more verbose than strictly necessary, but not wasteful.

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

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

For a broad query tool with no output schema, this description is remarkably complete. It defines the tool's scope, expected answer format (structured, cited), when to use it, when to use alternatives, and covers many domains. The agent has enough context 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 six aliases for the same required question field, so the baseline is 3. The description contributes beyond schema by giving concrete example queries ('current US unemployment rate', 'Apple's latest 10-K') and phrase triggers ('what is', 'look up', 'find'), which helps the agent formulate a good question.

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 this tool answers factual questions about current/historical data across many domains, returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research and explaining when to use each.

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

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

Extremely explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', concrete trigger phrases, and numerous examples. It also gives escalation paths to alternatives for grounded answers and deep research, plus notes about breaking news routing.

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

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

Annotations already provide read-only, idempotent, open-world, and non-destructive hints. The description adds valuable behavioral context: it is experimental, may change routing behavior when candidates are under test, and currently matches ask_pipeworx exactly. This goes beyond the annotations by explaining the beta status and the comparison process, though it does not detail every possible behavior.

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

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

Three sentences pack in all essential information: identical to ask_pipeworx, experimental routing, current state, usage direction, and reassurance about fallback. Slightly long but every clause earns its place; no fluff.

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

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

For a tool with a simple schema and no output schema, the description is highly complete. It explains the tool's essence, its relation to ask_pipeworx, its current experimental state, and what the agent should expect. No gaps found.

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 has full coverage: 6 parameters are aliases for question, and their descriptions are clear. The description does not add additional parameter details, but since schema coverage is 100%, no compensation is needed. 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 is a 'Beta version of ask_pipeworx: identical universal router' with the same tools, arguments, and response shape. It also distinguishes itself from the sibling ask_pipeworx by mentioning candidate routing improvements and experimental status, so the agent understands exactly what this tool does and how it relates to siblings.

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

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

Explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router and notes that results are compared to decide merges, providing clear context for choosing this over the stable alternative. No misleading guidance.

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

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

The description discloses the exact return contract including refusal reasons, the fact that answers are extracted only from tool results, and the extra LLM call cost, going beyond the read-only/open-world/idempotent annotations. This gives high behavioral transparency.

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

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

Every sentence earns its place—purpose, routing, output format, usage, and cost are delivered in a compact, front-loaded structure. It is appropriately detailed without being verbose.

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

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

No output schema exists, so the description compensates by fully specifying the success and refusal return shapes with refusal reason enums. It also covers lifecycle context (same routing as ask_pipeworx, extra call cost), making it complete for safe 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?

The input schema already documents all six properties as aliases for the natural-language question with 100% coverage, so the description does not need to add parameter detail. Baseline 3 is appropriate.

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

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

The description clearly defines a hallucination-resistant answer mode for high-stakes reads, distinguishing it from sibling ask_pipeworx via the grounded extraction and explicit refusal mechanism. The verb 'Ask' plus the mode explanation gives specific 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?

Explicitly states when to use: when answers will be quoted, cited, or acted on, and when not to (casual lookups). Names the alternative (ask_pipeworx) and gives a cost trade-off, providing clear decision guidance.

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

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

The description extensively details behavior beyond annotations: response shapes (market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent_event extractor, news fields with fallback logic, safety mechanisms (low-confidence short-circuit, closed market handling), and resolution-rule risk. Annotations indicate read-only, idempotent, non-destructive, which aligns with the description.

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

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

The description is thorough but lengthy. It is well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.), but could be more concise. Every sentence adds value, but the overall length may hinder quick comprehension.

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

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

Given the complexity of the tool, the description is exceptionally complete. It covers input variations, processing logic, output structure, error cases, safety mechanisms, and edge cases (closed markets, wide spreads, resolution risks). No output schema exists, but the description compensates comprehensively.

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

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

Schema coverage is 100%, so the description adds moderate value. It repeats parameter descriptions but enriches them with fan-out examples per category (e.g., BTC bet → coingecko + fred + gdelt+gnews), which clarifies how the 'depth' parameter affects behavior beyond the schema's simple definition.

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: researching a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and outputs (evidence packet, comparison). The verb 'research' distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which have different focuses.

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: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, the description does not explicitly exclude scenarios where sibling tools would be more appropriate, missing a chance to differentiate.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent with the description. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and inclusion of citation URIs. 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 somewhat lengthy but well-structured and front-loaded with core purpose. It efficiently packs essential information without unnecessary repetition. Some brevity could be achieved, but it's justified by 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?

Without an output schema, the description adequately covers return information ('paired data + citation URIs') and explains the specific data fields for each entity type. The level of detail is sufficient for an agent to understand the output, though a bit more structural detail could help.

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. The description adds value by providing concrete examples (tickers/CIKs for company, names for drug) and explaining the enum choices, going beyond the schema's basic 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: side-by-side comparison of 2-5 companies or drugs. It uses explicit examples like 'Compare X and Y' and distinguishes itself from sibling tools by recommending preference over sequential single-pack lookups.

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

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

The description provides clear when-to-use guidance with example queries and explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lacks explicit exclusions but context implies single entity lookups should use entity_profile.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses account requirements, latency expectations (15-60s, up to ~90s), response structure (findings packet with evidence, confidence, gaps[], contradictions[]), and processing behavior (parallel decomposition, semantic excerpting, hop fields). It explicitly states the tool 'never invented' answers for gaps, adding trust-critical context.

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

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

The description is lengthy but densely informative, covering auth, use cases, alternatives, behaviors, and output structure. It is logically organized from account requirement to use cases to iteration depth and timing. Some redundancy with the schema's depth description exists, but the additional behavioral details justify the length for such 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?

With no output schema, the description fully explains return values: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', 'explicit gaps[]', 'contradictions[]', and 'hop' fields. It also addresses failure modes (gaps for unanswered facets, empty results for non-catalog topics) and performance expectations. Given the tool's complexity, the description is exceptionally 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% for both params, and the depth param already includes a thorough enum description in the schema. The tool description adds contextual notes (e.g., 'depth:"thorough" needs a paid plan') but does not materially enhance meaning beyond the schema's existing depth details. The question param is well described in schema as broad/multi-part, which the description reinforces but doesn't expand.

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

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

The description clearly defines the tool as a multi-source research engine over Pipeworx's structured data sources, with explicit verb+resource ('Grounded multi-source research across...') and a detailed output packet. It distinguishes itself from siblings by contrasting with ask_pipeworx for single lookups and current news, clarifying that this is not open-web search. The scope and behavior are 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 provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states account prerequisites and fallback if not signed in, leaving no doubt about appropriate invocation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that the tool returns top-N tools with full schemas and examples, ready to call directly—this is valuable behavioral context beyond annotations. 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 comprehensive but slightly verbose. It front-loads the purpose and includes all key information. Every sentence adds value, though it could be tightened slightly.

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

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

No output schema exists, but the description clearly explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This is complete and eliminates ambiguity.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description mentions aliases for query but adds minimal extra meaning beyond the schema's descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explicitly positions this as a first-call discovery tool, distinguishing it from sibling tools that are specialized.

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 when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This effectively tells the agent when to invoke this tool versus others.

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

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

Adds behavioral details beyond annotations: patents API sunset soft-fail, max 5 filings, sorted fundamentals, and multi-source fan-out. Annotations already indicate read-only, idempotent, non-destructive, so description adds useful context 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?

Description is well-structured and front-loaded with key purpose. Each sentence adds value, though slightly dense with multiple data points; could be slightly more streamlined but overall effective.

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

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

Despite no output schema, description covers all return fields with sources and ordering. Also mentions soft-fail for patents and gives example inputs. Complete for the complexity level.

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 meaning: explains value can be ticker or zero-padded CIK, notes names not supported, and clarifies type is only 'company'. This enriches the schema definitions.

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

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

The description clearly states it provides a full cross-source profile of a US public company in one parallel call, listing specific data points (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from sibling tools like compare_entities and 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 to prefer this over chaining single-pack lookups for holistic views, and notes that names are not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and stale context, reinforcing behavioral understanding without contradiction.

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

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

Two sentences, no fluff. Front-loaded with action and key detail, then usage guidance. 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?

Tool is simple with one required param and no output schema. Description sufficiently covers purpose, usage context, and relationships to siblings. No gaps for an agent to misinvoke.

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 description for 'key' parameter. Description does not add extra meaning beyond schema, so baseline score of 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?

Description clearly states 'Delete a previously stored memory by key', specifying action and resource. Siblings include 'remember' and 'recall', making its unique role distinct.

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

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

Explicitly says when to use: when context is stale, task done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall', providing clear guidance vs alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown format. This goes beyond annotations by explaining the process and output.

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

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

The description is a single, well-structured paragraph. It first states the core action, then the process, then the output, and finally use cases. Every sentence adds value with no redundancy or fluff.

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

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

Despite no output schema, the description specifies the output format ('single text blob ready to drop at site-root/llms.txt'), which is sufficient for the tool. With clear annotations, full schema coverage, and a comprehensive description, it provides complete context for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add additional meaning beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description specifies the verb 'generate', the resource 'llms.txt file', and the target 'for any URL'. It distinguishes from sibling tools like ai_visibility_check by focusing on file generation rather than inspection. The purpose is clear and specific.

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

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

The description lists explicit use cases (indexing a client's site, drafting for own project, auditing competitor). It does not explicitly state when not to use it or name alternatives, but the examples provide strong contextual 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns specific data fields, but does not disclose any additional behavioral traits such as rate limits, caching, or error behavior.

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

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

The description is a single sentence that front-loads the core purpose and then specifies return content. Every word is informative; there is no fluff or 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 simple single-parameter tool with an output schema (has output schema: true) and safety annotations, the description covers all necessary aspects: what it does, how to call it (by ID), and what to expect in return. No gaps are apparent.

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 sole parameter playerId is documented in both the tool description and schema (100% coverage). The schema provides an example and explanation, which adds meaning beyond the parameter name. The description reinforces the parameter's purpose without redundancy.

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

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

The description uses a specific verb 'Get', identifies the resource 'NHL player's profile and current season stats', and lists key output components (bio, position, team, season statistics). It clearly distinguishes from sibling tools like get_schedule or get_scores.

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 clearly states it fetches player data by ID, but does not explicitly mention when to use this tool over alternatives like entity_profile, nor does it provide exclusions or prerequisites. The usage context is implied but not explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the tool's safety and behavior are covered. The description adds that it returns 'upcoming and recent games with teams, dates, times, and venues', which provides useful context but does not conflict with annotations.

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

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

The description is a single, clear sentence with no unnecessary words. It is front-loaded with the action and resource, then specifies the return content. 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 no parameters, rich annotations covering behavioral traits, and an output schema, the description is complete. It tells exactly what the tool returns, leaving no ambiguity for a simple parameterless tool.

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

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

The input schema has no parameters, so schema_description_coverage is 100%. The description adds meaning by listing the types of data returned (teams, dates, times, venues), which helps the agent understand the output, even though an output schema exists. Baseline for 0 params is 4.

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

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

The description clearly states the tool gets the 'current NHL weekly schedule' and specifies it returns 'upcoming and recent games with teams, dates, times, and venues'. The verb 'get' and resource 'NHL weekly schedule' are specific, and it easily distinguishes from siblings like get_scores, get_standings, and get_player.

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 when schedule information is needed, but does not explicitly state when to use or not use this tool compared to alternatives. There is no mention of exclusions or conditions, though the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by specifying return fields (teams, scores, shots on goal, period), which is not covered by annotations. It does not contradict annotations.

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

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

The description is a single sentence that efficiently communicates purpose and return contents. It is front-loaded with the key action ('Get today's NHL game scores and status'). 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 zero parameters, high schema coverage, existing output schema, and thorough annotations, the description fully covers what the tool does and returns. No missing context for selection or 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?

No parameters exist, so baseline is 4. The description does not need to add parameter info, and the schema coverage is 100%.

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

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

The description clearly states it retrieves today's NHL game scores and status, specifying exact return contents (teams, scores, shots on goal, current period). It distinguishes from sibling tools like get_schedule or get_standings by focusing on scores and live status.

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 use for today's games but does not explicitly contrast with siblings (e.g., get_schedule for future dates, get_standings for standings). No exclusionary or alternative guidance is provided.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the exact return fields (wins, losses, OT losses, points, goals for/against, streak info), which aids in understanding the behavior beyond the annotations.

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

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

Two sentences, front-loaded with the main purpose, no extraneous words. 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 no parameters and an existing output schema (as indicated), the description provides sufficient context about the return data. It covers the key fields, making it complete for a simple listing tool.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter information, and it correctly leaves the schema handle the (empty) parameter definitions.

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

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

The description clearly uses the verb 'Check' and the resource 'current NHL standings', listing the specific data fields returned. It distinguishes itself from sibling tools like get_player, get_schedule, and get_scores.

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 states what the tool does but provides no explicit guidance on when to use it versus alternatives, nor any conditions or exclusions. The purpose is clear, but usage context is minimal.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field details (id, type, params, etc.) and default behavior (active only). Adds context beyond annotations.

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

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

Two sentences: first states purpose, second adds usage guidance. No wasted words. Front-loaded with core information.

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

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

For a simple list tool with one optional parameter and no output schema, description lists return fields and usage context, making it fully adequate for agent selection and 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 parameter include_inactive described. Description does not repeat parameter info but provides no additional semantics beyond schema. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions.' Verb 'List' with specific resource 'subscriptions' and scope 'caller's active' differentiates from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides concrete when-to-use and purpose.

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

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

Annotations are all false, so the description fully carries the behavioral disclosure burden. It states the tool is rate-limited (5 per identifier per day), free, and doesn't count against quota. It implies a non-destructive write operation, consistent 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 four sentences, each earning its place: purpose, usage scenarios, how to describe feedback, and behavioral constraints. No fluff or repetition.

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

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

Given the moderate complexity (3 parameters, nested object, no output schema), the description covers purpose, usage guidance, parameter details, rate limits, and quota. It fully compensates for the lack of output schema by telling the agent what happens (digests, roadmap impact).

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the enum values ('bug = something broke...') and advising on message content ('be specific', '1-2 sentences typical'). This surpasses the basic 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 sends feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs like 'tell the Pipeworx team' and 'describe the issue in terms of Pipeworx tools/packs', distinguishing it from sibling tools that are for querying or 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?

The description provides explicit when-to-use scenarios (wrong data, missing tool, praise) and when-not-to (don't paste user prompts). It also explains the team reads digests daily, feedback affects roadmap, and notes rate limits and quota-free usage.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII), going beyond annotations. 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 concise, with two well-structured paragraphs. The first sentence immediately conveys the purpose, followed by numbered use cases. No unnecessary words.

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

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

Given the simplicity (1 optional parameter, no output schema), the description covers all necessary context: purpose, usage scenarios, caching, data source, and privacy. It is self-contained and 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% with a clear enum and description for 'window'. The description adds context about shorter vs longer windows (surfacing hot vs steady-state demand), providing additional meaning beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window, distinguishing it from siblings like discover_tools and ask_pipeworx. The verb 'returns' and specific outputs provide a precise 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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, aligning use case), providing clear guidance on when to use. It does not explicitly state when not to use, but the use cases imply alternatives.

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

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

The description fully discloses behavioral traits beyond annotations: semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live CLOB depth, and conditions for valid trades. Annotations already state readOnly and idempotent, and description adds rich context without contradiction.

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

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

The description is lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with core purpose. Every part adds value, but slight streamlining 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?

The description covers response structure (opportunities[], partition_check object, fill check details) and refers to sibling for custom sizing. Despite no output schema, it provides sufficient context for an agent to understand the tool's capabilities and when to use 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 descriptions are minimal, but the tool description greatly expands parameter meaning with examples, accepted formats (URLs), and detailed behavior for each mode. It compensates fully for the schema's brevity.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event, topic) and differentiates from siblings like polymarket_edges by mentioning fill checks and referring to polymarket_fill_risk.

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 on when to use each mode: no args for trending scan, event for specific market, topic for cross-event. It recommends event for specific markets and explains when not to trade (realizable_edge_pp <= 0). Also refers to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds useful behavioral context: caching (1h at KV level), diagnostics so callers see why segments are empty, and the exclusion of Fed bets from ranking. There is 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 thorough but verbose. It front-loads the purpose and uses bold section headers for structure, but could be trimmed to improve readability. Every sentence adds value, but the density may overwhelm agents.

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

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

Given the tool's complexity (9 parameters, 3 segments, no output schema), the description comprehensively covers inputs, outputs, internal models, and edge fields. It explains the response structure (by_segment, fed_candidates, _diagnostics) and lists all opportunity fields (edge_pp_net, kelly_fraction, etc.), leaving no major 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 detailed parameter descriptions. The description adds extra context, especially for min_partition_leg_kelly (explaining why min_kelly does not filter partition arbs) and slippage_pp (advice on setting it). This enhances understanding of parameter interactions, though the schema already covers individual parameters well.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for the use case 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on scanning top markets for edge opportunities across multiple model families.

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

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

The description provides clear context on when to use the tool (discover opportunities without paging hundreds of markets) and describes knobs for filtering (min_liquidity, max_spread_pp, etc.). It also notes that Fed bets surface here but are excluded from ranking. However, it does not explicitly state when not to use this tool in favor of siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds significant detail: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), interpretation of trend and decay (based on absolute edge value, signed by trade direction), limitations (cache-miss gaps, 60-day TTL, decay from daily closes). 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?

Long but front-loaded with purpose. Each sentence adds value (purpose, response details, limits, interpretation). Could be slightly more concise, but efficient for the level of detail.

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

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

No output schema, so description must document return values. It does so thoroughly: tracked[] arrays with edge_pp_net time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. Also covers limitations (60-day TTL, start date, decay computation). Fully complete for a time-series edge tracking tool.

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

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

Schema covers both parameters with descriptions. Description adds defaults (14 days, '1wk' window), clamping range (2-30), and clarifies that window is 'snapshot family'. Also explains that snapshot_dates reflect cache-miss behavior. Good additive 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 states tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers specific questions 'how long has this edge existed and is it shrinking?' and distinguishes from sibling tools like polymarket_edges by focusing on time-series 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?

Provides context on when to use: to evaluate edge persistence and decay, contrasting fresh vs old edges. Includes limitations (60-day TTL, start date, decay from daily closes not intraday). Does not explicitly state when not to use or name alternative tools, but the guidance 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds behavioral context that it checks against live order book, walks the ladder, and returns fill details. It warns about unhedged directional risk, which is beyond annotations. 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 well-structured with headings and bullet points, front-loading the core purpose. However, it is somewhat verbose with detailed explanations; a bit more conciseness could improve it without losing essential context.

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 is provided, but the description comprehensively lists return fields for both modes (e.g., top_of_book, vwap_fill_price, profit_usd, thin_legs). It covers the risk of partial fills and forced directional risk, making it complete for a complex tool.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it explains mutual exclusivity of market/event, default values for side and size_usd, and the basket mode's interpretation of size_usd as 'settlement notional'. This goes beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes single-market vs basket modes. It names the tool as a prerequisite for polymarket_arbitrage and polymarket_edges, effectively differentiating from sibling tools.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains consequences of not using it, such as partial fills converting an arb into an unhedged directional position.

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 details behavioral traits beyond annotations: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the fact that spreads are only computed when outcomes match. There is no contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is well-structured with clear headings (TWO MODES, RESPONSE, SAFETY FIELDS) and contains valuable information. However, it is somewhat verbose and could be trimmed slightly without losing clarity. Every sentence earns its place, but conciseness could be improved.

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

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

Given the tool's complexity (two modes, multiple safety fields) and lack of output schema, the description is remarkably complete. It fully explains inputs, expected output fields (prices, spreads, warnings, temporal alignment), and edge cases, leaving minimal ambiguity for an agent.

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

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

Schema coverage is 100%, and the description adds significant meaning: lists all 10 topic shortcuts, explains that explicit tickers/slugs override topic mappings, and describes the role of each parameter. This adds value beyond the schema definitions.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, and distinguishes two modes (topic shortcuts and explicit pairing). The verb 'spread' and resource 'Polymarket–Kalshi' are specific, and the description differentiates from sibling tools like polymarket_arbitrage by focusing on cross-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?

The description provides explicit guidance on when to use each mode, including the caution that most pre-mapped topics return warnings and are not tradeable. It also explains the response structure and safety fields. However, it does not directly compare to alternative tools for cross-venue analysis.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral details: scoping to identifier, listing all keys when omitted, and pairing with remember/forget. No contradictions.

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

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

The description is concise but thorough, front-loading the main action, then providing examples, scope, and pairing in a logical order. Every sentence adds value without redundancy.

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

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

For a simple retriever tool with one optional parameter and no output schema, the description is complete. It covers the main operation, the list-all behavior, scoping, and relationship with related tools (remember, forget).

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

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

With one parameter and 100% schema coverage, the description adds significant value beyond the schema: 'omit the key argument' to list all keys. This clarifies behavior not evident from the 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?

Clearly states the verb (retrieve/list), resource (saved values/keys), and distinguishes from siblings remember and forget. The description explicitly says 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).'

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 context for when to use ('look up context the agent stored earlier') and explains scope ('Scoped to your identifier'). It pairs with remember and forget but does not explicitly state when not to use alternatives, though the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: mark_read:true flags events as read affecting subsequent calls, the feed is persisted, and return fields are specified. No contradictions with annotations.

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

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

The description is a single concise paragraph that front-loads the main purpose, then systematically covers return fields, filtering options, and alternative access. Every sentence adds value without redundancy.

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

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

The description covers return fields and parameter behaviors comprehensively. Since there is no output schema, it explains what data is returned. It lacks explicit mention of the limit parameter, but that is documented in the schema. Overall, it is complete for a simple list tool with strong annotations.

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%, providing baseline 3. The description adds significant semantics: explains filtering by type with an example, clarifies since expects ISO timestamp, and describes the effect of mark_read on feed state. This value goes 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 pulls fired events from a subscription feed, identifies the returned fields (source, citation_uri, raw payload), and distinguishes itself through filtering and mark_read capabilities, setting it apart from sibling 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 usage guidance on filtering by type and since, and explains the effect of mark_read. It also mentions the feed is accessible via an alternative URL for scripts/dashboards, implying when to use which interface. However, it does not explicitly state when not to use this tool or compare with 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?

Description goes beyond annotations by detailing the fan-out to multiple sources, fallback mechanisms, and return structure (changes grouped by source, total_changes, 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?

The description is concise yet comprehensive, with a clear front-loading of example queries, followed by detailed source behavior and parameter explanations. No unnecessary words.

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

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

Given the tool has 3 required params, no output schema, and annotations present, the description fully covers inputs, behavior, return structure, and sibling differentiation. An agent can confidently invoke this tool.

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

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

Schema coverage is 100%, but description adds value by explaining `since` formats (ISO date or relative shorthand) with examples, suggesting '30d' for monitoring, and specifying that `value` accepts ticker or CIK. This enhances the schema descriptions.

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

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

The description explicitly states the tool's purpose: providing a change feed for a company in the last N days/weeks/months, with specific examples like 'What's new with X' and 'updates on Acme'. It distinguishes from sibling tool 'entity_profile' by noting when to use that instead.

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

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

Gives explicit when-to-use guidance (queries about recent changes, latest news) and when-not-to-use (static profiles should use entity_profile). Also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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

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

The description adds useful context beyond annotations: key-value pair scoped by identifier, persistence differences for authenticated vs. anonymous sessions (24-hour retention). No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). Does not explicitly mention overwrite behavior, but idempotentHint implies it.

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 of 4 sentences, front-loaded with purpose, then usage guidelines, then technical details. No superfluous information; 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 low complexity (2 required params, no output schema), the description is largely complete. It covers purpose, usage, persistence scoping, and pairing with sibling tools. Could mention return value or overwrite behavior, but not critical for a simple storage tool.

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

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

Schema coverage is 100% with clear descriptions. The description reinforces the purpose but does not add significant new detail beyond the examples already in the schema for 'key' and 'value'. Baseline score of 3 appropriate.

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides specific examples of when to use it (resolved ticker, address, user preference). It distinguishes from siblings by explicitly mentioning recall and forget as complementary 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 says 'Use when you discover something worth carrying forward' and 'so you don't have to look it up again', providing clear guidance on when to use. It also mentions pairing with recall and forget, indicating appropriate alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds value by detailing internal cascading behavior, output formats (including citation URIs), and accepted input variations (ticker, CIK, name). 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?

Starts with example queries, then purpose, then detailed type breakdown. Every sentence is informative; no wasted words. Efficient and well-organized.

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

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

Despite no output schema, the description fully explains return values for each supported type, including citation URIs. Covers input, output, and internal behavior completely for a lookup tool.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds examples and clarifies accepted formats (e.g., 'ticker (AAPL), CIK (0000320193), or name'). Useful complement.

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

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

The description uses specific verbs and examples ('resolve a user-spoken NAME to the canonical/official identifier') and distinguishes from siblings like 'entity_profile' by clarifying it returns IDs, not profiles. It clearly states the tool's purpose.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context. It does not list alternatives or when-not-to-use, but the context is strong enough.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses return fields (score, confidence, signal density), which is not in annotations.

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

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

The description is three sentences long, front-loaded with the main purpose, and contains no redundant information. Every sentence contributes to understanding the tool's function, output, and usage context.

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 adequately explains the return format (ranked list with score, confidence, signal density). It covers the main use case and the internal process. However, it could elaborate on how the 'models' parameter affects behavior or what happens if no Anthropic API key is provided.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds context that ai_visibility_check is used internally, but does not provide additional semantic value beyond what's in the schema. It could clarify the relationship between models and the internal probe, but is adequate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying 'competitive AI-marketing audits' and the internal probing method.

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 recommends use for competitive AI-marketing audits and gives a concrete example. It implies when to use but does not explicitly state when not to or list alternatives like ai_visibility_check for single entities, leaving some room for ambiguity.

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

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

Discloses partial failure graceful degradation, potential 5-30s delay for bundlephobia first measurement, and that sources_failed will list timeout. Annotations already indicate readOnly, idempotent, non-destructive; 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?

Single paragraph with dense, useful information. Front-loaded with purpose, then usage, then details. Slightly long but efficient.

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

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

No output schema, but description details return summary fields, per-advisory detail, links, and alternative versions. Also explains error behavior. 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 has 100% coverage; description adds useful context: accepts scoped packages, defaults to latest version when omitted. 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?

The description clearly states the tool's purpose: a composite check for adding an npm package, summarizing license, advisories, size, and tree-shake support. It distinguishes from siblings by focusing on npm dependencies, unlike other research/scan 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?

Explicit guidance on when to use: when asked 'is X safe/popular/small' or 'what does adding lodash cost'. Also notes limitations: only npm ecosystem and alternative for other ecosystems.

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, idempotent, non-destructive), the description reveals the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), max input length, and that passages include character offsets for verification.

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 single paragraph is dense and well-structured, front-loading the core action and use case. It could benefit from bullet points for technical details, but remains concise and informative.

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

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

Given no output schema, the description adequately explains return format (top-N passages with offsets and scores). It covers input constraints, use case, and sibling pairing, but lacks an explicit example output.

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 with concrete examples for the 'query' parameter and context for 'text' (already pulled document), enhancing understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K and articles. It effectively differentiates from sibling tools by explaining its use alongside ask_pipeworx_grounded.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt'), provides a pairing suggestion with a sibling tool, and mentions input limits (200K chars) and truncation behavior.

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 idempotent and non-destructive, but the description adds important behavioral details: requires OAuth, returns subscription id, delivery constraints (SMS cap, webhook auto-disable). It does not contradict 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 well-structured with a clear front-loaded purpose, followed by requirements, types, and channels. It is somewhat lengthy but every sentence adds value. Minor verbosity in delivery channel details could be condensed.

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 explains the return value ('Returns the new subscription id.'). It covers all parameter semantics, requirements, delivery options, and constraints. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%. The description goes far beyond schema descriptions with examples for each type, detailed explanations for 'params' and 'delivery' fields, including constraints like phone verification and webhook signing. This adds significant meaning.

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

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

The description clearly states the purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation and monitoring. The verb 'Create' and resource 'subscription' are specific.

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

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

The description provides clear context on when to use this tool: for setting up persistent subscriptions. It mentions requirements (Pipeworx OAuth account) and limitations (anonymous/BYO cannot persist). It does not explicitly name alternatives but the context and sibling tools imply when not to use it. Slight gap in explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that results are drawn from a live catalog and returns category-bucketed examples, but this is mild behavioral context beyond annotations.

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

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

Well-structured with front-loaded example queries. Every sentence adds value, but the description is slightly long; minor tightening possible.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains what to expect (category-bucketed examples) and when to use it, making it 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 a clear description of 'topic'. The description adds value by listing the exact topic options (finance, pharma, etc.) and explaining the effect of omitting it, going beyond the schema's enum hint.

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

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

The description clearly states the tool is an onboarding entry point returning category-bucketed example questions with tool+argument shapes. It distinguishes from siblings by referencing meta-tools like 'ask_pipeworx' and 'entity_profile'.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass 'topic' vs omit for full spread.

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

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

Annotations provide safety profile (non-destructive, idempotent). Description adds key behavioral detail: 'row is deactivated (not deleted) so historical events stay available.' 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, front-loaded with action. Each sentence adds essential 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 low complexity (1 param, no output schema), description covers purpose, ownership, and behavioral impact on data. Annotations complete the safety profile.

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

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

Schema coverage is 100% with a single parameter 'id' already described as a uuid from subscribe. Description adds no further parameter semantics, but baseline 3 is appropriate given full schema coverage.

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

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

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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which clarifies when to use. Mentions effect on historical events via recent_alerts. No explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: the dual-pipeline processing (SEC EDGAR for financial claims, grounded pipeline for others), the exact percent-delta math, and the output verdict types. This goes 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 moderately long but front-loaded with example triggers. Every sentence adds value: examples, pipeline details, return values, and efficiency claims. Could be slightly tighter, but the structure is logical and effective.

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

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

Given the tool's complexity (claim verification with two pipelines) and the absence of an output schema, the description adequately explains return values ('verdict, actual value with citation, reasoning'). It covers the main behavioral aspects and parameter usage, making it self-contained for an agent.

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

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

Schema coverage is 100% with both parameters well-described. The description adds practical usage guidance for tolerance_pct (e.g., 'set 1-2 for hallucination detection'), and explains that the default is implied by claim wording, enhancing the schema's minimal description.

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

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

The description uses clear verbs ('check', 'verify', 'validate') and specifies the resource ('factual claims against authoritative sources'). It provides numerous examples of user intents ('Is it true that...', 'fact check') and distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls, giving it a unique identity.

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

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

The description explicitly states when to use this tool ('when the agent needs to check whether something a user said is factually correct') and provides a detailed breakdown of claim types (financial vs. other). However, it does not explicitly state when NOT to use it or name specific sibling alternatives, though the context of replacing multiple calls implies efficiency.

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