Ca Procurement

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds significant behavioral context: default model, cost implications for Anthropic probes, and return format (per-model score/confidence/signals/raw_response + combined view). 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?

Four sentences front-load the core action, then add necessary details (default, key, returns, uses). No wasted words; every sentence earns its place.

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

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

All four parameters are described, return format is summarized (per-model + combined view), and use cases are provided. No output schema exists, but the description compensates well. Given the tool's moderate complexity, this is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for the `models` parameter, the purpose of `_apiKey` (BYO key), and how `context` disambiguates common names. This goes beyond the schema definitions.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business / brand / product / topic and score visibility'), clearly distinguishing it from sibling tools like entity_profile or deep_research. It also specifies default model and optional provider.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool or name alternatives.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context beyond safety: it 'fills arguments', 'returns the structured answer with stable pipeworx:// citation URIs', 'works on every tier', and 'one fast call'. It also clarifies how breaking-news queries are routed. Minor gaps, like failure modes or latency, are not disclosed, but overall the behavioral profile is well explained.

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

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

The description is longer than average but is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and every sentence contributes to selection or usage guidance. The examples and alternative-tool comparisons earn their place, though some redundancy (e.g., 'START HERE' restated) prevents a perfect score.

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

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

Despite having no output schema, the description specifies the return format ('structured answer with stable pipeworx:// citation URIs') and covers the full range of inputs, use cases, trigger phrases, and sibling distinctions. For a one-parameter tool, this is comprehensive and leaves no major gaps for an agent choosing or invoking the 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 a single required parameter 'question' and five documented aliases. The description provides example queries but does not add new parameter-level semantics beyond what the schema already describes. Baseline 3 is appropriate since the schema carries the weight.

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 a general-purpose factual question-answering router that 'routes the question to the right one of 5,526 tools across 1453 verified sources' and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and even names when to step up: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also gives trigger phrases and examples, making the selection criteria concrete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond those: beta status, live candidate activation, current state of matching ask_pipeworx, and that it is a full working router rather than a stub. 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 moderately detailed but every sentence serves a purpose: explaining beta nature, current routing state, usage, and comparison behavior. It is front-loaded and not wasteful, though it could be slightly tightened without losing key context.

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

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

Despite lacking an output schema, the description covers the response shape by referring to 'same response shape' as ask_pipeworx. It fully explains the tool's current behavior, relationship to the stable router, and fallback nature, making it complete for an agent deciding to invoke it.

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

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

Schema coverage is 100%, with all six parameters and their aliases fully documented in the input schema. The description adds no parameter-specific detail beyond 'same arguments' as ask_pipeworx, so it does not improve on what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,526 tools and response shape. It explicitly distinguishes it from the stable ask_pipeworx by noting it runs candidate routing improvements, making its purpose and differentiation from siblings 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?

It explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router and mentions that results are compared, providing clear usage context without needing to exclude 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 mark readOnly/idempotent/openWorld, but description adds substantial behavioral detail: exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), explicit refusal reasons, and the 'EXTRACTS the answer using ONLY what the tool result contains' constraint. This fully discloses failure modes and result semantics 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 dense but well-organized: purpose, mechanism, output format, use cases, and cost tradeoff in three sentences. Front-loads the key concept ('Hallucination-resistant') and every sentence contributes essential information without redundancy.

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

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

For a complex tool with no output schema, the description thoroughly covers return format, refusal conditions, and usage scenarios. Combined with rich annotations and full schema coverage, the agent has all necessary context to select and invoke the tool correctly.

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

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

Schema description coverage is 100% as all six parameters are documented aliases of 'question' with descriptions. The description only says 'fills arguments' generically and does not add parameter-level meaning beyond the schema. Baseline 3 is warranted since the schema already handles parameter documentation.

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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' specifying the verb ('answer mode') and resource ('Pipeworx'). It clearly distinguishes from sibling ask_pipeworx by emphasizing extraction using 'ONLY what the tool result contains' and returning evidence, which is unique among siblings.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains (financial verdicts, legal claims, medical lookups). Provides direct alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost as a tradeoff.

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

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

The description extensively covers behaviors: low-confidence short-circuit, closed market handling, wide-spread illiquidity, resolution-rule risk, resolver contract, and news fallback. Annotations already declare readOnlyHint, and the description adds significant 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 long and verbose, with multiple sections, but it is well-structured with headers and bullet-like examples. Some detail could be condensed without losing clarity.

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

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

Given the complexity and no output schema, the description covers input formats, classification, fan-out examples, response shapes, resolver behavior, edge cases, and cancellation rules. It is comprehensive.

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

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

Schema coverage is 100%, but the description enriches parameter meanings with examples for 'market', explains 'depth' options, and clarifies 'include_raw' usage. This adds 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 it researches Polymarket bets by pulling data, with examples of inputs. It is specific but does not explicitly distinguish from sibling tools like polymarket_edges or polymarket_edge_tracker.

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

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

Explicit use cases are given (e.g., 'should I bet on X', 'what does the data say about Y'). However, no when-not-to-use or alternative tool suggestions are provided.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds context about ranking by dollar amount by default, max limit 100, and that it covers California state data only, enhancing transparency beyond annotations.

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

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

Description is informative and front-loaded with the main purpose. Each sentence adds value, covering data source, result contents, filters, usage examples, and a disclaimer about scope. Slightly long but no redundancy.

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

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

Given 9 parameters with no output schema, the description explains result fields (department, vendor, amount, etc.), default sorting, and provides filter examples. It covers pagination indirectly via schema and notes max limit. Lacks explicit mention of offset pagination but overall 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 detailed descriptions for each parameter. The description adds some extra context (e.g., case-insensitive substring, default sort), but does not significantly improve upon the schema's existing detail.

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

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

The description clearly states it searches California state government contract awards and purchase orders, specifying the data source (SCPRS on data.ca.gov) and what each result contains (department, vendor, amount, etc.). It differentiates from siblings by focusing on awards, while siblings like ca_procurement_supplier target individual suppliers.

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 example questions for when to use the tool, e.g., 'who won California state contracts'. Does not explicitly state when not to use or suggest alternatives, but the examples imply appropriate contexts.

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. The description adds useful behavioral details: returns total dollars and purchase-order count, sorted largest first, and limited to California state data. This goes beyond the annotations without contradiction.

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

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

The description is concise (two sentences plus example queries) and front-loaded with the core purpose. Every sentence adds essential context; no wasted words.

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

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

Given no output schema, the description adequately explains the return structure (total dollars and purchase-order count) and data source. Annotations cover safety. It lacks mention of pagination, but the limit parameter and default max are in the schema. Overall complete for agent use.

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

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

Schema coverage is 100% with each parameter described. The description adds value by mentioning optional scoping by department/agency or fiscal year, and the example shows default limit and that department is a case-insensitive substring. This provides richer semantics than 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 explicitly states the tool ranks commodity categories by spending, using UNSPSC commodity titles, and gives example queries. It clearly distinguishes from sibling tools like ca_procurement_awards or ca_procurement_top_suppliers by focusing on categories rather than individual awards or suppliers.

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 like 'Answers what does California buy the most of' and gives specific examples, making it easy for agents to decide when to use this tool. It does not explicitly list alternatives or when not to use, but the context is sufficient given the sibling tool names.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, etc., indicating safe read-only behavior. The description adds behavioral details: matches department name as case-insensitive substring, uses SCPRS purchase-order data from data.ca.gov, and clarifies it's state-level data. No contradiction with annotations.

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

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

The description is two sentences plus an example usage, front-loaded with the core purpose. Every sentence adds value: first sentence states functionality, second adds matching method and data scope. 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 tool with 2 parameters and no output schema, the description is fairly complete: it specifies data source, matching method, and output categories. However, it does not mention pagination, limits, or error handling (e.g., department not found). With no output schema, some return format details would improve completeness.

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

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

Schema description coverage is 100%, so the schema already describes both parameters. The description adds the detail that department matching is case-insensitive substring and provides an example fiscal_year format, but these are already in the schema descriptions. Minimal added 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 it profiles a California state department's procurement spend, listing specific outputs like total dollars, PO count, top suppliers, and commodity categories. It also gives example queries, distinguishing it from sibling tools like ca_procurement_top_suppliers or ca_procurement_awards.

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 what the tool does and provides example questions it answers. It clarifies the data scope (California state, not federal), which helps differentiate from federal-level tools. However, it does not explicitly state when to use this tool versus alternatives like ca_procurement_supplier or ca_procurement_commodities.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that matches are case-insensitive and surfaces name variants, and notes the data is California state, not federal. No contradictions. Provides useful context beyond annotations.

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

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

Three concise sentences front-loaded with the main purpose. Second sentence adds behavioral detail, third gives usage guidance. No wasted words. Every sentence earns its place.

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

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

The description explains the return structure (totals, counts, breakdowns) despite no output schema. With only 2 parameters and simple semantics, the description is complete for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces 'case-insensitive substring' for supplier and optional fiscal_year, but does not add new meaning beyond the schema's own property descriptions. Adequate but not exceptional.

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

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

The description specifies the action (aggregate), resource (SCPRS California state contract awards), and outputs (total dollars, purchase orders, breakdown by department and fiscal year). It clearly distinguishes from sibling tools like ca_procurement_department or ca_procurement_top_suppliers by focusing on a single supplier.

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

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

Explicitly states use case: 'size up a single vendor's business with the State of California.' Mentions substring matching for name variants. Does not explicitly list when not to use, but sibling tools provide context for alternatives. Clear enough for an agent to select appropriately.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds valuable context: it returns suppliers with total dollars and order count sorted largest first, and clarifies the data is California state (not federal). 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 two sentences: first sentence states core purpose, second adds optional scoping and output details. Every sentence adds value, no fluff. Front-loaded with the primary action.

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

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

Despite no output schema, the description explains the output (supplier, total dollars, PO count, sorted). It also specifies the data source (SCPRS, data.ca.gov). The tool is simple and the description covers all necessary context for an agent to use it effectively.

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, so baseline is 3. The description adds meaning by explaining parameters in context (e.g., 'case-insensitive substring' for department, default limit 20, max 100). This enhances understanding 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 ranks the biggest suppliers to California by total contract dollars, using SCPRS data. It answers the specific question 'who are California's largest state contractors / award winners' and distinguishes itself from sibling tools like ca_procurement_supplier by indicating it returns a ranked list.

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 optional filters (department, fiscal year, acquisition type, keyword) and provides examples, indicating when to use them. However, it does not mention alternative tools or explicitly state when not to use this tool, which slightly reduces clarity.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, and 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 informative but slightly verbose, especially the opening list of synonyms. However, each sentence adds value, and the structure is logical: purpose, usage preference, type-specific details, output format.

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 (paired data + citation URIs). It covers both entity types comprehensively, including edge cases like off-calendar fiscal years. The tool's complexity (2-5 entities, multiple data sources) is well addressed.

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

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

Schema description coverage is 100%, and the description enriches parameter meaning. For 'type', it explains the different data sources and metrics. For 'values', it specifies tickers/CIKs for companies and drug names, with explicit min/max count guidance.

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

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

The description clearly states the tool provides side-by-side comparison of 2-5 companies or drugs, with specific verb phrases like 'compare', 'rank', 'head-to-head'. It distinguishes itself from sequential single-pack lookups, highlighting its unique value.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It also explains when to use type='company' vs. type='drug', but could better exclude cases where this tool is not 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?

Discloses extensive behavioral traits beyond annotations: returns gaps[] for unanswered facets, 'never invented' evidence, contradictions[] for standard/thorough, stable pipeworx:// citations that are always fetchable when present, semantic excerpting, latency expectations (15-60s, thorough up to 90s), and plan-based depth limits. No contradiction with readOnlyHint/openWorldHint annotations.

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

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

The description is long but densely packed with essential information, front-loaded with the account requirement and alternative. Every sentence contributes new detail (latency, citation semantics, gaps). However, it is a single unbroken paragraph that could benefit from bullet points or bolding for scannability, though the content justifies 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 no output schema, the description fully explains the return format ('findings packet: verbatim evidence + confidence + source + fetched_at + pipeworx:// citation'), gaps[], contradictions[], and hop field. It covers account prerequisites, alternatives, use cases, performance, and limitations, making it complete for a complex research 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 covers both parameters with 100% description coverage, including enum meanings. The description adds valuable context: depth behavior (hop counts, gap recovery, contradiction scan) and the nature of the 'question' (broad/multi-part is fine). This enriches the schema without redundancy.

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

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

The description states a specific verb+resource: "Grounded multi-source research across Pipeworx's 1453 STRUCTURED data sources ... in ONE call" and explicitly contrasts with open-web search. It clearly distinguishes from sibling ask_pipeworx by scope ('broad/multi-part questions' vs 'single lookup') and names the alternative, making the tool's unique 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?

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and if not signed in use ask_pipeworx. It also specifies account/plan requirements for depth levels, which is critical operational guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: returns 'top-N most relevant tools' with 'full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This exceeds what annotations convey.

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

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

The description is well-structured, starting with a clear verb-resource statement, then listing use cases, returning format, and invocation guidance. It is slightly long but every sentence adds meaningful information without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return value (top-N tools with names, descriptions, schemas, examples, ready to call). It also addresses when to use the tool. No gaps remain given the tool's complexity and sibling context.

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

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

Schema coverage is 100% with all 6 parameters described. The description does not add specifics about parameters beyond stating that 'query' accepts natural language. Since schema already handles parameter semantics, a score of 3 is appropriate (minimal added value).

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA, etc.) and explains it returns top-N relevant tools with schemas, ready to call. This distinguishes it from sibling tools like 'ask_pipeworx' or 'deep_research' which are for direct queries or research, not tool discovery.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also describes when to use: 'when you need to browse, search, look up, or discover what tools exist for...' While it doesn't explicitly state when not to use, the 'FIRST' implies using before other tools for exploration.

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?

Details multi-source fan-out, notes USPTO soft-fail due to API sunset, and lists return fields. Adds significant behavioral context beyond annotations without contradiction.

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

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

Front-loaded with examples and structured logically, but somewhat lengthy. All sentences add value, but 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 thoroughly covers return fields, edge cases (soft-fail), and constraints. 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?

Explains type enum constraint (only company), value formats (ticker or CIK), and names not supported. Adds meaning over schema descriptions.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with examples of queries and a list of return components. It distinguishes from chaining individual lookups, though not explicitly from all sibling tools.

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

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

Explicitly states when to use (holistic view) and when not to (names not supported, directing to resolve_entity). Also advises preference over chaining single-pack lookups.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. Description adds minimal context beyond 'delete'; does not explain error on missing key or other side effects. With annotations covering safety profile, score 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?

Two sentences: first for purpose, second for usage. No fluff, front-loaded with main action. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description adequately covers purpose and usage. Minor omission: missing behavior if key does not exist, but not critical.

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

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

Input schema covers 100% of parameters with description for 'key' as 'Memory key to delete'. Description adds no extra meaning beyond schema, so 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?

Explicitly states verb (Delete), resource (memory), and method (by key). Distinguishes from siblings 'remember' and 'recall' by being the delete counterpart.

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 clear when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with siblings. Lacks explicit when-not-to-use instructions, but sufficient for a simple tool.

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

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

Description adds value beyond annotations by detailing the process: fetches page, extracts title/description/key links, emits markdown. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness, and the description is consistent with these. 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?

Two sentences: first states core function clearly, second lists use cases. Every sentence is essential, no filler, and the key action is front-loaded.

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

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

Despite no output schema, the description explains the output is 'standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'. It also covers process and use cases, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no new semantic meaning beyond what the schema provides. Baseline for high coverage is 3, and the description does not exceed that.

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 generates a 'production-ready llms.txt file' for any URL, specifies the verb 'generate', the resource 'llms.txt', and the actions (fetch, extract, emit). It is distinct from sibling tools like 'scan_competitor_ai_presence' which has a different purpose.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, or auditing competitor. It does not mention when not to use or alternative tools, but given no sibling tool performs the same function, the guidance 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 indicate readOnly and idempotent, but the description adds value by listing return fields and mentioning the optional include_inactive parameter, clarifying behavior beyond annotations.

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

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

Two concise sentences, front-loaded with purpose, zero waste.

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

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

Given the simple tool (1 optional boolean, no output schema), the description fully covers functionality, return data, and use cases.

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 description for the boolean parameter. The tool description does not add further meaning, meeting the baseline.

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

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

The description clearly states the action ('List the caller's active subscriptions') and specifies the return fields, distinguishing 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use and implies 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 are all false, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim-token workflow ('Filing without an account returns a `claim_token`...'), and that it is free ('doesn't count against your tool-call quota'). It also explains the async feedback process and that the team reads digests daily.

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

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

The description is longer than average but every sentence adds critical information: use cases, scoping, claim-token mechanics, rate limits, and quota. It is front-loaded with the primary purpose and follows a logical structure, so there is no wasted prose.

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

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

For a tool with no output schema and all-false annotations, the description covers all essential context: what it does, when to use it, when not to, how the claim-token lookup works, rate limits, and feedback impact. It even instructs on how to phrase feedback ('describe the issue in terms of Pipeworx tools/packs'). This is a thorough, self-contained specification.

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

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

The input schema already covers all parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds meaningful semantics for `claim_token` by explaining how to use it to later read status, and for `message` by advising specificity ('1-2 sentences typical, 2000 chars max'). This elevates the parameter guidance.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource that clearly defines the action. It further enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly scopes it to tools served by this Pipeworx connection, distinguishing it from sibling research tools.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug)...' and a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also offers a decision rule for identifying Pipeworx tools ('Not sure? Pipeworx tool names are the ones this connection lists'), making usage unambiguous.

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

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

Description adds valuable traits beyond annotations: caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). Annotations already declare readOnly, openWorld, idempotent, non-destructive; description enhances with operational details. 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?

Three sentences: purpose, use cases, technical details. Front-loaded with the core function. No filler. Every sentence adds value.

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

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

Given one optional parameter, no output schema, and no nested objects, description fully covers what the tool does, returns, and when to use. Also explains caching and data source. 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 parameter 'window' with enum and description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides strategic guidance beyond schema's literal description. With 100% schema coverage, baseline is 3; extra semantic value justifies 4.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. The verb 'Returns' and resource 'top tools, top packs, total call volume' are specific. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on trending analytics rather than direct answers or tool discovery.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choices, aligning use case with agent needs). Does not explicitly state when to avoid or mention alternatives, but the use cases provide clear context for when this 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?

Annotations already declare the tool as read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: fill checks, similarity thresholds (≥0.30 Jaccard), partition filter (>20% placeholder fraction returns null), and details about the response structure including trade recommendations.

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 slightly verbose with multiple technical terms. However, it is well-structured: purpose first, then mode details, then edge cases, then response format. It front-loads the most important information.

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

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

Given the complexity of the tool (multiple modes, fill checks, similarity filters, partition checks), the description is remarkably complete. It covers all inputs, behaviors, edge cases, and output fields. No output schema is provided, but the description enumerates response fields sufficiently.

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

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

Schema description coverage is 100%, and the description adds substantial meaning beyond the schema. It explains the purpose of each parameter (event for single-event mode, topic for cross-event mode), provides example values, and describes what happens when no parameters are passed.

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

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

The description clearly states what the tool does: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) with specific verbs and resources.

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', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains why cross-event mode is beneficial: 'catches ...by May 31 vs ...by Jun 30 patterns that single-event misses.'

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

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

Annotations already flag readOnlyHint, openWorldHint, and idempotentHint. The description adds immense behavioral context: internal modeling details (five model families, three segments), caching policy (1h at KV level), diagnostics for empty segments, and tradeable-edge knobs. 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 each sentence serves a purpose, detailing complex model families and filtering logic. It is front-loaded with the core purpose and segments. While thorough, it could be slightly more concise for quick reading, but the density is justified for the tool's complexity.

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

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

With 9 parameters, no output schema, and intricate behavior, the description fully explains each segment, edge metrics, tradeable-edge knobs, and output structure (by_segment, fed_candidates, _diagnostics). The caching detail and guidance on why segments might be empty make it 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%, baseline 3. The description adds value by explaining why each parameter matters (e.g., min_kelly skips small opportunities, max_spread_pp is a tradeable-edge filter, slippage_pp provides market context about Polymarket fees). This elevates it above 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 uses specific verb+resource ('Scan top Polymarket markets') and clearly distinguishes from siblings like polymarket_arbitrage, polymarket_edge_tracker, and polymarket_kalshi_spread. The phrase 'Built for what should I bet on today' further clarifies the tool's unique purpose.

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

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

The description explicitly states when to use: 'agents discover opportunities without paging hundreds of markets'. It provides context for the 'what should I bet on today' scenario. However, it lacks explicit instructions on when NOT to use or alternatives beyond sibling names, so not a 5.

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

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

The description provides extensive behavioral details: data source (daily closes, not intraday), snapshot creation triggers (cache-miss), response structure (tracked, expired, snapshot_dates), and limits (60-day TTL, start date). 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 efficient and front-loaded with the core purpose. Despite length, every sentence adds value—e.g., response structure and limitations. No wasted words.

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

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

Given no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their meanings. It covers data freshness, limitations, and edge cases, making it complete for this tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about defaults and the meaning of 'window' as snapshot family, but much of this is already in the schema. Extra nuance (e.g., 'snapshot family') justifies a 4.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily snapshots, and answers specific questions about edge duration and decay. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage.

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 the tool's purpose ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges. However, it does not explicitly state when not to use it or list alternative 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?

Adds substantial behavioral detail beyond annotations: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict. For basket mode, includes theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional, forced_directional_risk. 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 comprehensive and well-structured with bold headings for modes. While lengthy, every sentence adds necessary value. Minor redundancy could be trimmed but overall earns its length.

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

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

For a complex tool with two modes, no output schema, and four parameters, the description fully explains all return fields, edge cases (partial fills, thin legs), and usage warnings. It is complete enough for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions. The description adds extra context: default values (size_usd=1000, side default auto for basket), range clamp (10–1,000,000), and interpretation of size_usd in each mode. This 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 clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific outputs. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by naming them explicitly in usage guidance.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why theoretical overround is not capturable on thin books and warns that partial basket fills convert an arb into directional risk.

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

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

The description fully discloses behavioral traits beyond annotations: it explains compatibility warnings, temporal alignment checks, and skipped cross-type/subtype counters. It clearly states that real spreads are rare and that most pre-mapped topics return warnings. This adds significant context beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is somewhat long but every sentence adds value. Minor redundancy (e.g., repeating pre-mapped mentions) could be tightened, but overall it is organized and front-loaded.

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

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

Despite no output schema, the description explains the response format (leg-by-leg prices, spread, safety fields) and covers edge cases like compatibility warnings, temporal alignment, and skipped comparators. Given the tool's complexity, the description is remarkably complete and 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%, so all parameters are documented in the schema. The description adds meaning by explaining the purpose of the topic parameter (10 macro shortcuts) and how explicit tickers override topic mapping. It provides functional context beyond the schema's data types.

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 cross-venue spread calculator between Kalshi and Polymarket, specifies two distinct modes (topic shortcuts and explicit tickers), and distinguishes it from sibling tools like polymarket_arbitrage. The verb+resource is specific and unambiguous.

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

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

The description provides explicit guidance on when to use topic mode versus explicit tickers, explains the response format, and warns that pre-mapped topics often yield compatibility warnings, indicating non-tradeable conditions. It also details when spreads are meaningful and when they are not (via safety fields).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds scope (anonymous IP, hash, account ID) and behavior when no key is provided, going 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, no fluff. First sentence gives core function, second provides usage context, third adds scope and pairing. Efficiently front-loaded.

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

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

Simple tool with 1 optional param and no output schema. Description explains purpose, usage, and scope sufficiently. Return format is implied but not detailed, acceptable for this tool.

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

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

Schema coverage is 100% for the single parameter. Description adds clarity that omitting the key lists all saved keys, which is not in the schema description.

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

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

Description clearly states the tool retrieves a value saved via 'remember' or lists all keys if omitted. Specific verb+resource and distinguishes from sibling tools (remember, forget).

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 clear context: use to look up previously stored data without re-deriving. Mentions pairing with remember and forget, but does not explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint=true, so description adds value by explaining the mark_read side effect ('flag returned events read') and noting the idempotent nature. No contradiction. Adds behavioral context beyond structured fields.

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?

Approximately 100 words, efficiently structured: purpose first, return payload, filtering, mark_read effect, polling info. No wasted sentences; every part earns its place.

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

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

Despite no output schema, description compensates by listing return fields (source, citation_uri, payload). Covers parameter behaviors and polling suitability. Lacks full return structure but adequate 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 has 100% coverage, but description enriches semantics: explains return types, gives example for 'type' filter ('sec_8k'), clarifies 'since' is ISO timestamp, and describes mark_read behavior. Adds value beyond schema descriptions.

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

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

Description clearly states the verb ('Pull') and resource ('fired events from your subscription feed'). It specifies the returned contents (source, citation_uri, raw event payload) and distinguishes itself from siblings like 'list_subscriptions' by focusing on alert events.

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

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

Provides explicit usage context: 'Filter by type... and/or since (ISO timestamp). Polls work fine.' Also mentions an alternative endpoint for scripts/dashboards. Lacks explicit when-not-to-use guidance, but overall 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 declare readOnly/ idempotent/ non-destructive. Description adds rich behavioral details: data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback logic, PatentsView API sunset, return format with citation URIs.

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

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

The description is well-structured with examples, fallback details, and sibling comparison. It is somewhat long but every sentence adds value. Could be slightly trimmed but overall effective.

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

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

Without an output schema, the description still explains the return structure (changes[] grouped by source, total_changes, citation URIs). For a multi-source tool with fallbacks, this is very complete.

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

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

Schema coverage is 100% with descriptions. Description additionally explains that type is only 'company', gives ISO and relative date examples for since, and clarifies value can be ticker or CIK. Also suggests '30d' or '1m' for typical use.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, fanning out to multiple sources. It distinguishes itself from sibling tool entity_profile by describing when to use the static profile instead.

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

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

Explicit usage examples like 'What's new with X' and 'latest on Y' are given, as well as an alternative when to use entity_profile. This helps the AI select the correct 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds storage scoping (scoped by identifier) and persistence details (24 hours for anonymous, persistent for authenticated). 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?

Two clear, front-loaded sentences. Every sentence adds essential info: purpose, when to use, storage details, and pairing with siblings. No fluff.

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

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

For a simple tool with 2 params and no output schema, the description fully covers purpose, usage, behavior, and integration with siblings. 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 for both parameters. Description adds value with key examples (subject_property, target_ticker) and states value is any text, reinforcing 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 states 'Save data the agent will need to reuse later' which is a specific verb+resource. It distinguishes from sibling tools like recall and forget by mentioning pairing with them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with examples of what to store. Pairs with recall and forget, providing clear context. Lacks explicit when-not-to-use but adequate.

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 valuable context beyond annotations, including specific return fields (ticker, CIK, RxCUI, ingredient, brand), citation URIs, auto-disambiguation, and internal cascading behavior. No contradiction with annotations.

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

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

The description is well-structured, starting with relatable user queries, then a clear purpose statement, and then detailed supported types. Every sentence adds functional value—no fluff. The use of quotes and separated sections aids readability and scanning.

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

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

Despite no output schema, the description fully explains return values and citation URIs for both entity types. It covers two distinct workflows (company and drug) with enough detail for an agent to invoke correctly and understand the result format. Comprehensive for a 2-parameter tool.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with examples and per-type semantics. For 'type' it enumerates supported values; for 'value' it provides concrete formats (AAPL, 0000320193, ozempic) and clarifies accepted input variations (ticker, CIK, name). This goes well 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: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific verbs ('resolve', 'look up') and resource examples, and distinguishes itself from siblings by emphasizing it's the first step when you have a name but need an ID.

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 usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use it (when you already have an ID) and mentions that it replaces 2-3 manual lookups, providing clear context for tool 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns ranked list with score/confidence/signal density. This goes beyond annotations.

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

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

Two sentences: first states purpose, second explains usage and output. Front-loaded, every sentence earns its place. No redundant information.

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

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

Given the tool's complexity (4 params, no output schema), the description adequately explains what the tool does, how it works (probes with ai_visibility_check), and what it returns (ranked list). An agent has sufficient information to decide when to use this tool.

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

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

Schema coverage is 100%, but description adds meaning: 'First entry treated as the subject for narrative; rest are competitors' for the entities array, and 'Omit for just workers-ai' for models. This provides additional guidance 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 'Compare' with a clear resource 'AI visibility across multiple entities'. It distinguishes from the sibling tool 'ai_visibility_check' (single entity) by explicitly stating 'side-by-side' and 'multiple entities', and mentions ranking and output format.

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: 'useful for competitive AI-marketing audits' with an example. It implies use for multi-entity comparison versus single-entity check (ai_visibility_check), but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable behavioral context beyond annotations: 'Partial failures degrade gracefully... bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out.' 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 relatively long but every sentence adds value. It is front-loaded with purpose, then usage, then return values, then scope and failure modes. Minor redundancy could be trimmed, but it remains effective.

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

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

Given no output schema, the description thoroughly explains the return structure: 'summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions.' It also covers ecosystem limitations and graceful degradation, making it fully informative.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context beyond the schema: 'version defaults to latest' and 'scoped packages (e.g. "@types/node") are accepted,' which improves parameter understanding.

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

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

The description clearly states the tool's purpose: a composite check for npm packages across deps.dev and bundlephobia. It specifies the verb (check), resource (npm package), and scope (license, advisories, bundle size), effectively distinguishing it from sibling tools which are focused on other domains.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' guiding agents away from incorrect usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds useful behavioral details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and character offsets for verification. 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?

Three sentences, front-loaded with core purpose, followed by usage guidance and technical details in logical order. No unnecessary words. 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 explains return values (top-N passages with offsets and similarity scores), embedding/chunking details, input cap with flagging, and pairing with a sibling tool. All relevant context for an agent to use correctly is provided.

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

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

Schema coverage is 100% (all 3 parameters described in schema). Description adds extra meaning: clarifies max length for text and truncation flagging, gives example queries for query, specifies range for limit. Enhances understanding beyond 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 'Semantic search INSIDE a fetched record,' specifying the verb (search) and resource (text within a record). It distinguishes this tool from siblings like ask_pipeworx_grounded and general search tools by emphasizing 'inside a fetched record' and comparing with ask_pipeworx_grounded.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt — search_within saves context...' and mentions pairing with ask_pipeworx_grounded, giving clear when-to-use context. It does not explicitly state when not to use, but the positive guidance is strong.

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

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

Discloses delivery limitations (10/day SMS cap), phone verification requirement, webhook signing and auto-disable, and feed always-on behavior. Annotations indicate idempotent, but description doesn't explicitly mention idempotency behavior for duplicate subscriptions.

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?

Front-loaded with purpose and returns a subscription id. Efficiently packs examples and constraints into one paragraph, but could be slightly restructured with bullet points for 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?

Covers account requirements, all subscription types with examples, delivery channels with limitations, and returns value. Adequately complete for agent to use correctly despite no 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?

Adds substantial meaning beyond schema by providing concrete examples for each subscription type's params and detailed delivery channel options with error handling notes (webhook signing, auto-disable). Schema coverage is 100%, and description enriches every parameter.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and providing specific event types.

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

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

Explicitly says when to use (create subscription) and includes a prerequisite: requires a Pipeworx OAuth account (anonymous/BYO cannot persist). Does not explicitly compare to alternatives but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context on return format (category-bucketed examples with tool shapes) and parameter behavior (full spread vs focused). No contradictions. Lacks details like rate limits or performance, but still 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?

The description is a single paragraph but front-loaded with key question types. It efficiently packs information without fluff, though slightly longer than necessary. Still well-structured 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 tool with one optional parameter and no output schema, the description covers purpose, usage scenarios, parameter details, and return format comprehensively. No missing critical information given the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter 'topic'. The description adds practical guidance: lists example values ('finance', 'pharma', etc.) and explains that omitting the parameter gives a cross-category spread, which is not explicit 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 is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verb 'suggest' and resource 'questions', and distinguishes from sibling tools by indicating it should be used first when the agent does not know Pipeworx capabilities.

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 ('first when you do not yet know what Pipeworx can do') and provides examples of queries that trigger it. It also mentions the optional topic parameter to focus the results and implies alternatives (meta-tools like ask_pipeworx, entity_profile).

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds critical context: ownership enforcement (auth requirement) and that the row is deactivated, not deleted. This explains the behavioral implications of the 'cancel' action, which is not evident from annotations alone.

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

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

The description is two sentences, direct and front-loaded with the primary action. Every sentence adds essential information without redundancy. Ideal length for the tool's complexity.

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

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

For a single-input, no-output-schema tool, the description covers all necessary aspects: what it does, who can use it, what happens to data (deactivation), and where historical data remains accessible ('recent_alerts'). Complements annotations well.

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 fully describes the single parameter 'id' with a clear description. The description doesn't add new parameter-specific meaning beyond 'by id', but it does provide contextual value by mentioning the source of the id ('returned by subscribe'). With 100% schema coverage, baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id', specifying the verb and resource. The title 'Unsubscribe from Alerts' reinforces the purpose. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. It also explains the deactivation behavior, implying that it's safe to use when you want to preserve history. However, it does not explicitly state when not to use or mention alternatives for other operations.

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 the tool is read-only, idempotent, and open-world. The description adds significant context: it reveals the two-path logic, the use of verbatim evidence, the verdict taxonomy (confirmed, refuted, etc.), and the inclusion of pipeworx:// citations. 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 moderately long but each sentence contributes meaningful detail (triggers, paths, output, efficiency). It front-loads with user-facing examples. Minor redundancy could be trimmed, but overall it is efficient for the complexity covered.

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

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

Given the tool's complexity (two processing paths, no output schema) the description thoroughly explains the output structure (verdict, value, citation, reasoning) and the fallback behavior. An agent can fully understand what to expect without additional documentation.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing concrete examples for the 'claim' parameter and explaining how 'tolerance_pct' overrides implied tolerances, including a use case for hallucination detection. This goes beyond the schema's minimal descriptions.

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

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

The description uses clear natural-language triggers ('Is it true that…', 'fact check') and specifies two distinct processing paths (SEC EDGAR+XBRL for financial claims, grounded pipeline for others), making the tool's verb and resource unmistakable. It distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on claim verification with a structured verdict output.

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 whenever the agent needs to check whether something a user said is factually correct' and explains when to use the fast path versus the grounded pipeline. While it doesn't list alternatives or exclusions, the context is sufficiently clear for most scenarios.

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