Brave Search

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 crucial details: default free model, requirement of _apiKey for Anthropic with direct billing, and per-model return structure. 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 sentences, front-loaded with core purpose, followed by key defaults and use cases. Every sentence is informative 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 no output schema, the description adequately explains return values (per-model {score, confidence, signals, raw_response} + combined view). It covers all behavioral aspects and use cases, making the tool self-contained.

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

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

Schema coverage is 100% with clear descriptions for all 4 parameters. The description adds value by explaining the default model, the role of _apiKey, and the purpose of context, going beyond the schema alone.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for visibility scoring (0-100) per model'. It distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by specifying its unique output and use case.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use the tool or mention alternatives, but the context implies differentiation from sibling tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, already covering safety. The description adds useful behavioral context: it routes to sub-tools, fills arguments, returns structured answers with stable citation URIs, and mentions it is a fast single call. It doesn't overpromise or contradict annotations, though it doesn't address edge cases like missing data.

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

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

The description is long but every sentence serves a purpose: directive, domain scope, usage triggers, examples, alternatives, and additional notes. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured logically, earning its length without being redundant.

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 substantial complexity (5,334 tools, 1,393 sources) and no output schema, the description covers the essential context: what it does, when to use it, what alternatives exist, and what the response looks like (structured answer with citations). It also mentions tier compatibility, making it sufficiently complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, with the 'question' parameter fully documented and aliases listed. The tool description's examples and domain list provide usage context, but that is not required for parameter semantics since the schema already carries the burden. Baseline 3 is appropriate; no additional parameter-level detail is missing.

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

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

The description names a specific verb ('asks'/'routes') and resource (Pipeworx's 5,334 tools across 1,393 sources), and clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It also provides a concrete list of domains and example questions, making the tool's 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 prefer this tool over web search, gives trigger phrases ('what is', 'look up', 'find', etc.), and names alternatives (ask_pipeworx_grounded, deep_research) for specific use cases. It also provides examples and positions itself as the default entry point, offering clear decision guidance.

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

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

The annotations already convey read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: beta status, dynamic enabling of candidate routing improvements, current state (no candidate active), and that it remains a full working router. It does not detail potential changes when a candidate is under test, but the disclosure is adequate.

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

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

The description is dense and well-structured, with each sentence serving a purpose: establishing identity, explaining dynamic behavior, noting current status, giving usage guidance, and affirming full functionality. It avoids fluff and front-loads key 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?

The tool is a high-complexity router with no output schema, but the description adequately orients the agent by referencing ask_pipeworx for the response shape and explaining current status. It is not fully self-contained, but the reference to a sibling tool is acceptable in context.

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

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

All 6 parameters are aliases for 'question' and the input schema provides complete descriptions for each (100% schema coverage). The description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router that handles the same 5,334 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental/beta nature and current equivalence.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router for merge decisions. This provides a clear when-to-use condition and implies the stable ask_pipeworx is the alternative for stable routing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds crucial behavioral context: it extracts answers only from tool results, returns explicit refusal reasons when data doesn't directly answer, and notes an extra LLM call cost. 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: states purpose, mechanism, output shape, usage guidance, and cost tradeoff in four sentences. Every sentence carries distinct information, with no redundancy or fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly covers behavior, return format (including refusal reasons), use cases, and relationship to sibling tools. It is complete enough 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?

The input schema has 100% coverage with all six parameters documented as aliases for the question. The description doesn't add parameter-level detail, but the parameter is self-explanatory (natural language question), so the baseline of 3 applies.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific mechanism (routes to a tool, extracts answer using only the result). It explicitly distinguishes from sibling ask_pipeworx by describing the same routing plus grounded extraction and structured refusal handling.

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

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

Provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also states when not to use and names the alternative: 'prefer ask_pipeworx for casual lookups.'

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

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

The description is highly transparent about the tool's behavior. It explains the fan-out mechanism per category, response shapes, resolver contract with confidence levels, parent event extraction, news fields with fallback handling, safety short-circuits, and cancellation rule parsing. Annotations (readOnlyHint, idempotentHint, etc.) are consistent with the described read-only, idempotent research operation. 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 well-structured with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, etc.) and begins with a concise summary. While it is lengthy, every paragraph adds necessary detail for safe and effective tool use. A minor improvement could be trimming some redundant explanations (e.g., the blocking mechanism for closed markets), but overall it earns its length.

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

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

Given the tool's complexity (3 parameters, no output schema, many siblings), the description is exceptionally comprehensive. It covers input resolution, fan-out logic per category, response structure, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and even response size considerations. This completeness enables an agent to use the tool correctly without guessing.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description adds significant value: examples for 'market', explanation of 'depth' values ('quick' vs 'thorough' with source counts), and context for 'include_raw' (summarized vs full payloads). This enriches the schema beyond basic type/constraint info.

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 the action (research), resource (Polymarket bet), and method (pass slug, URL, or question text). It also distinguishes itself from sibling tools by providing use cases like 'should I bet on X' and listing classifiers and examples, making it unique among the many related tools.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to inspect output fields (market_match_confidence) and describes blocking conditions (low-confidence short-circuit, closed markets, wide spreads). While it doesn't explicitly compare to siblings, the given use cases and blocking conditions offer clear usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: off-calendar fiscal years handled correctly, results sorted by primary metric, returns paired data with citation URIs. No contradictions.

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

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

The description is front-loaded with query examples and gets to the point quickly. It is slightly long but every sentence provides useful information. No filler or redundancy.

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

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

Given no output schema, the description compensates by explaining return format (paired data + citation URIs) and sorting behavior. It handles complexity like off-calendar fiscal years and explains the tool replaces 8–15 lookups, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the enum values (company vs drug), specifying input formats (tickers/CIKs for companies, names for drugs), and noting min/max items. It also clarifies that results are sorted by primary metric.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs. It provides specific example queries and distinguishes from sibling tools by explicitly preferring this over sequential lookups. The verb 'compare' and resource 'entities' are precise.

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

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

The description gives clear usage context: use when comparing entities, prefer over sequential lookups. It also explains what each entity type pulls. However, it does not explicitly state when not to use or list alternative tools for specific scenarios.

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

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

Despite annotations already indicating readOnly/openWorld/idempotent, the description adds rich behavioral context: account/auth prerequisites, parallel decomposition across 5,334 tools, return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), hop and citation_uri fields, semantic excerpting, and expected latency (15-90s). It also discloses that breaking-news topics yield mostly empty gaps[]. No contradiction with annotations.

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

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

The description is long but well-organized and front-loaded with critical account requirements. Each sentence contributes unique value, though the depth details in the 'Second-hop iteration' paragraph partially duplicate the schema's depth description. Could be tightened but earns its length given the tool's complexity.

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

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

With no output schema, the description thoroughly explains return values: findings packet, gaps[], contradictions[], hop field, citation_uri, semantic excerpting. It also covers account prerequisites, alternatives, parameter nuances, and performance expectations. This is 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 covers 100% of parameters, so baseline is 3. The description adds meaningful context beyond the schema: the 'thorough' depth requires a paid plan, and latency expectations vary by depth (up to ~90s). It also reinforces the 'question' parameter's natural-language usage with examples. Slight redundancy with the schema's depth description prevents a higher score.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources.' It explicitly differentiates from siblings by saying 'this is NOT open-web search' and distinguishing when to use ask_pipeworx instead. This is far beyond a tautology or vague 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 gives explicit when/when-not guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also notes the account requirement and the paid plan condition for depth:'thorough', providing clear alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full input schemas and curated examples, ready to call. 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 somewhat long but is dense with useful information and front-loaded with purpose. Every sentence adds value, though minor trimming possible.

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

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

For a simple tool discovery tool, the description covers how it works, what it returns, and when to use it. No output schema needed; completeness is high given context.

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

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

Schema has 100% parameter coverage with descriptions. The description adds context about aliases and natural language usage examples, going beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing a data or task, listing many example domains. It distinguishes itself from siblings by being the discovery tool to call first.

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

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

Explicitly tells to use this tool first when many tools are available to see options, and when needing to browse or discover tools. Does not specify when not to use, but positive guidance is clear.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description adds valuable context: returns specific fields (cik, recent_filings with URIs, fundamentals sorted, patents soft-fail, news fallback), and explains source dependencies. No contradictions.

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

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

Well-structured with examples first, then details on return fields and caveats. Slightly long but every sentence adds value. Front-loaded with key examples.

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 all aspects: intended use, data sources, return values, edge cases (soft-fail, name unsupported). No output schema, but description fully explains expected results. Complete enough for an agent to invoke correctly.

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

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

Both parameters have schema descriptions (100% coverage). The description adds usage examples and clarifies that names are not supported via the 'value' field, enhancing real-world 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 explicitly states the tool provides a 'full cross-source profile of a US public company' with example queries. It clearly distinguishes from siblings by recommending preference over chaining single-source 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes 'names not supported (use resolve_entity first if you only have a name)'. Also mentions patent API 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description confirms deletion but adds no behavioral details beyond what annotations convey.

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

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

Three focused sentences with no waste. The action and use cases are front-loaded, making the purpose immediately clear.

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 parameter, no schema options, no output schema), the description fully covers its behavior and usage context.

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

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

The input schema already describes the 'key' parameter (100% coverage). The description adds no additional parameter semantics 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?

The description clearly states the action 'Delete' and the resource 'previously stored memory by key', and the verb-resource combination distinguishes it from siblings like 'remember' and 'recall'.

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

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

Specifies multiple concrete use cases: when context is stale, task is done, or clearing sensitive data. Also explicitly pairs with 'remember' and 'recall'.

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) already indicate safe, read-only behavior. The description adds meaningful context: it fetches the page, extracts content, and emits standard markdown format. 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 with two short paragraphs, front-loading the core action and purpose. Every sentence adds value (what it does, how it outputs, use cases). 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 tool's simplicity and full schema/annotation coverage, the description is complete: it explains output format (markdown), intended placement (site-root/llms.txt), and provides use cases. No missing critical details.

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

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

Schema description coverage is 100% (both 'url' and 'max_links' are documented). The description does not add new meaning beyond the schema (e.g., it mentions 'max_links' explicitly but no format or constraints). Baseline 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for a URL, explaining the specific verb ('generate'), resource ('llms.txt'), and action ('fetches page, extracts title/description/key links, emits markdown'). This distinguishes it from siblings like 'scan_competitor_ai_presence' or 'web_search'.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'), providing clear context for when to use. However, it does not mention when not to use or specify alternatives among 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 declare readOnlyHint and idempotentHint, so the description does not need to reiterate safety. It adds value by specifying returned fields and parameter behavior, though not strictly necessary.

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

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

Two sentences, front-loaded with the core purpose, no redundant information. Every word earns its place.

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

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

Given low complexity (1 param, no output schema), the description is complete: it explains return fields, usage, and parameter in the schema. No gaps remain.

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 schema already describes include_inactive. The description does not add further parameter meaning beyond what is in the schema.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). This distinguishes it from siblings 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?

Explicitly advises 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear guidance on when to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing safe read behavior. The description adds value beyond annotations by specifying return fields and mentioning 'publication metadata' and 'breaking-news flag.' Some behavioral details (e.g., rate limits, pagination) are omitted but not critical given the safety profile.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. No fluff or redundancy.

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

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

Given the presence of an output schema and high schema coverage, the description is sufficient for most use cases. It explains what is returned but could briefly mention how parameters like 'freshness' affect results. Still, it avoids gaps for a news-search tool.

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

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

The input schema has 100% coverage with descriptions for all 6 parameters. The description does not add any parameter-specific information beyond what the schema already provides, so the score is at baseline.

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

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

The description clearly states it is a 'News-specific search' tool, specifies the verb 'search' and resource 'news', and lists exact return fields (title, URL, source, age, snippet, breaking-news flag). This distinguishes it from sibling tools like 'web_search' by emphasizing news focus and metadata.

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 term 'News-specific search' implies use for news queries, but no explicit guidance on when to use this vs. alternatives like 'web_search' or when not to use it. No exclusion criteria or alternative tool names are mentioned.

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 rate limits (5 per identifier per day), cost (free, no quota impact), and how feedback is processed (digests daily, signal affects roadmap). Annotations (readOnlyHint=false) are consistent; 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 compact (3-4 sentences) yet comprehensive. Purpose, usage, formatting guidance, and behavioral notes are front-loaded. Every sentence carries essential information.

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

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

Given the tool's simplicity (3 params, nested object, no output schema), the description covers everything needed: purpose, when to use, parameter semantics, rate limits, and processing details. 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%, but the description adds valuable semantics: explains the 'type' enum in detail, advises against pasting user prompts for 'message', and clarifies the 'context' object's purpose. This goes beyond the schema.

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

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

The description clearly states it sends feedback about bugs, missing features, or praise, using specific verbs like 'tell' and 'broken/missing/needs to exist.' It distinguishes from siblings by its unique feedback-collection purpose; no other sibling tool offers this function.

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

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

Explicitly states when to use: when a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or when something worked well (praise). Also provides a clear 'don't' instruction: describe in terms of tools/packs, not pasting end-user prompts.

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 safety profile (readOnly, openWorld, idempotent, non-destructive). The description adds context about data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which further discloses behavior beyond annotations. No contradiction.

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

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

The description is front-loaded with core function, follows with bullet points for use cases, and ends with technical details. It is concise without unnecessary words, though slightly long.

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

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

Without an output schema, the description adequately explains what is returned (top tools, top packs, total call volume) and provides caching details. For a simple read-only tool with one optional parameter, this is sufficient.

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

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

Schema coverage is 100% with a well-described optional enum parameter. The description reaffirms the window options but adds no new meaning beyond the schema. 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 the tool returns top tools, top packs, and total call volume over a recent window, which is a specific and unique purpose. It distinguishes itself from siblings like 'discover_tools' which list available tools, not trending usage.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) that guide when to use. It doesn't explicitly mention when not to use or compare to siblings, but the context is clear and helpful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds valuable context: it explains scanning, monotonicity and partition checks, fill check against CLOB depth, placeholder filtering, and similarity thresholds, without contradicting 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?

While the description is well-structured with clear sections, it is quite verbose and contains excessive technical detail. The first sentence front-loads the purpose, but subsequent paragraphs could be more concise to improve readability.

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

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

The description thoroughly explains the return format (opportunities[], partition_check, fill check details) despite no output schema. It covers multiple modes, edge-case filtering (placeholders, similarity), and trade recommendations. No major gaps are apparent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining what event slugs and topic seeds look like, giving concrete examples, and detailing behavior for each parameter (e.g., 'walks child markets, checks ordering...' for event, 'searches related events...' for topic).

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

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

The description explicitly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's function from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique modes (event, topic, trending).

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: 'Call with NO args for a trending_scan', 'pass event for... partition_check', 'topic for cross-event scan'. It also includes recommendations ('event recommended for a specific market'), conditions to avoid ('do not trade it' when fill check negative), and explains when cross-event mode is advantageous.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant context: caching (1h KV), diagnostics for empty segments, Fed bets exclusion, specific model details (e.g., per-sport alpha for favorite-longshot bias), and a warning that edge may already be priced in. 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 comprehensive but verbose, packing detailed model explanations and diagnostics into paragraphs. While front-loaded with purpose, it could be more concise without losing essential information. Still functional for an AI agent.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description is exceptionally complete. It explains response structure (by_segment, fed_candidates, _diagnostics), caching, filter behaviors, and edge calculations, ensuring an agent knows what to expect despite the absence of an 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 coverage is 100% with detailed parameter descriptions. The description adds some context (e.g., min_kelly refers to half-Kelly, max_spread_pp as tradeable filter), but the schema already covers meaning adequately. 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, targeting the 'what should I bet on today' use case. It distinguishes itself from sibling tools by detailing three distinct model families and segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its unique value clear.

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

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

The description provides extensive guidance on when to use the tool, including the tradeable-edge knobs and filters for customizing output. However, it lacks explicit comparisons to sibling tools or stated when-not-to-use scenarios, slightly reducing clarity for an AI agent deciding between alternatives.

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

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

The description fully discloses behavior: read-only telemetry, snapshot data source, time-series computation, trend classification, and limitations (TTL, snapshot gaps). Annotations already indicate readOnlyHint and idempotentHint, and the description adds valuable context without contradiction.

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

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

The description is detailed but well-structured with clear sections for purpose, response fields, and limits. It is slightly verbose but every sentence adds necessary context, earning a 4.

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

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

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and data nuances (trend, decay, lifespan). This makes it complete for an agent to understand the output.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds practical defaults (days=14, window=1wk) and constraints (max 30 days), providing extra 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: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series 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 it (to assess if an edge is fresh or old and decaying) but does not explicitly mention when not to use it or compare to alternatives, though the context is clear.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description is not required to repeat that. The description adds significant behavioral details beyond annotations: it walks the order book ladder, returns specific metrics like top_of_book, vwap_fill_price, slippage, shares_filled, verdict, and warns about forced directional risk. 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 dense but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the purpose and uses punctuation and line breaks for readability. Every sentence adds value, from the functional description to usage guidance and risk warnings.

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

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

There is no output schema, but the description comprehensively lists all return fields for both modes: top_of_book, vwap, slippage, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It also explains the practical risk of partial fills, making the tool self-contained for the agent.

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

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

Schema coverage is 100%, but the description adds crucial meaning beyond schema. It explains that size_usd interpretation differs between single-market (max spend on buys, target proceeds on sells) and basket (settlement notional, shares per leg). It clarifies default side logic for basket (auto from partition sum). This enables the agent to use parameters correctly.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and the purpose is well differentiated from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on risk assessment.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns when not to rely on theoretical edges on thin books and explains the risk of partial basket fills converting an arb into an unhedged directional position.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds substantial behavioral context: how matching works, safety fields (compatibility_warning, temporal_alignment), and why spreads may be invalid. No contradiction with annotations.

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

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

The description is long but well-structured with bullet points, bolding, and clear sections. It front-loads the main purpose and each sentence adds value. 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?

Despite no output schema, the description comprehensively explains the response structure (leg-by-leg prices, spreads array, safety fields) and edge cases. For a tool with 3 parameters, this is thorough and leaves no ambiguity.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds meaning beyond schema: it explains the two modes, enumerates topic values, describes how explicit tickers override, and includes examples. This adds significant value for an agent.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts vs explicit tickers) and explains the output (leg-by-leg prices, spreads). This differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides extensive guidance: it explains when to use each mode, when the spread is meaningful, and when compatibility_warning fires (non-equivalent bet shapes, semantically unrelated events, temporal misalignment). It even warns that most pre-mapped topics return warnings today, 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, idempotentHint, destructiveHint. Description adds scope details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which adds value 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?

Three sentences, front-loaded with action. Every sentence adds value without redundancy. Efficient and clear.

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 1-parameter tool with good annotations and no output schema, the description is complete. It covers purpose, usage, scope, and pairing with siblings.

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 parameter. Description adds that omitting the key lists all keys, which is not in the schema description, providing actionable semantics.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all saved keys. It distinguishes from siblings 'remember' and 'forget' by specifying its complementary role.

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

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

Description provides explicit usage guidance: use to look up context stored earlier without re-deriving. It explains the optional key argument to list all keys. It does not explicitly state when not to use, 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?

Discloses the side effect of 'mark_read:true' on subsequent calls, and confirms read-only behavior via annotations. No contradictions; description adds context beyond annotations.

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

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

Four sentences front-load the main purpose and provide supplementary details without verbosity. Every sentence adds value.

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

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

Despite no output schema, the description adequately describes the return fields (source, citation_uri, payload). All parameters are explained, and usage context is sufficient for complex optional parameters.

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

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

Schema covers 100% of parameters, and description adds meaningful context (e.g., example type 'sec_8k', explanation of 'mark_read' effect) that goes beyond the schema alone.

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

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

The description uses a specific verb 'Pull fired events' and identifies the resource 'subscription feed'. It clearly distinguishes from sibling tools like 'list_subscriptions' by focusing on events/alerts data.

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

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

Explicitly mentions filtering options and provides an alternative endpoint for scripts/dashboards. While it doesn't list all when-not scenarios, the context is clear enough for an agent to decide.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: fans out to multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), explains fallback logic ('GDELT preferred, GNews when rate-limited or 5xx'), and notes the PatentsView API sunset. 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 dense and front-loaded with query examples, but it runs to 4 sentences and includes technical details about API fallbacks and sunset dates. While efficient, it could be slightly more concise without losing clarity. However, every sentence adds distinct value.

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

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

Given no output schema, the description adequately summarizes the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers three diverse data sources, fallback behavior, and parameter formats, leaving no major gaps for a monitoring 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 already has 100% coverage with clear descriptions. The description adds valuable context: concrete relative shorthand examples for `since` ('7d', '30d', '3m', '1y') and the recommendation 'Use "30d" or "1m" for typical monitoring'. For `value`, it provides examples of both ticker and CIK formats, enhancing usability beyond schema.

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

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

The description starts with concrete query examples ('What's new with X', 'latest on Y') that immediately clarify the tool's purpose as a change feed for companies. It explicitly distinguishes from sibling entity_profile ('Use entity_profile instead when you want the static profile'), establishing clear 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?

Provides explicit guidance on when to use this tool (query language examples like 'updates on Acme') and when not to ('Use entity_profile instead'). Mentions sibling tool by name, giving clear context for selection.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. The description adds valuable context: memory is key-value, scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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 a single, well-structured paragraph. It front-loads the purpose, then explains when to use, how it works, and related tools. Every sentence adds value; no wasted words.

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

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

For a simple write tool with two string parameters and no output schema, the description fully covers usage, storage behavior, scope, retention, and pairing with recall/forget. Annotations handle safety hints. Complete.

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

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

Schema coverage is 100% with descriptions. The description adds real-world examples (e.g., 'subject_property', 'target_ticker') and clarifies the value can hold any text, enhancing understanding beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data') and clearly states the tool's purpose: storing data for reuse across conversations or sessions. It distinguishes itself from sibling tools like recall and forget by explaining the pairing.

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

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

The description explicitly states when to use this tool ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). It also clarifies scope and persistence depending on authentication.

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 behavior. Description adds that each call cascades through several internal lookups, replacing 2-3 manual steps, and mentions citation URIs per type—valuable 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 concise yet packed with examples and details. It front-loads the core purpose and supports specific usage. Every sentence contributes value, though slightly more structure could help.

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 and moderate complexity (two entity types, internal cascading), the description covers purpose, parameters, return values, and usage context comprehensively. Annotations handle safety, so 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 covers 100% of parameters with descriptions. Description adds output details per type (e.g., returns ticker+CIK for company, RxCUI+ingredient for drug), which the schema lacks, thus adding meaning.

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

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

The description clearly states the tool resolves a name to a canonical identifier, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by focusing on identifier resolution, not other functions like searching or validating.

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,' providing strong when-to-use guidance. Does not explicitly list alternatives, but the context is clear enough.

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

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

Description details probing mechanism, ranking, and output fields (score, confidence, signal density), complementing annotations that mark it as read-only, idempotent, and non-destructive.

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

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

Two sentences: first clearly defines action, second adds usage and output details. 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 all aspects: purpose, parameters, usage, output format, and behavioral traits, especially since output schema is absent.

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, but description adds context on entity count range, first-as-subject, context disambiguation, and models usage.

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?

States specific verb 'Compare' and resource 'AI visibility across entities', distinguishes from siblings like ai_visibility_check and compare_entities by specifying side-by-side comparison and ranking.

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 use case example ('competitive AI-marketing audits') and related tool (ai_visibility_check), but lacks explicit when-not or alternative exclusions.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds key behavioral traits: graceful degradation, bundlephobia latency (5-30s on first measure), and sources_failed listing. 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?

Description is concise yet information-dense: composite check, usage, return summary, ecosystem scope, failure behavior. Every sentence adds value; front-loaded with purpose.

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

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

No output schema, but description covers return structure (summary block, advisories, links, alternatives). Parameters fully covered. All necessary context for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enhances by mentioning scoped packages are accepted for 'package' and default behavior for 'version'. Adds value beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for npm package quality, fans out across deps.dev and bundlephobia. It specifies the verb-resource combination (scan_dependency for npm packages) and distinguishes from siblings by focusing on npm ecosystem only.

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

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

Explicitly states when to use (agent asks about safety, popularity, size) and when not to (other ecosystems fall under different tools). Also provides guidance on partial failures and timing.

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, etc.), description discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), char limit (200K), and truncation flagging. Also states output includes character offsets and similarity scores, enabling verification.

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

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

Description is 4 sentences, each earning its place: purpose, usage, pairing, technical details. No fluff; front-loaded with main idea. Efficient and well-structured.

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

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

Given no output schema, description still explains return format (passages with offsets and scores). Annotations cover safety and idempotency. Technical constraints (200K char limit, embedding details) are provided. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% but description adds valuable examples and context: for 'query' gives natural language examples like 'supply-chain risk'; for 'text' notes max 200K chars; for 'limit' implies default 5 and range 1-20. Adds meaning beyond the schema entries.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' — specific verb (search inside), resource (fetched record), and context (after fetch). It distinguishes from sibling 'ask_pipeworx_grounded' by explaining how they pair together.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only passages that matter). Also notes the 200K char cap and truncation behavior, providing clear guidance on when the tool is 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?

Beyond annotations (e.g., idempotentHint=true, destructiveHint=false), the description reveals prerequisites (OAuth account), delivery constraints (sms verification, 10/day cap, webhook auto-disable), and returns subscription id. 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 the main purpose and is structured into clear sections: general statement, prerequisite, types, delivery channels. 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 tool's complexity and lack of output schema, the description covers prerequisites, types, delivery details, and return value. It is sufficient for correct agent invocation.

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

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

The description adds significant meaning to each parameter, e.g., explaining type-specific filter formats and delivery subfields, going well beyond the schema's descriptions. Schema coverage is 100%, but the description enriches 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 action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context for when to use the tool (creating subscriptions) and details on parameters and delivery options, but does not explicitly state when not to use it or reference alternatives (though siblings are available).

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 beyond annotations by detailing that it returns example questions with tool+argument shapes and is the starting point for discovering capabilities.

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-structured with parentheses for examples and front-loading of key phrases. Every sentence adds value, though it 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 adequately explains that it returns category-bucketed example questions with tool+argument shapes. It covers the tool's purpose, usage, and behavior fully for its simple interface.

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 one optional parameter. The description adds meaning by explaining that omitting topic yields a cross-category spread and providing example values like 'finance', 'pharma', etc., which 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 that this tool is the onboarding entry point for learning what Pipeworx can do. It specifies the verb 'ask' and resource 'Pipeworx', and distinguishes from siblings by emphasizing its role as a first-use tool for getting started and understanding meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides clear context for when to use it (onboarding) and implies it should be used before other tools, though it doesn't explicitly 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?

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds important behavioral context beyond the annotations (idempotent, non-destructive). No contradiction with annotations.

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

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

Two concise sentences, both informative and front-loaded with the main action. No unnecessary words.

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

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

For a simple 1-parameter tool with full schema coverage and no output schema, the description provides complete context: purpose, usage constraint, and behavioral outcome. Nothing is missing.

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

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

Schema coverage is 100% with parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds the context that the id comes from subscribe, which is helpful but not extensive. 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 explicitly states the action ('Cancel a subscription') and the resource ('by id'). It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 a clear constraint: 'Ownership is enforced — you can only cancel your own subscriptions.' This guides usage, though it doesn't explicitly state when to use this tool over alternatives.

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

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

The description adds significant context beyond the annotations (readOnlyHint, openWorldHint, etc.), including the exact handling of financial claims (percent-delta math) and the fallback to a grounded pipeline. It also details the return verdicts (confirmed, approximately_correct, etc.) and citation format, which the annotations do not cover.

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 trigger phrases and purpose, then explains the two paths succinctly. It efficiently covers output and use-case. The list of query patterns is slightly verbose but serves as helpful triggers. Overall, well-structured and 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 adequately explains the return values (verdict, value with citation, reasoning). It covers the dual processing logic and includes efficiency claims (replaces 4-6 calls). No major gaps for a factual verification 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 descriptions for both parameters. The description adds context about tolerance_pct overriding implied tolerance and its use for hallucination detection. The claim parameter is illustrated with examples, enriching 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 starts with explicit query patterns ("fact check", "verify the claim") and clearly states the tool's purpose as "natural-language claim verification against authoritative sources." It distinguishes financial claims (SEC EDGAR+XBRL) from other claims (grounded pipeline), making it unique from sibling tools like deep_research or web_search.

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

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

It explicitly states "Use whenever the agent needs to check whether something a user said is factually correct" and explains the dual-path routing. While it does not explicitly list when not to use, the purpose is so specific that the usage context is clear. The mention of replacing 4-6 sequential calls also guides efficiency.

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 minimal behavioral context beyond naming the Brave index and return fields. No contradictions.

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

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

Two concise sentences that front-load the core purpose and immediately list return fields and optional filters. No extraneous words.

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

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

The description covers purpose, return fields, and optional filters. Output schema exists for return values. Minor omission: no mention of pagination/offset, but that's documented in the 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 coverage is 100% with detailed parameter descriptions. The description mentions 'Optional country, language, safesearch, and freshness filters,' which restates schema content without adding significant new meaning.

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

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

The description clearly states it performs a 'General web search via the Brave index' and lists specific return fields (title, URL, description snippet, etc.). This distinguishes it from sibling tools like deep_research or news_search.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., deep_research, news_search). The description implies general search but lacks 'when to use' or '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.