Chaos Index

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds that default model is free, Anthropic requires user-provided key and pays Anthropic directly, and API key is passed through. 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, front-loaded with action and purpose. Every sentence adds distinct information: function, default, optional key, return structure, use cases. No filler.

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 4 parameters, high schema coverage, and no output schema, the description fully explains inputs, default behavior, optional anthropic integration, and return format (per-model fields + combined view). Annotations cover safety. Complete for its 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 has 100% coverage. Description adds value by clarifying default model is free, '_apiKey' is only for Anthropic, and 'context' aids disambiguation. Provides practical usage context beyond schema.

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

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

Clear verb ('probe'), specific resource ('LLMs for business/brand/product/topic'), and metric ('score visibility 0-100'). Distinguishes from siblings like 'ask_pipeworx' by focusing on external LLM knowledge rather than internal Pipeworx queries.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explains when to use optional parameters ('_apiKey' for Anthropic probes). Does not explicitly list exclusions, but context and sibling names imply alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already signal safety, and the description adds meaningful behavioral context: it routes to other tools, fills arguments automatically, and returns stable citation URIs. It does not contradict the annotations and offers extra detail about the tool's aggregation behavior, though it does not discuss rate limits or failure modes.

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 intentionally information-dense: it front-loads the key instruction ('PREFER OVER WEB SEARCH'), provides concrete examples, and structures the escalation paths clearly. Every sentence contributes to decision-making, though it could be trimmed slightly without losing value.

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

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

Given the absence of an output schema, the description compensates by explaining the return format (structured answer with citation URIs), listing supported domains, and giving realistic examples. It also covers fallback tools and limitations, making it comprehensive enough for an agent to decide when to invoke this tool and what to expect.

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, describing 'question' and five aliases with clear descriptions. The description adds minimal new parameter semantics beyond restating that it accepts natural language and internally fills arguments; the aliases are already documented in the schema, so the description does not carry additional weight.

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

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

The description clearly states the tool's function: routing questions to one of 5,529 tools across 1,455 sources and returning structured answers with citations. It uses a specific verb ('routes', 'fills arguments') and explicitly differentiates itself from web search and 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?

The description explicitly says to prefer this tool over web search for factual questions, provides example queries, and tells the agent to 'START HERE for most questions.' It also gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions, making when-to-use vs. alternatives 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context beyond this: the beta/experimental nature, the mechanism of comparing against the stable router, and the fact that it 'Falls back to nothing' yet remains a full working router. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the key identity ('Beta version of ask_pipeworx') and provides essential details without excessive verbosity. The final sentence about falling back to nothing adds clarity, though it could be seen as slightly emphatic.

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 moderate complexity (6 parameters, all aliases) and strong annotations, the description is complete. It explains the tool's current state, relationship to ask_pipeworx, and usage context. No output schema exists, so the mention of 'same response shape' is sufficient.

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

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

Schema description coverage is 100%, with all parameters being aliases for 'question' and fully described. The description adds no additional parameter-level semantics beyond noting 'same arguments' as ask_pipeworx, which is unnecessary given the schema already documents everything. Baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, explaining it is the same universal router with identical tools, arguments, and response shape. It also explicitly notes that it currently matches ask_pipeworx exactly when no candidate is active, distinguishing it from its stable sibling.

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 a clear usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that results are compared to the stable router, implying it is for experimental purposes. However, it stops short of explicitly stating when not to use it or naming an alternative like ask_pipeworx_grounded.

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

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

The description discloses the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal enum values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also mentions the extra LLM call overhead, which goes beyond the annotations that only indicate read-only, idempotent, open-world behavior.

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

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

The description is dense but every clause adds value: mechanics, return format, refusal reasons, use cases, and cost trade-off. It is well-structured with a clear hyphen-delimited outcome/refusal breakdown, and there is no redundant or filler text.

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 complexity and lack of an output schema, the description fully covers purpose, usage context, alternatives, return value structure, and error/refusal behavior. It also contextualizes the tool within the sibling set by referencing ask_pipeworx and providing a cost comparison.

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 100% of parameters, listing all six as aliases for a single natural-language question. The description adds no additional parameter semantics beyond what the schema states, so the baseline of 3 applies.

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

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

The description clearly states the tool is a hallucination-resistant answer mode that routes through the same tool selection as ask_pipeworx, fetches data, and extracts answers using only the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and the extra LLM call cost.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives concrete examples (financial verdicts, legal claims, medical lookups, public statements) and explicitly advises preferring ask_pipeworx for casual lookups due to the 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description goes far beyond by detailing resolver contract, parent event extraction, news fallbacks, safety measures (low-confidence, closed markets, wide spreads), and cancellation rule 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 very long and dense, covering many edge cases and details. While thorough, it lacks a clear structure and contains redundancy (e.g., multiple references to resolution). Could be more concise for an AI agent to parse quickly.

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

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

Given the tool's complexity (3 params, no output schema), the description fully explains the response shape (result.market, analysis, evidence), resolver behavior, parent event extraction, news handling, and safety mechanisms. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description enriches by explaining how the 'market' parameter is resolved, when to use 'depth' (defaults), and use cases for 'include_raw'. Baseline 3 due to high coverage, but adds meaningful context.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug, URL, or question text) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx and polymarket_edges.

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

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

The description provides explicit use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It gives context but does not explicitly state when not to use or name alternative tools, though the sibling set is diverse.

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, openWorldHint, idempotentHint, and not destructive. The description adds valuable behavioral context: real-time computation, listing specific data sources, and returning component contributions, which goes beyond what annotations provide.

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

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

The description is a single sentence that front-loads the purpose and includes all necessary information. It is concise but could be slightly more structured (e.g., splitting into two sentences 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?

Given the tool has no parameters, annotations covering safety, and an output schema (not shown), the description provides sufficient context: what it does, what it returns, and the components involved. It is complete for a simple compute tool.

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

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

The tool has zero parameters, so the input schema fully covers them. The description adds no parameter information, but with no parameters, the baseline of 4 is appropriate as the description does not need to compensate.

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

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

The description clearly states the tool computes a chaos index (0-100) by combining multiple data sources, with a specific verb 'Compute' and resource 'chaos index'. It distinguishes itself from siblings by its unique combination of data inputs.

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

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

The description implies the tool is for computing a chaos index but does not explicitly state when to use it versus alternatives or provide context on prerequisites or when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes beyond by detailing data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years for companies, and that results are sorted by primary metric. It also mentions output includes paired data and citation URIs. 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 detailed but not overly verbose. It starts with example queries, then explains the tool's function, data sources, and output. Every sentence adds value, though it could be slightly more streamlined. It is well-organized and front-loaded with key usage patterns.

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 (multiple entity types, different data sources), the description is thorough. It explains both company and drug data pulls, result sorting, and inclusion of citation URIs. Without an output schema, it adequately describes return format. It also provides efficiency context by stating it replaces many sequential lookups.

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 has 2 parameters with 100% description coverage. The description adds significant meaning: for 'type' it explains what data each enum value pulls; for 'values' it specifies format (tickers/CIKs for companies, drug names for drugs). This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 entities (companies or drugs). It provides specific examples of user queries like 'X vs Y' and 'which is bigger', and distinguishes itself from siblings by noting it replaces 8–15 sequential single-pack lookups, implying tools like entity_profile are for single entities.

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 tells when to use this tool: when comparing entities head-to-head, ranking, or asking which is larger. It says 'ALWAYS PREFER over sequential single-pack lookups', providing clear preference guidelines. It also implies constraints like 2–5 entities and that single-entity requests should go elsewhere.

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 annotations by revealing: output packet shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting of large records, hop field, and timing expectations. All of these are behavioral traits not inferable from readOnlyHint/openWorldHint, and they don't contradict the annotations.

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

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

The description is extremely long and written as a single run-on paragraph. Almost every sentence adds information, but the structure is poor — no bullets, headings, or logical separation between account requirements, usage guidance, and technical behavior. It could be condensed or reformatted without losing content, but it's still far more informative than a minimal description.

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

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

Given the tool's complexity (5,529 tools, parallel routing, multi-depth behavior) and lack of an output schema, the description is remarkably complete. It covers return format (findings packet, gaps[], contradictions[]), citation resolvability, semantic excerpting, timing, account tiers, and edge cases like current-news topics. An agent could confidently invoke this tool and interpret its results based solely on the 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?

Schema coverage is 100%, so baseline is 3; however the description adds genuine extra semantics: it explains the depth paid-plan constraint ('depth:'thorough' needs a paid plan'), clarifies what the gap-recovery and contradictions passes do at each depth, and expands on 'question' as natural-language with broad/multi-part acceptable. This is meaningful 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 the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' and even warns 'this is NOT open-web search.' It explains the internal mechanism (decomposes question into facets, routes to 5,529 tools in parallel, returns a findings packet) and explicitly contrasts with ask_pipeworx, making it distinct among siblings.

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

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

Provides explicit when-to-use and when-not-to-use: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' plus 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also gives a fallback for unsigned users ('If you are not signed in, use ask_pipeworx instead') and depth-based prerequisites.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds behavioral details: returns top-N results with 'full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' This enriches 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?

The single paragraph is dense but well-front-loaded: the first sentence states purpose, followed by usage, domain list, output details, and a call-to-action. Every sentence adds value; no fluff. Could be slightly more structured, but highly 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?

With no output schema, the description compensates by explaining return content: 'names, descriptions, and full input schemas (with curated examples).' It covers all six parameters via schema and examples. The input schema has high coverage, and the description provides enough context for a 6-parameter, single-required 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%, so baseline is 3. The description adds value by listing accepted aliases (q, task, search, description) and providing example queries in the schema examples. This clarifies parameter usage beyond the schema descriptions 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 starts with 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists many domains (SEC filings, financials, etc.) and explains the output includes full schemas, distinguishing it from sibling tools like search_within or suggest_questions.

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 you need to browse, search, look up, or discover what tools exist for...' and directs the agent to 'Call this FIRST when you have many tools and want to see the option set (not just one answer).' This provides clear when-to-use guidance 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about patents soft-failing, the fan-out across multiple sources, and input limitations. No contradictions found.

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 front-loaded with examples and a clear purpose. Every sentence conveys useful information, though some redundancy could be trimmed. Overall effective and well-structured.

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

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

Given the tool's complexity (multiple sources, fallbacks) and absence of an output schema, the description thoroughly explains input limitations, data sources, and specific return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). It also notes potential failures, making it complete.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by specifying that names are not supported, providing examples for ticker and CIK, and clarifying that value can be ticker or zero-padded CIK. This goes beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in a single parallel call. It lists specific examples and distinguishes itself from single-source lookups, demonstrating a specific verb+resource+scope.

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 advises to prefer this tool over chaining single-pack lookups for holistic views and directs users to use resolve_entity if only a company name is available. This provides clear when-to-use and when-not-to-use guidance with an explicit alternative.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds valuable context about why to use it (stale context, sensitive data) beyond what annotations provide, without contradicting them.

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 short sentences that deliver the core message without filler. Every sentence provides actionable 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 simple interface (1 required param, no output schema), the description fully equips an agent to decide when and how to use the tool, including relation to siblings.

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

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

Schema coverage is 100%, and the schema describes the single parameter 'key' as 'Memory key to delete'. Description does not add extra parameter semantics, 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 (delete), the resource (memory by key), and differentiates from siblings like 'remember' and 'recall' by specifying that 'forget' is for deletion.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall', giving clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the fetch-and-extract process and output format, consistent with annotations. No contradictions.

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

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

Two sentences, no fluff. First sentence front-loads core purpose and output, second sentence provides use cases. Every word earns its place.

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

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

For a tool with 2 params (100% schema coverage), no output schema, and rich annotations, the description is complete. It covers what, how, output, 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%, so description doesn't need to re-list params. Adds useful context: default and max for max_links, and clarifies url is for the site to summarize. This aids correct usage.

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

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

The description states a specific verb ('Generate') and resource ('llms.txt file for any URL'), clearly distinguishing it from siblings like 'scan_competitor_ai_presence' or 'discover_tools'. No ambiguity.

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

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

Provides explicit use cases: getting client sites indexed, drafting for own project, auditing competitors. Could be stronger by mentioning when not to use (e.g., if you need a full sitemap), but current guidance is clear.

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

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

Annotations already declare readOnlyHint and non-destructive, so description adds value by specifying return fields and the include_inactive parameter. No contradictions.

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

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

Two sentences, front-loaded with action, no fluff. 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?

With no output schema, description includes all return fields and the optional parameter. Annotations cover safety. Complete for a simple list 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%, and the description does not add extra semantics beyond the schema's parameter description. Baseline score.

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

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

The description clearly states 'List the caller's active subscriptions' with specific return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clear context for usage, though no explicit when-not.

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

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

Despite annotations being minimal (only false hints), the description discloses substantial behavioral context: rate-limiting to 5 per identifier per day, no tool-call quota cost, the claim_token workflow for tracking resolution, and the team's daily digest reading cadence. These details far exceed what the annotations provide and give the agent a realistic model of the tool's side effects.

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

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

The description is long but every sentence earns its place: purpose, use cases, exclusions, account-free workflow, token mechanics, rate limits, and quota impact. It is front-loaded with the core purpose and then logically proceeds to exclusions and operational details. No redundancy or filler.

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 that there is no output schema, the description compensates by explaining the claim_token return value and its later use. It also addresses the main contextual gaps: what to report, what not to report, limitations (rate limit), and cost (free). The presence of nested objects in the schema is handled by the schema itself, and the description adds the missing operational context.

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

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

The schema already describes all four parameters at 100% coverage, so the baseline is 3. The description adds meaningful usage semantics beyond the schema, especially for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and message ('1-2 sentences typical, 2000 chars max'). It doesn't deeply elaborate on type or context, but what it adds is valuable.

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 clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes this feedback tool from sibling tools by scoping it to 'tools served by this Pipeworx connection' and by naming the exact triggers (bug, feature, data_gap, praise).

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

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

The description provides explicit when-to-use guidance for each feedback type and, crucially, when-not-to-use: it tells the agent to file bugs with a different server if the tool is not from Pipeworx. It even includes a fallback ('Not sure? Pipeworx tool names are the ones this connection lists'), making the decision boundary exceptionally clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds source (CF analytics-engine), data content (no PII), and caching behavior (5min-1h). No contradiction with annotations.

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

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

Description is concise, front-loaded with purpose, then use cases, then technical details. Every sentence adds value. No redundancy or verbosity.

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, rich annotations, and no output schema needed for a trend report, the description covers all essential aspects: what, why, when, and how it works.

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 enum and description. Description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond schema.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. Provides three specific use cases. Does not explicitly distinguish from sibling tools, but the function is unique enough among siblings like ask_pipeworx or discover_tools.

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

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

Explicitly lists three scenarios for use: discovering hot data sources, confirming canonical tool, and checking alignment. Does not specify when not to use or alternatives, but the context is clear and actionable.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, non-destructive behavior. The description adds valuable behavioral context: it performs semantic similarity checks (Jaccard threshold), partition filtering, and a fill check against live CLOB depth. 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 lengthy but well-structured: it opens with a concise summary, then details each mode with specific examples, and concludes with response structure and fill check. While every sentence is informative, some redundancy could be trimmed (e.g., 'SEMANTIC ANCHOR' and 'PARTITION FILTER' are detailed but essential). Slightly below perfect conciseness.

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

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

Given the tool's complexity (multiple modes, internal checks, fill risk), the description covers all necessary aspects: parameter usage, output format, edge cases (placeholder slugs, similarity thresholds), and cross-references a sibling tool for custom sizing. No output schema is needed as the description explains the response structure. 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 description coverage is 100%, so the schema already provides basic meaning. The description adds extra semantics: event accepts slugs or full URLs, topic uses seed questions, and it explains the underlying logic (e.g., cross-event mode catches date patterns). This goes beyond the schema.

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

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

The description clearly identifies the tool as 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes three modes (no args, event, topic), each with specific behavior. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also explains the partition filter and fill check, providing guidance on when not to trade. This offers clear decision criteria for the agent.

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

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

Description adds significant behavioral context beyond annotations: caching at KV level with 1h TTL, diagnostic output for empty segments, and detailed edge calculation methods. Annotations already indicate read-only, idempotent, non-destructive behavior, which is consistent.

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

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

The description is long but well-structured with clear sections (model families, segments, knobs, diagnostics). It front-loads the core purpose and uses bullet-like formatting. Some redundancy exists (e.g., repeating segment names), but overall efficient for the 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?

Despite no output schema, the description fully explains the response structure (by_segment, fed candidates, diagnostics) and how to interpret edge metrics. It covers caching, filter behavior, and edge calculation details, making the tool's operation completely transparent for an agent.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds valuable context for tradeable-edge knobs (e.g., min_partition_leg_kelly's role in filtering partition arbs) and how slippage_pp interacts with Kelly sizing. This goes beyond what the schema alone provides.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'Polymarket markets' are specific, and it distinguishes from siblings like polymarket_arbitrage by focusing on model-driven and structural opportunities.

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 frames the tool for 'what should I bet on today' and mentions segments, but does not directly state when not to use it or list alternatives. However, the context of removing the need to page hundreds of markets provides clear use-case guidance.

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

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

Annotations declare readOnly, idempotent, openWorld, non-destructive. Description adds rich behavioral context: data from daily snapshots with 60-day TTL, decay on daily closes (not intraday), response structure details (tracked, expired, snapshot_dates), and limitations. 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?

Though lengthy, every sentence provides value: purpose, use case, response fields, limitations, and computation details. Front-loaded with core question. 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?

No output schema, so description fully explains return values: tracked[], expired[], snapshot_dates[] with field details. Covers data source, TTL, start date, and computation method. Complete for a complex temporal analysis tool.

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

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

Schema coverage is 100% with full descriptions for both parameters. description basically repeats schema info ('days lookback default 14 max 30' vs schema 'default 14 clamp 2-30'; window lists same values). Adds no extra meaning beyond schema, so baseline 3.

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 verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers specific questions about edge duration and decay, distinguishing from sibling tools like polymarket_edges (raw data) and polymarket_arbitrage (different analysis).

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

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

Description gives clear context: 'a fresh wide edge and a 3-week-old wide edge are different trades' – guides when to use for trade decision-making. Lacks explicit alternatives or when-not-to-use, but the sibling list provides contrast implicitly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds rich behavioral context: it 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), explains per-leg fill detail for baskets, identifies thin_legs and forced_directional_risk, and warns about the dominant loss mode. No contradiction with annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, followed by usage guidance. It is somewhat lengthy but every sentence adds value; no redundancy. Could be slightly more terse 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?

Despite no output schema, the description fully documents return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for baskets: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). Also provides edge-case warnings about partial fills and forced directional risk.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: side default and auto behavior in basket mode, size_usd interpreted differently for single-market vs basket (spend vs target proceeds vs settlement notional), and market vs event mode triggering different return structures. This enriches 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 it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific outputs (top_of_book, vwap_fill_price, slippage_pp, etc.). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this risk check before acting on those signals.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns against partial basket fills converting arb into unhedged directional positions, providing clear when-to-use and when-not-to-use context.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details safety fields like compatibility_warning, temporal_alignment, and skipped_cross counters. It explains how the tool handles non-equivalent bets and temporal mismatches, fully transparent on behavior.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose. Slightly dense but 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 no output schema, the description compensates by describing the response structure (raw probabilities, spread, safety fields) and special cases. It covers inputs, behavior, and output interpretation comprehensively.

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

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

Schema coverage is 100% with descriptions, but the tool description adds substantial meaning: it lists all 10 topic shortcuts, explains how explicit tickers override topics, and gives examples. This goes well beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from single-venue siblings like 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 provides explicit guidance on when the spread is meaningful (equivalent bet shapes) and when the tool warns of incompatibility. It also cautions that pre-mapped topics often return warnings, setting realistic expectations.

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

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

Adds scoping details (by identifier) and behavior of omitting key for listing, which annotations (readOnlyHint, idempotentHint) don't cover. No contradiction with annotations.

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

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

Two efficient sentences, no filler. Front-loads the primary action and uses second sentence for context and pairing, maximizing information density.

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-parameter read tool with full annotation coverage, the description adequately covers behavior, scoping, and usage relationship with siblings, leaving no obvious gaps.

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

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

Schema coverage is 100% with parameter description. The description adds the behavior of omitting 'key' to list all saved keys, exceeding the schema's explanation.

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 specifies the verb 'retrieve' and resource 'memory key/value', explicitly distinguishing from siblings 'remember' and 'forget' by explaining recall's role in retrieving saved values or listing keys.

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

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

Provides clear use cases (lookup context, target ticker, address, research notes) and states it avoids re-deriving info. Pairing with remember/forget implies when to use, though no explicit when-not-to-use is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the mark_read behavior (flagging events as read so subsequent calls return only newer ones) and that polls work fine. 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 succinct (3-4 sentences), front-loaded with the core purpose, and every sentence adds value. No redundant or vague statements.

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 5 optional parameters, no output schema, and good annotations, the description covers the return format, filtering, and mark_read feature. It also mentions an alternative endpoint. Could be more explicit about error handling or rate limits, but overall 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 meaning by explaining the mark_read parameter's effect, the filtering by type and since, and the fields returned (source, citation_uri, raw payload), which enriches understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returning the most recent alerts with specific fields. It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on retrieving alert events rather than managing subscriptions.

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

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

The description provides context that polls work fine and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool versus other similar tools or when not to use it.

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

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

Annotations already declare safe flags (readOnly, idempotent, non-destructive). The description adds rich behavioral details: fans out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and structured return format. No contradictions with annotations.

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

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

The description is a single paragraph with front-loaded example queries. It is thorough without redundancy, though slightly dense. Every sentence serves a purpose.

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

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

Given the tool complexity (multi-source, fallback), schema coverage, and annotations, the description is complete: explains sources, fallbacks, return format, and alternative tool. No output schema, but return structure is described.

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

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

All parameters have descriptions in the schema (100% coverage). The description adds context: since accepts ISO or relative, value can be ticker or CIK, type limited to company. It recommends typical values and explains formats beyond bare schema.

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

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

The description clearly states the tool provides a change feed for a company (filings, news, patents) in a time window, with specific example queries. It distinguishes from sibling tool entity_profile for static profiles.

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

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

The description explains when to use this tool vs. entity_profile, and provides guidance on parameter values (e.g., recommended '30d' for since). However, no explicit when-not-to-use conditions are included.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds key-value scoping by identifier, persistence details (authenticated vs anonymous 24hr), and pairing with other tools. 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 with excellent front-loading: first sentence states purpose, second gives usage guidance, third and fourth add behavioral details. 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?

Complete for a write-only tool with 2 parameters and no output schema. Covers purpose, timing, persistence, and relationships to siblings without gaps.

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

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

Schema coverage 100% with descriptions for key and value. Description reinforces key-value pair and adds naming conventions (e.g., 'subject_property'), going 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?

Clear verb 'Save data' with resource scope 'the agent will need to reuse later'. Distinguishes from siblings 'recall' and 'forget' by stating it is for storing, while those are for retrieval and deletion.

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

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

Explicitly states when to use 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Pairs with recall and forget. No explicit when-not-to-use, but context is clear.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already disclosing the safe, non-mutating, idempotent nature, the description adds substantial behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of sources for identifiers, and the 'unresolved' list for failed lookups. This goes beyond the annotations and helps the agent predict behavior accurately.

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

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

The description is long but well-structured: it opens with relatable query examples, then states the core purpose, then uses 'SUPPORTED TYPES' to organize detailed behavior. Every sentence contributes useful information (fallback behavior, source labeling, unresolved handling). It is slightly dense but front-loaded enough for an agent to quickly grasp the purpose. A 4 reflects its efficient organization despite the length.

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

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

With no output schema, the description carries the full burden of explaining return values. It does this thoroughly: identifiers are labeled with their source, unresolved identifiers are explicitly listed, drug lookups include citations, and the tool notes it replaces 2-3 manual lookups. It also covers input types and failure modes, making it complete for a 2-parameter lookup tool.

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

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

The input schema already provides 100% coverage for both parameters (`type` with enum values, `value` with per-type explanations). The description adds examples ('AAPL', '0000320193', 'ozempic') and nuances like 'when a ticker is implied' for FIGI, but these largely reinforce rather than extend the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 specifies a unique purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides specific query examples (ticker, CIK, LEI, RxCUI) and explicitly distinguishes this tool from siblings like entity_profile and compare_entities by focusing on ID resolution. The verb 'resolve' and resource 'entity' are specific and accurate.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists example user queries that trigger this tool. However, it does not explicitly mention alternative tools for other scenarios (e.g., 'if you need a detailed profile, use entity_profile instead'), so it stops short of full 'when-not/alternatives' guidance.

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

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

Annotations indicate read-only, idempotent, open world; description adds specifics: probes each entity, ranks, and returns 'ranked list with score, confidence, signal density', providing full 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?

Four sentences with no redundancy; purpose stated in first sentence, additional details in subsequent sentences; every word earns its place.

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

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

Complete description for a compound tool: explains operation, inputs, and outputs (ranked list with metrics) given no output schema; no missing information.

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

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

Schema covers 100% of parameters; description adds practical usage notes (e.g., 'Omit for just workers-ai', 'First entry treated as the subject') that enhance understanding beyond schema.

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

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

Description uses specific verbs ('compare', 'probe', 'ranks') and resources ('AI visibility across multiple entities'), and clearly separates from sibling tool 'ai_visibility_check' by noting it performs side-by-side comparison.

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

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

Description explicitly states use case ('competitive AI-marketing audits') and provides an example query, but does not mention when not to use or alternatives beyond implicit differentiation.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds important behavioral details: graceful degradation, bundlephobia timeout (5-30s), and partial failure handling. This enriches the agent's understanding of tool behavior.

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

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

The description is information-dense and front-loaded with the core purpose, but slightly long. Every sentence adds value without fluff. Good structure, but could be slightly more concise.

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

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

Given no output schema, the description thoroughly details return fields (summary block, per-advisory detail, links, alternative versions) and error handling. It covers all necessary context for an agent to understand what the tool returns and how it behaves.

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

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

Schema covers 100% of parameters with clear descriptions. The description reinforces scoped package acceptance and default version behavior, but does not add significant new semantics beyond what the schema provides. Baseline score for high schema coverage.

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

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

The description clearly states it performs a composite check for npm packages, specifies the verb 'scan dependency', and defines the resource as an npm package. It explicitly distinguishes scope (NPM ecosystem only) and mentions fallback for other ecosystems, helping differentiate from potential alternatives.

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 use cases: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also mentions limitations (NPM only in v1) and suggests alternatives for other ecosystems. Lacks explicit 'when not to use' but the context is clear.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: embedding model (BGE-base-en), scoring (cosine similarity), chunking (500-char overlapping windows), size cap (200K chars with truncation flag), and output structure (character offsets). This fully informs the agent.

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 focused paragraph with no wasted words. Every sentence contributes actionable information: purpose, when to use, output details, technical implementation, and limitations.

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

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

Given the tool has three well-documented parameters, no output schema needed (output is described inline), comprehensive annotations, and behavioral details, the description leaves no practical gaps. An agent can confidently decide when to use this tool and what to expect.

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 documented. The description adds value by explaining the 'text' parameter's maximum length and truncation behavior, giving concrete examples for the 'query' parameter (e.g., 'supply-chain risk'), and specifying the default and range for 'limit'. This goes beyond the schema's basic descriptions.

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

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

The description uses a specific verb-resource pair ('Semantic search INSIDE a fetched record') and clearly distinguishes the tool by naming its sibling 'ask_pipeworx_grounded' and explaining how they pair together. Examples (SEC 10-K, article) further clarify the domain.

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: 'Use when the record is too big to cram into the prompt' and provides a complementary workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear if-then guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains the need for OAuth, absence of persistence for anonymous users, constraints on delivery channels (phone verification, 10/day SMS cap), and return of subscription ID. This enriches the agent's understanding without contradicting annotations.

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

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

The description is well-structured: it starts with the primary action, then covers prerequisites, supported types, and delivery options. Every sentence adds value, and the information is front-loaded for quick comprehension.

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

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

Given the tool's complexity (3 parameters, 5 enum types, nested objects, multiple delivery channels) and absence of an output schema, the description thoroughly covers input configuration, constraints, and return value. It provides enough detail for an agent to correctly invoke the tool.

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

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

While schema coverage is 100%, the description elaborates on each parameter's structure with type-specific examples (e.g., sec_8k with items codes, polymarket_edge with topic). It also details delivery channel semantics, including webhook signing and auto-disable conditions, adding significant value beyond the JSON schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription, with a specific verb ('Create') and resource ('proactive monitoring subscription'). It also mentions the return value (subscription id), setting it apart from siblings like unsubscribe 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?

The description provides explicit requirements (Pipeworx OAuth account) and lists supported types with examples. It does not explicitly state when not to use the tool or alternatives, but the context is sufficiently clear for an agent to judge appropriate 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 declare readOnly, idempotent, non-destructive. Description adds value by explaining return structure (example questions with tool+argument shapes) and that it draws from a live catalog. 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?

Somewhat verbose with synonym list, but front-loaded and well-structured. Each sentence adds value. Could be condensed slightly 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?

No output schema, but description clearly explains what is returned (category-bucketed examples with tool+argument shapes). Also covers when to use, parameter variants, and relationship to meta-tools. Fully adequate for agent understanding.

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: lists example focus values ('finance', 'pharma') and explains behavior when omitted ('cross-category spread'). This goes beyond schema's brief 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 tool is for onboarding: 'the onboarding entry point for an agent that just connected'. Uses specific verbs ('returns category-bucketed example questions') and distinguishes from siblings like ask_pipeworx, discover_tools by framing as first-use 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 advises use 'FIRST when you do not yet know what Pipeworx can do'. Also explains optional topic parameter. Lacks explicit when-not-to-use, but context strongly implies it's for initial 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?

Adds value beyond annotations by stating ownership enforcement, row deactivation, and historical event availability. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true).

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, no extraneous information. Every sentence is valuable.

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 simple tool (1 param, no output schema), description fully covers ownership, effect, and relation to other tools. Annotations handle rest.

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

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

Schema coverage is 100% and description for 'id' is minimal and already present in schema. Description adds no extra meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. 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?

Provides context on ownership enforcement and effect (deactivation not deletion). Mentions alternative tool 'recent_alerts' for historical events. Lacks explicit when-not-to-use but sufficiently guides 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?

Beyond the annotations (readOnly, idempotent, openWorld, destructive false), the description adds critical behavioral context: it explains the meaning of 'could_not_verify' (check failed, not evidence), 'unsupported' (no source covers it), the two execution paths (SEC EDGAR vs grounded), and the return format. This goes well beyond what annotations provide.

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

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

The description is dense but every sentence earns its place: trigger phrases aid selection, usage guidance is explicit, return types and the 'could_not_verify' warning are essential for correct invocation. It is front-loaded with purpose and structured logically, making it easy to scan despite 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?

With no output schema, the description fully compensates by detailing the verdict list, citation, reasoning, and the critical distinction between 'could_not_verify' and 'unsupported'. It also explains the pipeline and why this tool replaces multiple calls, making it self-contained and complete for the agent.

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

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

Schema coverage is 100%, so the description doesn't need to add parameter details. It adds a small amount of context about tolerance math and overrides, but the schema already fully describes both 'claim' and 'tolerance_pct'. Baseline 3 is appropriate.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources, with explicit trigger phrases ('fact check', 'verify the claim that...'). It distinguishes itself from siblings by focusing specifically on claim verification and notes it replaces 4-6 sequential calls, making its purpose and scope unambiguous.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context for when to invoke it. However, it does not mention when not to use it or name specific alternative tools, so it falls short of a perfect 5.

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