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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses that this tool acts as a router, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure cases or latency, but the annotations already cover the safety profile and the description adds meaningful behavioral context.

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

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

The description is longer than average but front-loaded with the key instruction to prefer this over web search. The domain list, examples, and sibling comparisons all earn their place, though a few phrases are redundant with earlier statements and the text becomes somewhat sprawling.

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 this is a single-question-parameter tool with no output schema, the description covers what is needed: when to use it, what it does internally, what it returns, and which siblings to choose instead. The examples further disambiguate the accepted input. No critical calling context is missing.

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

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

The schema already provides 100% coverage for all six parameters, all aliases of 'question'. The description adds value by giving concrete example queries and clarifying that natural-language factual questions are accepted, which helps an agent formulate the parameter correctly. This goes slightly beyond the schema 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 states a specific action: routes a natural-language question to one of 5,798 tools across verified sources, fills arguments, and returns a structured answer with citation URIs. It clearly distinguishes this from web search and from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Gives explicit when-to-use guidance: prefer over web search for factual data about SEC filings, FDA data, economic stats, weather, news, stocks, etc., and for queries starting with 'what is', 'look up', 'find', 'get the latest'. It also names alternatives and their conditions, such as ask_pipeworx_beta for fast one-shot answers, ask_pipeworx_grounded for fully grounded answers, and deep_research for broad multi-part questions.

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 cover read-only and non-destructive behavior. The description adds valuable context beyond annotations: candidate routing improvements can be live intermittently, the last candidate was retired, and the tool currently matches ask_pipeworx exactly. It also confirms this is a full working router with no fallback.

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

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

The description is front-loaded with the core beta distinction and provides useful detail about current candidate state and usage. It is somewhat repetitive around the 'matches ask_pipeworx exactly' and 'full working router' points, but every sentence serves the agent's decision-making.

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 universal router with no output schema, the description gives enough context to invoke it correctly: same tools, same arguments, same response shape as ask_pipeworx. It also clarifies current runtime state and the comparison purpose. The response shape is not described directly, but referencing the stable sibling's shape is reasonable given the extensive 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 description coverage is 100%, so the schema already fully documents the six aliases for the single required question parameter. The description only repeats that it uses the same arguments as ask_pipeworx, adding no additional parameter-level meaning beyond what the schema already provides.

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

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

The description states a clear purpose: a beta version of ask_pipeworx that routes to the same 5,798 tools with identical arguments and response shape. It explicitly differentiates from the stable ask_pipeworx and the grounded sibling by positioning this as the experimental edge with candidate routing improvements.

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

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

The description gives explicit when-to-use guidance: use it exactly like ask_pipeworx when you want the newest routing, since results are compared against the stable router. It also clarifies that no candidate is currently active, so behavior matches ask_pipeworx exactly. However, it does not explicitly state when not to use it or name the stable alternative as the production-safe choice.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral context beyond those: it returns evidence as a verbatim quote, includes confidence and source, and explicitly refuses with a refusal_reason enum when the data does not directly answer. This makes the tool's hallucination-resistant behavior and failure modes transparent.

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

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

The description is three sentences with high signal density and zero filler. It front-loads the core purpose and usage guidance, then packs the output shape, refusal reasons, cost tradeoff, and sibling preference into the remaining sentences.

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

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

Although there is no output schema, the description fully documents the success return shape and the explicit refusal object with its possible refusal_reason values. It also names the closest sibling and the condition for preferring it, making the tool effectively self-contained for an agent deciding whether and how to call it.

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

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

Schema description coverage is 100%, and the schema already defines the question parameter plus all aliases in natural language. The tool description adds no parameter-level meaning beyond the general statement that it fills arguments internally, so it correctly relies on the schema rather than duplicating parameter docs.

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 a specific mode—'hallucination-resistant answer mode for high-stakes reads'—and clearly states the action: route to the right source tool, fetch data, and extract an answer using only the tool result. It explicitly distinguishes itself from ask_pipeworx via the grounded, evidence-backed extraction behavior and refusal semantics.

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 gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, especially for financial verdicts, legal claims, medical lookups, and public statements. It also gives the when-not-to-use case by saying to prefer ask_pipeworx for casual lookups, and it names the cost tradeoff of one extra LLM call.

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?

Annotations already signal readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond annotations by disclosing the multi-hop behavior, gap-recovery semantics, contradictions[] scan, evidence packet structure (verbatim evidence + confidence + source + fetched_at + citation_uri), stable pipeworx:// citations, explicit gaps[] that are never invented, citation_uri only present when fetchable, semantic excerpting rather than head-truncation, and expected latency (15-60s, up to ~90s for thorough). No contradiction with annotations; the description meaningfully enriches the safety and behavior profile.

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

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

The description is long but densely packed with high-value information: every sentence adds behavioral or usage detail. It front-loads the critical account requirement, then the core value proposition, then depth-tier mechanics, then response details, then latency. The only slight deduction is for density and length — an agent must parse a long paragraph — but there is no filler or repetition.

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

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

Given the tool's complexity (two params, three depth tiers, parallel routing, multi-hop behavior, citations, gaps, contradictions), the description covers everything an agent needs: prerequisites (sign-in), when to use the tool, depth semantics, output structure, caveats (citation availability), expected latency, and alternatives. No output schema exists, so the description carries the full burden of explaining return values — and it does so with specific field names (gaps[], contradictions[], hop, citation_uri, fetched_at, confidence, source).

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. But the description adds substantial meaning beyond the schema: it explains that depth:'quick' = single hop, depth:'standard' = default with gap-recovery + contradictions scan, and depth:'thorough' = paid with full iterative hop. It also clarifies that the 'question' parameter is best used for broad/multi-part questions and gives concrete examples ('compare X and Y's regulatory + financial exposure'), which maps directly to the schema's statement that decomposition is the point. This goes well beyond the schema's short enum 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 a specific verb ('research'), names the resource ('Pipeworx's 1517 STRUCTURED data sources'), and clearly differentiates from alternatives: it explicitly states 'this is NOT open-web search' and positions itself against 'ask_pipeworx instead' for single lookups. It clearly states the tool decomposes questions into facets and routes them in parallel to 5,798 tools, making it distinguishable from siblings like bet_research, compare_entities, and ask_pipeworx.

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

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

The description explicitly states when to use this tool ('Best for broad/multi-part questions over structured data' with concrete examples) and when not to ('For a single lookup use ask_pipeworx instead'). It also provides an explicit exclusion for unsigned users ('If you are not signed in, use ask_pipeworx instead'), and explains the depth tiers and their tradeoffs. This is model guidance that routes the agent to 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 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description goes far beyond them: it discloses the parallel fan-out across sources, return structure, sources_used/sources_failed semantics, soft-fail behavior for patents, expected empty sections for FDA products, and the private-company resolved:false behavior. No contradictions with annotations.

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

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

The description is long, but the tool is genuinely complex and the length is mostly high-density, non-redundant detail. It is front-loaded with user intents and the key 'ALWAYS PREFER' guidance before moving into source lists and return semantics. Could be slightly better structured, but 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 tool with no output schema, the description is remarkably complete: it covers all accepted input forms, the full list of data sources, the returned fields, failure modes, edge cases like private companies, and the meaning of empty sections. An agent has everything needed to select and invoke it correctly.

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

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

The schema already covers both parameters with 100% description coverage, but the description adds value by clarifying that type accepts company or ticker interchangeably and that value can be a ticker, zero-padded CIK, or company name with name resolution details. This complements rather than merely repeats 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 states a specific verb, resource, and scope: it produces a full cross-source profile of a US public company in one parallel call. The example phrasings and the explicit mention of 'holistic view' distinguish it from single-purpose lookups and 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?

It explicitly says when to use the tool — whenever the user asks for a holistic view, company profile, or briefing on a public company — and instructs to ALWAYS PREFER it over chaining single-pack SEC/XBRL/news lookups. This is clear routing guidance against the obvious alternative approach.

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?

Annotations already state readOnlyHint and idempotentHint, but the description goes far beyond that. It discloses that matching uses keyword/word overlap rather than a shared resolution source, warns that compatibility fields can be non-empty even with matched pairs, explains that Kalshi fees are not modeled (spreads are gross), details the meaning of `temporal_alignment` with a NULL caveat, and explains skipped/unclassified leg handling. This is rich behavioral context that fully complements the annotations with 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 extremely long and dense, but it is internally structured with uppercase signposts ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS', 'Codes:'). It front-loads the core purpose in the first sentence, which is good, but the subsequent block of text is overwhelming and could be broken into bullet points for easier consumption. It is informative but not 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 the tool's complexity and the absence of an output schema, the description covers all essential return semantics: leg-by-leg prices, `top_spreads_pp`, safety fields and their codes, `temporal_alignment`, fee disclosure, skipped-leg counters, and explicit warnings about unverified pairs. Nothing an agent needs to call the tool correctly and interpret results seems to be missing.

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

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

The input schema already documents each parameter (100% coverage), so the baseline is 3. The description adds significant value by explaining the interaction between the `topic` shortcut and the explicit override parameters, and by clarifying that both modes run the identical token-overlap matcher. It also enumerates the valid topic values and example tickers/slugs, going beyond the schema's example list.

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 a precise statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the two venues and the concept of spread, and explains two modes (`topic` and explicit ticker/slug). This makes the tool's purpose unambiguous and distinct from sibling tools like `polymarket_arbitrage` or `polymarket_edges`, which focus on different aspects.

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 both usage modes and how to choose between them, and adds a critical caution: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also clarifies when the spread is meaningful ('when the bet shapes are equivalent') versus when the tool flags non-equivalence. However, it never explicitly names an alternative tool to use instead, which would strengthen the guidance to 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?

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?

The description goes far beyond the readOnly/openWorld/idempotent annotations by explaining graceful degradation when GLEIF/OpenFIGI are unavailable, multi-endpoint cascading, ambiguous-name behavior returning figi_candidates without asserting a match, explicit unresolved identifiers, and the ISIN-to-LEI mapping path. This is rich behavioral disclosure that helps an agent anticipate edge cases.

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 densely packed, but front-loads the core purpose and usage directive before diving into per-type details. Nearly every clause adds unique information, though the heavy use of nested parentheticals makes it less scannable than ideal.

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 two-parameter tool with no output schema, the description explains what each type returns, how identifiers are sourced, how failures and ambiguities are represented, and what inputs are accepted. It is sufficiently complete for an agent to invoke it correctly without additional external knowledge.

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

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

The schema already has 100% coverage, so baseline is 3, but the description adds substantial value: it explains that 'value' should be the entity name only, warns against including trailing security-class words for bonds, gives per-type examples, and clarifies how the same parameter behaves differently for company versus drug. This is meaningful semantic 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 states a specific action—resolving a user-spoken name to canonical identifiers—and explicitly names the identifier types (CIK, ticker, LEI, FIGI, RxCUI) and supported entity types (company, drug). It also distinguishes itself from other tools by noting it supplies IDs that 'other tools require as input' and instructs to 'Use FIRST' when a name but not an ID is available.

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

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

The description gives clear context on when to use the tool ('Use FIRST whenever you have a name but need an ID') and describes the scope of supported lookups. It does not name explicit alternative tools or when-not-to-use conditions, but the guidance is concrete enough for an agent to select it 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, 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?

Beyond the read-only/idempotent annotations, the description discloses the full verdict taxonomy, the critical meaning of could_not_verify (check did not happen, must not be used as evidence), and the distinction between unsupported and could_not_verify. It also reveals the internal routing logic and the fact that it replaces multiple sequential calls—transparency that annotations alone do not provide.

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

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

The description is front-loaded with trigger phrases and a one-line purpose, then systematically covers behavior, return values, and an explicit caller warning. Every sentence adds distinct value; no filler. The length is justified by the complexity of the tool.

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

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

With no output schema, the description fully explains return verdicts, citation format, and reasoning. It covers edge cases (could_not_verify, unsupported), gives domain-specific routing details, and even mentions the performance benefit of replacing multiple calls. For a tool of this complexity, this is a complete and self-contained description.

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?

While the schema covers both parameters 100%, the description adds significant context: it explains that tolerance_pct overrides claim-implied tolerance, gives a concrete use case (1-2% for hallucination detection), and clarifies the default cap at 5%. The claim parameter is also enriched with examples from the description's opening. 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 opens with explicit trigger phrases ('fact check', 'verify the claim that…') and defines the tool as natural-language claim verification. It clearly distinguishes from siblings by focusing on fact-checking against authoritative sources, and even mentions replacing sequential calls, positioning it as a composite verification tool.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates the two processing paths (company-financial vs. any other claim), providing clear context on when each applies and how the tool behaves differently. This gives an agent actionable guidance on invocation.

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