Alpaca

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds key behavioral details: defaults to free Workers AI Llama, requires BYO key for Anthropic, returns per-model fields. No contradictions.

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

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

Three focused sentences: first defines action and output, second explains defaults and key usage, third lists use cases. No redundant text; well front-loaded.

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

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

Even without output schema, description specifies return structure (per-model {score, confidence, signals, raw_response} + combined view). Adequately covers all aspects for a 4-param tool with 1 required param.

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

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

Schema covers all 4 params (100% coverage). Description adds value beyond schema by explaining the default model is free, the _apiKey is passed through to Anthropic, and context helps disambiguate entities.

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 verb 'probe' and resource 'LLMs' for visibility scoring. Distinguishes from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on AI brand visibility metrics (0-100 score per model).

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 gives use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not directly name alternatives but context implies it's for visibility checks rather than general research or Q&A.

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, openWorldHint=true, destructiveHint=false, so the description adds value by noting intraday bars include pre-market and after-hours sessions on the IEX feed, and that a free Alpaca account is sufficient. 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 concise and front-loaded with the main purpose. It efficiently covers what the tool does, timeframes, data source, parameter usage, and an example. Minor improvement could be better structure, but it earns its place with no redundant sentences.

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

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

Despite no output schema, the description explains the bar structure ({t,o,h,l,c,v,vwap,trades}) and the IEX feed. It covers all necessary aspects: symbols, timeframe, time range, authentication, limits, and provides an example. The context is complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description enriches meaning by providing example formats for start/end, lookback shorthand examples, API key format ('key_id:secret_key'), and timeframe options. It adds significant value beyond the schema.

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

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

The description clearly states the tool returns 'Historical US stock OHLCV bars with per-bar VWAP and trade count'. It specifies the resource (US stock bars), the verb (get/retrieve), and distinguishes from siblings like alpaca_intraday_vwap and alpaca_snapshot by focusing on historical multi-timeframe bars.

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 guidance on usage: 'Use start/end ISO timestamps or a lookback shorthand', 'Multiple symbols comma-separated (max 20)', and includes an example. It does not explicitly state when not to use this tool versus alternatives like alpaca_intraday_vwap, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it fetches 1-minute bars from 04:00 ET, computes cumulative VWAP, and uses real-time IEX feed. It does not contradict annotations and adds meaningful behavioral context such as pre-market inclusion and computation method.

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

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

The description is front-loaded with the core purpose and structured logically: purpose, methodology, output, example. It is efficient but slightly verbose, repeating some schema details. Each sentence contributes, but could be tightened.

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

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

For a tool with no output schema and 2 params, the description explains computation, data source, and output fields. Annotations cover safety. Minor gaps: no explicit mention of market hours or error handling, but these are implicit and acceptable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates parameter info but adds minimal new meaning: it repeats the credentials format and provides an example query. The value added over the schema is marginal.

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

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

The description clearly states the tool computes intraday VWAP for US stocks and checks if the price is above or below VWAP. It specifies the verb 'fetches, computes, compares' and the resource 'current session VWAP'. However, it does not explicitly distinguish from sibling tools like alpaca_bars or alpaca_snapshot, though the emphasis on 'current session' implies differentiation.

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

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

The description gives context by answering a sample query and noting the max 20 symbols. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., alpaca_bars for historical bars, alpaca_snapshot for real-time quotes). There are no when-not-to-use instructions.

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 key behavioral details: during extended hours the minute bar IS the live price, and data is from real-time IEX feed. 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 dense paragraph that efficiently communicates purpose, behavior, and usage. It front-loads the core purpose. Could be slightly more structured (e.g., bullet points) but is still concise.

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

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

Given no output schema, the description explains the output contents (trade, quote, OHLCV, minute bar with VWAP). It covers extended-hours behavior. Missing details like error handling or rate limits, but sufficient for typical use.

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

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

Schema coverage is 100% with good descriptions. The description reinforces parameter semantics with an example usage and clarifies the format for _apiKey. This adds value beyond the schema by showing how to call the tool.

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: 'Real-time US stock snapshot with extended-hours coverage' and lists specific data points (latest trade, bid/ask, OHLCV, change, VWAP). It distinguishes from siblings like alpaca_bars by focusing on real-time snapshots with extended hours.

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 specifies when to use the tool by giving example queries ('pre-market price of OKTA', 'overnight change %') and constraints (max 20 symbols, comma-separated). It implies alternatives exist (historical data) but does not explicitly name them.

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 non-destructive behavior. The description adds useful context: it routes to 5,093 tools across 1,340 sources, returns structured answers with citation URIs, and works on every tier. No contradictions, but the description enriches the behavioral understanding beyond annotations.

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

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

The description is long but well-structured: starts with a clear directive, lists sources, gives usage guidance, examples, and escalation paths. It is front-loaded with key information. While it could be more concise, the structure benefits readability and completeness.

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 (5,093 tools) and simple input schema (one required string), the description is remarkably complete. It explains the tool's purpose, when to use it vs. alternatives, what to expect (structured answers with citations), and provides extensive examples. No output schema, but the description adequately covers return value expectations.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by listing multiple aliases (q, text, input, query, prompt) and providing example questions, making it clear that the input is a natural language query. This clarifies flexibility beyond the schema's basic description.

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

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

The description clearly states the tool is for asking questions about current/historical data from structured sources, with explicit preference over web search. It lists many specific data types and provides example queries, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for factual questions, provides a comprehensive list of when to use (e.g., 'what is', 'look up', 'find'), and gives clear guidance on stepping up to ask_pipeworx_grounded or deep_research for specific needs. Examples illustrate the correct 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?

Adds significant behavioral context beyond annotations: describes it as a universal router with 5,093 tools, same arguments and response shape, source-preference ranking behavior, and that it falls back to nothing (full working router). No contradiction with annotations.

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

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

Description is moderately sized (3 sentences) and front-loaded with beta nature and key differentiator. Each sentence adds value, though could be slightly more concise.

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

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

Given no output schema, the description explains the response shape ('same response shape') and that it's a full working router. Provides context of 5,093 tools and experimental nature, making it complete for tool selection.

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 reinforces that it accepts the same arguments as ask_pipeworx, which aligns with the schema but adds no new meaning beyond what the schema already provides.

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

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

Clearly states it's a beta version of ask_pipeworx, an identical universal router with 5,093 tools, and distinguishes from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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 use it exactly like ask_pipeworx when wanting the newest routing, and explains results are compared against the stable router to decide merges. No explicit when-not, but the experimental nature is implied.

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: it explains the internal process (routes to tools, extracts answer only from results), the return format with explicit refusal reasons, and the cost of one extra LLM call. This adds value beyond the readOnly, openWorld, idempotent 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 somewhat lengthy but every sentence adds value, front-loading the core purpose and key details. It efficiently conveys when and how to use the tool.

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

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

Given the tool's complexity (routing across 5093 tools and 1340 sources), the description adequately covers the return object format, failure modes, and usage context. No output schema is provided, but the description compensates with detailed return structure.

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

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

Schema coverage is 100%, with each parameter including a description. The tool description does not significantly expand on parameter semantics beyond what the schema provides, but the aliases are already noted. Baseline 3 is appropriate as the schema carries the burden.

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 'hallucination-resistant answer mode for high-stakes reads' and explains the process of routing to the right tool, fetching data, and extracting answers only from tool results. It distinguishes itself from the sibling tool 'ask_pipeworx' by specifying it is for situations where answers will be quoted or acted upon.

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 this tool: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts (e.g., financial, legal, medical). Also recommends preferring ask_pipeworx for casual lookups, providing clear guidance on 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 (readOnlyHint, idempotentHint) are consistent with description. Description adds extensive behavioral details: resolver contract with confidence levels, parent event extractor, news fallback fields, safety short-circuits for low-confidence/closed markets, wide-spread liquidity warnings, resolution-rule risk parsing. 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 very long (~600 words) and detailed, with labeled sections. While structured, it includes redundancy (e.g., low-confidence handling mentioned twice). Could be more concise without losing key info.

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

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

Given no output schema, the description fully explains response shape (market, analysis, evidence, etc.), edge cases (low confidence, closed markets, wide spreads), and resolution risks. Covers all critical aspects for an agent to use the tool correctly.

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

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

All 3 parameters have schema descriptions (100% coverage). The description adds extra context: market can be slug/URL/question; depth defaults to thorough; include_raw default false and explains size implications. Examples in schema enrich understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from siblings like polymarket_edges by focusing on a single bet research.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides fan-out examples for categories. Does not explicitly exclude alternatives or compare to siblings, 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, openWorldHint, and idempotentHint. The description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting by primary metric. No contradictions with annotations.

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

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

The description is front-loaded with query examples and is packed with information. It is somewhat long but every sentence adds value. Could be slightly more concise, but structure is 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 full schema coverage, strong annotations, and no output schema, the description covers purpose, usage, data sources, and return behavior (paired data with citation URIs). Missing detailed return format but sufficient 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%, but the description enriches meaning by explaining that for companies 'values' are tickers/CIKs and for drugs they are names. It also clarifies what data is pulled per type, adding context beyond the schema descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 entities (companies or drugs) with specific example queries like 'compare X and Y' or 'which is bigger'. It distinguishes from siblings such as 'entity_profile' by explicitly mentioning it replaces sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong when-to-use guidance. It does not explicitly state when not to use, but the context implies single-entity lookups are for other tools.

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

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

The description adds significant behavioral context beyond annotations: details the research process (decomposes, routes in parallel), return format (findings packet, gaps[], contradictions[]), timing expectations (15-60s, up to ~90s for thorough), and hop/citation fields. No contradiction with annotations.

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

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

The description is long (~250 words) but front-loaded with critical account requirements. Every sentence adds value, though slight verbosity could be trimmed. For the complexity, it's acceptable.

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 thoroughly explains the return format (findings packet with evidence, gaps, contradictions), behavior, limitations (current news), and timing. It is completely informative for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (baseline 3). The description adds extra meaning: for 'depth' explains quick/standard/thorough differences, for 'question' specifies natural language and suitability for broad queries. This provides good value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1340 STRUCTURED data sources in ONE call'. It distinguishes from siblings like ask_pipeworx by specifying it's for broad/multi-part questions over structured data, not for single lookups or breaking news.

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 provides usage guidelines: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes account requirements (if not signed in, use ask_pipeworx). It also mentions the paid tier for 'thorough' depth.

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=true, idempotentHint=true, destructiveHint=false) are corroborated and extended. The description explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This goes beyond annotations.

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

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

Description is well-structured: purpose first, then usage list, then return value. It is somewhat lengthy but each sentence adds value. Slightly verbose for the given info.

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 compensates by stating that results include names, descriptions, schemas with examples. For a discovery tool with many aliases, this is sufficiently 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% (all params described), so baseline is 3. The description adds minimal extra meaning, only noting 'Natural language description' for query. No param details beyond schema aliases.

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 multiple concrete domains and distinguishes this from siblings by being the discovery mechanism. The verb 'discover' aligns with the name.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for: [list].' It also advises: 'Call this FIRST when you have many tools available and want to see the option set.' This helps the agent decide when to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds valuable behavioral context: parallel fan-out across multiple sources, specific return fields with sorting, and disclosure of potential soft-failure for patents. This exceeds the baseline expected from annotations alone.

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 somewhat lengthy, with example prompts at the start and detailed enumeration of data sources. While it is well-structured and front-loaded, it could be slightly more concise to improve readability without losing essential information.

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

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

Given the complexity of the tool (multiple data sources, no output schema), the description is remarkably complete. It lists all returned fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents status, news fallback, LEI) and discusses limitations. It provides everything needed for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond the schema: 'type' is clarified to only support 'company' with future plans, and 'value' is explained with examples and instructions (ticker vs. CIK, names not supported). This fully compensates for any gaps.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company in a single parallel call. It uses specific verbs and resources (e.g., 'full cross-source profile', 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF') and distinguishes itself from chaining single-pack lookups, making the purpose unmistakable.

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

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

Explicitly states when to use ('ALWAYS PREFER over chaining single-pack lookups when user asks for a holistic view') and when not to use ('Names not supported — use resolve_entity first'). Provides clear context and instructions for parameter input, giving strong guidance.

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

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

Annotations already provide destructiveHint and idempotentHint. Description adds context about clearing sensitive data but does not describe behavior on missing keys or side effects beyond deletion.

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, then use cases. Every sentence is valuable with no redundancy.

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

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

Covers purpose and usage well for a simple delete tool with one parameter. Lacks return behavior or error handling details, but not critical given simplicity.

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

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

Schema coverage is 100% and the description for 'key' ('Memory key to delete') adds no new meaning beyond what the schema provides.

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

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

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource. Distinguishes from siblings 'remember' and 'recall' as the deletion tool.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with 'remember' and 'recall'. Lacks explicit when-not-to-use or alternatives beyond siblings.

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

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

Annotations already reveal readOnly, idempotent, non-destructive, open-world hints. The description adds behavioral context by stating it fetches the page, extracts title/description/key links, and outputs markdown. This goes beyond the annotations, giving the agent a clear mental model of the tool's operations.

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

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

The description is three sentences long, front-loaded with the main purpose, followed by the process and use cases. Every sentence is informative and necessary. 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 the lack of an output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt') adequately. It covers the main behaviors but could mention error handling or prerequisites (e.g., URL accessibility). Still, it is reasonably complete for a straightforward 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%, so the baseline is 3. The description does not add new information about the parameters beyond what the schema already provides. It does not repeat the parameter details, which is acceptable but adds no extra value.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with a specific verb and resource. It explains the process (fetch, extract, emit) and distinguishes its purpose from typical web tools. Although sibling differentiation is not explicit, the description is very specific and leaves no ambiguity.

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

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

The description provides explicit use cases (client indexing, drafting, auditing) and context. However, it does not mention when not to use this tool or suggest alternatives, which would have made it a 5. Still, the guidance is clear and actionable.

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. Description adds return field details and optional parameter behavior, providing useful 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, front-loaded with action and return values, no wasted words. Highly concise.

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

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

Complete for a simple list tool: explains return fields, optional parameter, and use case. Rich annotations compensate for lack of output schema.

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

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

Schema has 100% coverage with a description for the single parameter. Description does not add meaning beyond the schema, so baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, lists return fields, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance on when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Implied alternatives but no explicit when-not.

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

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

The description adds behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and signals that feedback directly affects roadmap. Annotations only indicate non-read-only, non-idempotent, non-destructive, but the description provides valuable operational details.

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

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

The description is compact and front-loaded: it starts with the core purpose, then lists use cases, then constraints. Every sentence is informative and necessary, with no filler. It uses bullet-style formatting for clarity.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description covers all necessary context: what to describe, how to format, rate limits, cost, and impact. No additional information is needed for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic detail: it elaborates on the enum values for 'type' (bug = wrong data, feature = new tool, etc.), explains the context object, and provides guidance on message content. 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 the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, or praise. It specifies what actions constitute each feedback type and distinguishes itself from sibling tools like ask_pipeworx or discover_tools, which are for queries or exploration, not feedback.

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 for bugs, feature/data gaps, or praise. It also includes what not to do (don't paste the end-user's prompt) and mentions rate limits and cost implications, which help the agent decide whether to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, and caching behavior (5min-1h). 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 two well-organized paragraphs: first states functionality and output, second lists use cases. Every sentence adds value without redundancy. 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?

Despite no output schema, the description specifies the return contents (top tools, top packs, total call volume). It also covers data source, privacy, and caching. For a simple tool with one parameter, this is fully 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%, and the description adds semantic guidance for the window parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately beyond the enum values.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over configurable time windows. The verb 'returns' is specific, and the resource and scope (trending usage from other AI agents) distinguish it from sibling tools like discover_tools or ask_pipeworx.

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 three concrete use cases (discovering hot data sources, confirming popular tools, aligning use cases). While it does not explicitly state when not to use the tool or name alternatives, the use cases are clear and contextually appropriate.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are all consistent with the description's claim of not executing trades. The description details internal steps: semantic anchor Jaccard filtering, partition filter for placeholder slugs, and fill check against CLOB depth. It warns that zero realizable edge means don't trade.

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

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

The description is dense with technical details and well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While it could be slightly shorter, every sentence adds value. It is front-loaded with the main purpose and modes.

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 arbitrage detection across multiple modes, the description is thorough. It covers the output structure (opportunities array, partition_check object, fill check details) despite lacking an output schema. It also explains edge cases like cross-event mode catching patterns missed by single-event mode.

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 adds significant meaning beyond the schema: explains the difference between event and topic modes, provides examples of event slugs and seed questions, and describes the internal algorithms (partition_check, monotonicity, fill check) that each parameter triggers.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes: no args for trending scan, event for specific market, and topic for cross-event scan. This distinguishes it from sibling tools like polymarket_edges or 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?

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. It explains the semantic anchor, partition filter, and fill check conditions, including when not to trade (realizable_edge_pp ≤ 0).

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

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

The description goes far beyond annotations, detailing caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge calculation (edge_pp_net net of slippage, Kelly fractions, 24h move warning), and tradeable-edge filters. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading purpose and usage. It covers many details but could be more concise; some details about model families are dense. Overall, it earns its length given complexity.

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

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

Given the complexity (9 parameters, no output schema), the description thoroughly covers input usage, response structure (by_segment, diagnostics), edge calculation, caching, and filtering knobs. It compensates for the lack of an output schema by describing the response top-level fields.

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

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

All 9 parameters have descriptions in the input schema (100% coverage). The description adds context about default values and interplay but does not significantly add to individual parameter semantics beyond what the schema provides. 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: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It explicitly mentions three segments, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 the tool (discovery without paging hundreds of markets) and explains various knobs (min_liquidity, max_spread_pp, category_filter) for filtering. It also explains the Fed bets exclusion. However, it lacks explicit 'when not to use' compared to siblings.

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

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

Beyond annotations (readOnlyHint, idempotent, nondestructive), the description adds key behavioral details: snapshots are written on cache-miss (gaps mean no scan), history is bounded by 60-day TTL, decay is from daily closes, not intraday. This transparently informs the agent about data availability limitations.

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: starts with core purpose, then details response fields and limits. Every sentence adds value, and the response format is clearly explained. Could be slightly more concise but remains effective.

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

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

Given no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields (time-series, trend, decay, lifespan). It also covers data freshness limitations, making the tool's behavior completely understandable.

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's parameter details add modest value. It clarifies 'days' is a lookback with default 14 and max 30 (schema says clamp 2-30, slightly inconsistent but not contradictory), and 'window' is a snapshot family. No significant extra meaning beyond the schema.

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

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

The description clearly states the tool tracks edge persistence and decay telemetry using daily snapshots, answering a specific question about edge age and shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis.

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

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

The description explains when to use the tool (to assess whether an edge is fresh or old/decaying) and provides context by contrasting a fresh wide edge with a 3-week-old one. It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare safety. Description adds rich behavioral detail: walks the ladder, returns verdict (clean|degraded|cannot_fill), and for baskets includes forced_directional_risk and thin_legs. 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 well-structured, starting with the core purpose, then REQUIRES, then mode details. Each sentence adds meaningful information. Slightly long but 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 4 parameters and no output schema, the description covers all needed information: input constraints, return fields per mode, and critical behavioral warnings (e.g., partial basket fills, forced directional risk). Complete for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains REQUIRES one of market or event, interprets size_usd differently for single-market vs basket (max spend vs settlement notional), and clarifies default side behavior for baskets ('auto from partition sum').

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth'. It specifies single-market and basket modes, and distinguishes from sibling tools like 'polymarket_arbitrage' and 'polymarket_edges' by being a pre-trade validation step.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why theoretical overround is not capturable on thin books and warns about partial basket fills converting arb into directional risk.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. The description adds rich behavioral context: explains that the tool compares venues, computes spread, and provides safety fields (compatibility_warning, temporal_alignment, skipped counts) that warn when bet shapes are not equivalent or venues are unrelated. This goes well beyond annotations.

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

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

The description is thoroughly structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and bolding. Every sentence adds value, from explaining the modes to detailing edge cases. Despite length, it is not verbose; it is efficiently packed with necessary information.

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

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

Given the lack of output schema and three parameters, the description is remarkably complete. It covers return format (prices, spread, safety fields), temporal alignment, compatibility warnings, and explains why spreads may be invalid. It leaves no gaps for an agent to misinterpret.

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 adds significant meaning: it explains the 'topic' parameter as a pre-mapped shortcut with a list of valid values, and clarifies that explicit parameters override the topic-mapped sides. It also describes the two modes of operation, which is not apparent from 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?

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on the specific spread between two venues. The verb and resource are explicit.

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: for cross-venue spreads on the same question. It details two modes (topic shortcuts and explicit ticker/slug) and warns that most pre-mapped topics return compatibility_warning and are not tradeable, setting clear expectations.

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, and idempotentHint=true. The description adds value by disclosing that results are scoped to the user's identifier (anonymous IP, BYO key hash, or account ID), which is important for understanding security and privacy boundaries. 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 three sentences, each serving a distinct purpose: main action, usage context, scope, and related tools. It is front-loaded with the core functionality and wastes no words.

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

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

For a simple read-only, idempotent tool with one optional parameter, the description covers all necessary aspects: basic behavior, usage scenario, scope, and relationship to sibling tools. No output schema is required given the simplicity.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema: it explains that omitting the key lists all keys, and provides concrete examples of what kind of data can be retrieved (e.g., user's target ticker, address, research notes). This helps the agent understand the parameter's dual role.

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

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

The description clearly states the verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings by explicitly mentioning 'remember' and 'forget'. It specifies that omitting the key lists all saved keys.

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 explains when to use the tool (look up previously stored context without re-deriving) and provides explicit guidance on when to use alternatives ('Pair with remember to save, forget to delete'). The context signals show sibling tools include 'remember' and 'forget', reinforcing the pairing.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds crucial behavioral context: mark_read:true flags events as read, affecting subsequent calls, and mentions the same feed is available via a GET endpoint. 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 reasonably concise and front-loaded with purpose and key return fields. However, the parameter explanations make it somewhat verbose; a slight restructuring could improve readability without losing content.

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

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

For a read-only tool with 5 optional parameters and no output schema, the description is quite complete. It explains what is returned (source, citation_uri, raw payload), how filtering works, the effect of mark_read, and provides an alternative access method. 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%, so baseline is 3. The description adds meaning beyond schema descriptions by explaining each parameter's purpose with examples (e.g., 'Filter by type (e.g. "sec_8k")', 'Set mark_read:true to flag returned events read so the next call only shows newer ones.'). This enhances understanding.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and supports filtering by type and since. This is a specific verb+resource that distinguishes it from sibling tools like list_subscriptions or recent_changes.

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 mentions that polling works fine and that the same data is available via a GET endpoint for scripts and dashboards, providing context for when to use this tool vs alternative access methods. However, it does not explicitly state when not to use this tool or how to choose between this and siblings like list_subscriptions or recent_changes.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds rich behavioral context: fan-out to multiple sources, fallback logic, return structure (grouped changes, total_changes, citation URIs), and window parameter behavior. No contradiction with annotations.

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

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

Description is comprehensive and well-structured with front-loaded examples, but slightly verbose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given no output schema, description compensates by detailing return structure and source behavior. However, lacks explicit mention of empty results or error scenarios beyond the noted fallback and soft-fail.

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

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

Schema coverage is 100% and description adds meaning beyond schema: explains 'since' accepts ISO date or relative shorthand with examples, suggests typical usage ('30d' for monitoring), clarifies 'type' is limited to 'company', and explains 'value' accepts ticker or CIK.

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 provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) in a time window. It distinguishes from 'entity_profile' by specifying when to use each, and uses specific verbs like 'fans out' to convey functionality.

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

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

Explicitly lists example queries ('What's new with X', 'latest on Y') and provides alternative: 'Use entity_profile instead when you want the static profile...'. Also explains source preference (GDELT preferred, GNews fallback) and USPTO soft-fail.

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

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

The description discloses behavioral traits beyond annotations: scoping by identifier, persistence duration (persistent for authenticated, 24 hours for anonymous), and pairing with recall/forget. Annotations already indicate idempotentHint=true and non-destructive, so 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 (three sentences), front-loaded with the main purpose, and structured logically: what, when, how. 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?

Given the simple input schema and no output schema, the description fully covers behavior (duration, scoping, pairing with tools). No gaps for this simple 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 good descriptions. The description reinforces the purpose of key-value pairs but does not add new meaning beyond providing examples in the schema. However, the context of storing 'findings, addresses, preferences, notes' is helpful.

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

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

The description uses a specific verb ('save') and resource ('data that the agent will need to reuse'), clearly stating the tool's function. It differentiates from sibling tools by mentioning recall and forget explicitly, making it easy to understand when to use this tool.

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

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

The description provides explicit guidance on when to use the tool ('when you discover something worth carrying forward'), and names alternatives ('Pair with recall to retrieve later, forget to delete'). This helps the agent decide between siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which provides helpful 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?

Description is well-structured with examples and clear guidance. Slightly verbose but each sentence adds value. Front-loaded with user queries and supported types.

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?

Fully covers inputs, outputs, and internal behavior for a lookup tool with no output schema. Includes citation URIs and auto-disambiguation. No gaps given the tool's purpose and 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%. Description adds meaning by listing accepted input formats (ticker, CIK, name for company; brand or generic for drug) and outputs (ticker+CIK+name, RxCUI+ingredient+brand). Enhances understanding beyond schema enums.

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

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

Description explicitly states the tool resolves names to canonical IDs, provides example queries (ticker, CIK, RxCUI), and distinguishes itself as the first step when needing an ID. The verb 'resolve' and resource 'entity' are clearly defined.

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 FIRST whenever you have a name but need an ID.' Lists supported entity types with input/output details. Does not mention negative cases or alternatives, but context is clear given sibling tools like 'compare_entities' and '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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable behavioral context: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density, and treats first entity as subject. No contradictions.

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

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

Three well-structured sentences: purpose, process, example. Front-loaded with verb 'Compare' and key resource 'AI visibility'. No unnecessary words. 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?

No output schema, but description specifies return fields (ranked list with score, confidence, signal density). Covers required usage context (entities, optional parameters). Annotations handle safety. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions for all 4 parameters, meeting baseline of 3. Description adds semantic nuance: entities array's first entry is treated as 'subject' for narrative, rest as competitors. Also explains context parameter purpose. This adds value beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility audit context.

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: 'Useful for competitive AI-marketing audits' and an example question. Implicitly tells when to use (multi-entity comparison) but lacks explicit when-not-to-use or alternatives beyond mentioning it uses ai_visibility_check.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context about partial failures (bundlephobia timeout), fan-out across external services, and graceful degradation. No contradiction with annotations.

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

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

The description is somewhat long but well-structured, front-loading key purpose and use cases. Every sentence adds value, though slight tightening 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?

Given no output schema, the description thoroughly explains the return shape and behavior (summary fields, failure modes, ecosystem limitation). Complete for a composite check tool with external dependencies.

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

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

Schema coverage is 100% for 2 parameters, but description adds significant meaning: explains default behavior for 'version' (latest published), details return fields (summary block, per-advisory, links, alternative versions). This goes well beyond schema.

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

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

Description clearly states it's a composite check for adding npm packages, covering licenses, advisories, version history, and bundle size. Uses specific verb 'scan' and resource 'dependency', and distinguishes from sibling tools like deps.dev:version for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Includes guidance on partial failures and timeout 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This provides valuable behavioral context beyond the annotations.

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

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

The description is a single paragraph but clearly structured: purpose, use case, pairing, technical details. Every sentence adds unique value. No fluff or repetition.

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

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

Despite no output schema, description covers input, output (top-N passages with offsets and scores), behavior (embedding model, windowing), and limits (200K chars). Sibling tools do not include similar search-within, so no missing context. Completely adequate for agent selection.

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 each parameter. Description reinforces parameter usage: explains how text and query relate, mentions limit but not its default. Adds context like 'Pass the text you already pulled' and 'natural-language query' examples. Adds value beyond schema without being redundant.

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 starts with 'Semantic search INSIDE a fetched record' – a specific verb+resource+method. Distinguishes from siblings by focusing on inside a record, while siblings like ask_pipeworx_grounded are for grounded generation. No confusion.

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 when the record is too big to cram into the prompt' and pairs it with ask_pipeworx_grounded. Does not explicitly state when not to use, but provides clear context and an alternative tool for generation tasks.

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

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

Description thoroughly discloses behavioral traits: requires OAuth account, supported types with examples, delivery channels with constraints (email, SMS with cap and verification, webhook with HMAC signing and auto-disable). This goes well beyond annotations (readOnlyHint=false, idempotentHint=true) by adding practical usage details.

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

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

The description is fairly long but well-organized: purpose, requirements, type examples, delivery options. Every sentence adds value, though it could be slightly more concise. It fronts the main purpose and then provides details.

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

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

Given the complexity (3 params, nested objects, 5 enum types, multiple delivery options), the description covers all essential aspects: usage, type-specific params, delivery constraints, and post-subscription behavior (webhook secret, auto-disable). No output schema, but return of subscription id is noted.

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

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

With 100% schema coverage, the description adds significant meaning: explains each type's params with examples (e.g., sec_8k items, fred_series series_id), optional delivery fields with constraints, and required fields for clinical_trial. This helps an agent construct correct parameter objects.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the subscription id. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of persistent subscriptions.

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

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

The description provides clear context: requires a Pipeworx OAuth account, lists supported types, and mentions delivery channels. It does not explicitly state when not to use or compare to alternatives like ask_pipeworx or recent_alerts, but the guidance is sufficient for an informed agent.

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 context: it's the onboarding entry point, returns example questions with tool shapes, and can be called with no arguments or with a topic. This adds value beyond annotations without contradiction.

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

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

The description is verbose with many synonyms and a list of categories. While it is front-loaded with the core intent, it could be more concise. Each sentence adds value, but the length is somewhat excessive for the information conveyed.

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

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

Given the tool's simplicity (one optional param, no output schema, good annotations), the description fully covers when to use, how to use, what it returns, and alternatives. It explains the return format (category-bucketed examples with tool shapes). No gaps.

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

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

Schema coverage is 100% for the single optional topic parameter. The description adds value by listing possible values (finance, pharma, economics, etc.) and explaining the effect of omitting the parameter (cross-category spread). This goes beyond the schema's description.

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

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

The description clearly states the tool returns category-bucketed example questions with tool/argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point. The synonyms and use cases reinforce the purpose.

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

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

The description explicitly says to use this FIRST when the agent does not know what Pipeworx can do, or to learn how to call meta-tools. It provides context and lists alternatives like ask_pipeworx, entity_profile, compare_entities, making it easy to decide when to use.

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

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

Annotations declare readOnlyHint false, destructiveHint false, idempotentHint true. The description adds meaningful behavioral details: ownership enforcement, deactivation (not deletion), and linkage to recent_alerts for history. This goes beyond annotation info without 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 concise sentences. The first sentence immediately states the action and resource. The second provides critical behavioral context. No redundant or 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?

For a simple mutation tool with one parameter and no output schema, the description covers purpose, side effects, ownership rules, and impact on historical data. Missing return value details, but that is acceptable given lack of output schema. Overall well-rounded.

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 100% description coverage for the single parameter (id). The description does not add any further parameter semantics beyond what the schema already provides. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states 'Cancel a subscription by id.' It uses a specific verb (Cancel) and resource (subscription), and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by describing the action and side effect.

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

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

The description provides context on when to use this tool: 'Ownership is enforced — you can only cancel your own subscriptions.' It also clarifies that it's a deactivation, not deletion, preserving historical data. However, it does not explicitly list when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: two processing paths (SEC EDGAR+XBRL for financial claims, grounded pipeline for others), exact percent-delta math, return verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported), and citation. This provides significant value beyond annotations without 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 detailed but well-structured: it starts with trigger phrases, explains the two-path behavior, return format, and efficiency. Every sentence adds value for a tool of this complexity. Could be slightly shorter, but the density of information justifies the length.

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

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

Given the tool's complexity and the absence of an output schema, the description completely explains what the tool does, how it works (two paths), and what it returns (verdict, value with citation, reasoning). No gaps are evident for a tool of this nature.

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 described. The description adds extra semantics: tolerance_pct overrides implied tolerance, default is implied by wording capped at 5, and provides examples of claim inputs. This exceeds the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger phrases ("Is it true that…", "fact check") and distinguishes itself as a unified path for both company-financial and other claims, replacing multiple sequential calls. This makes the purpose highly specific and distinct from siblings.

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

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

The description explicitly states when to use the tool: "Use whenever the agent needs to check whether something a user said is factually correct." It also provides example trigger phrases. However, it does not explicitly exclude use cases or compare against specific sibling tools like ask_pipeworx_grounded, though the specialization is implied. Clear usage context but no alternatives.

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