Chaos Index

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining cost implications (free for Workers AI, BYO key for Anthropic) and the return structure (per-model and combined view), going beyond annotations.

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

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

The description is concise with six well-organized sentences, covering core function, model options, output, and use cases without redundant information.

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

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

Despite no output schema, the description fully explains return values (score, confidence, signals, raw_response per model plus combined view). All four parameters are covered, and the use cases are clearly stated.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by specifying the default model for 'models', explaining the '_apiKey' usage as bypass to Anthropic, and providing example values for 'entity'.

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

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

The description uses a specific verb 'probe' and resource 'LLMs' to clearly state the tool's purpose. It distinguishes from siblings like 'entity_profile' and 'ask_pipeworx' by focusing on visibility scoring across multiple models.

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

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

Explicitly mentions use cases such as AI-marketing audits and pre-launch brand checks. It explains the default model and how to use Anthropic with an API key, though it does not explicitly state when not to use the tool or list alternatives.

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

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

Since no annotations are provided, the description carries the full burden. It clearly states the tool is a query interface that delegates to other data sources, implying no side effects. However, it doesn't specify response format, latency expectations, or error handling, but this is acceptable for a natural language query tool.

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

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

The description is concise (three sentences plus examples) and front-loaded with the core purpose. Every sentence adds value: the first defines the tool, the second explains the internal mechanism, the third gives usage guidance, and examples illustrate. No wasted words.

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

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

Given the tool's complexity (single parameter, no output schema, natural language interface), the description is complete. It covers what the tool does, how it works, when to use it, and provides examples. The lack of return value explanation is acceptable for a conversational 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 only one parameter. The description adds meaning beyond the schema by explaining the 'question' parameter should be in natural language and providing examples. A minor gap: it doesn't clarify if follow-up questions are supported or if context is preserved.

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: 'Ask a question in plain English and get an answer from the best available data source.' It uses a specific verb ('ask'), defines the resource ('Pipeworx'), and distinguishes itself from siblings by explaining that it internally selects tools and fills arguments, unlike direct tool calls.

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

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

The description provides explicit guidance on when to use: 'just describe what you need' and contrasts with browsing tools or learning schemas. It gives three concrete examples covering different domains, which helps the agent understand the tool's scope.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, which are consistent. The description adds behavioral context: it resolves the market, classifies the bet, fans out to packs, and returns an evidence packet with a market-vs-model comparison. This goes beyond the annotations by detailing internal logic and output structure.

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

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

The description is front-loaded with the purpose and is relatively concise for the amount of detail. Every sentence adds value, though it could be slightly more streamlined. Overall well-structured and informative.

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

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

Given the lack of an output schema, the description fully explains the return: an evidence packet plus a market-vs-model comparison. It covers input formats, internal processing (classification, fan-out), and output structure, making the tool's behavior completely understandable 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?

The input schema has 100% description coverage, but the tool description adds significant meaning: it explains that the 'market' parameter accepts a slug, URL, or question text, and the 'depth' parameter controls the number of sources (quick=2-3, thorough=full fan-out). This provides practical usage context 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 clearly states the tool's purpose: researching Polymarket bets by pulling Pipeworx data. It specifies the verb 'research', the resource 'Polymarket bet', and distinguishes it from siblings like 'ask_pipeworx' and 'validate_claim' by detailing the classification and fan-out process.

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

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

The description explicitly lists use cases ('should I bet on X?', 'what does the data say?', 'is there edge?') and explains that it is the core demo product. It implies when to use it over alternatives but does not explicitly state 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?

No annotations, but description clearly indicates it is a read-only calculation returning a score and breakdown. No hidden side effects disclosed, though not required for a stateless tool.

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?

Single concise sentence that front-loads the purpose and 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 simple tool: explains input (none), output (index 0-100 with component breakdown), and has output schema. No gaps.

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

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

No parameters, so schema coverage is 100%. Description adds no parameter info, which is acceptable as there are none.

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

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

Clearly states it calculates a chaos score combining specific factors (Bitcoin volatility, ISS orbital position, etc.) and returns a 0-100 index with breakdown. Distinct from sibling tools which focus on entities and memory.

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

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

No guidance on when to use this tool or when to avoid it. Lacks any mention of alternatives or exclusions, which is expected for a unique tool.

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

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

No annotations provided, so description carries full burden. It discloses the data returned for each type and the resource URIs, but doesn't cover authentication, rate limits, or error behavior. Adequate but not exhaustive.

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

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

Three sentences with front-loaded main action and constraint. Every sentence adds value, no wasted words.

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

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

Given no output schema, the description covers returned data per type and efficiency benefits. Lacks details on return format or error handling, but sufficient for common use.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates parameter usage but adds no significant new meaning beyond the schema descriptions.

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

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

The description clearly states the tool compares 2–5 entities side by side, specifies two types (company and drug) with exact data fields, and mentions returning paired data and URIs. It distinguishes from siblings that don't offer comparison functionality.

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

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

Explicitly says when to use: for comparing 2–5 entities in one call replacing 8–15 sequential calls. Does not provide explicit when-not-to-use or alternatives, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses the search behavior and returns names/descriptions, but doesn't mention side effects, authentication needs, or rate limits. A score of 3 is adequate given the tool is read-only by nature, though more detail would help.

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

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

The description is two sentences and front-loaded with purpose. It is concise with no wasted words, though it could be slightly shorter by combining the first and third sentences.

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

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

Given no output schema and simple parameters, the description covers the core use case well. It tells what it does, when to use it, and what to expect. Lacking return value details slightly reduces completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context by explaining that 'query' is a natural language description with examples, and mentions defaults for 'limit'. This adds value but doesn't go beyond what the schema already indicates.

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

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

The description uses specific verbs 'search' and 'returns', and identifies the resource as the Pipeworx tool catalog. It clearly distinguishes from siblings by stating 'Call this FIRST' and mentioning 500+ tools, which is a unique responsibility.

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 it ('when you have 500+ tools available and need to find the right ones') and provides a usage directive ('Call this FIRST'). No alternatives are mentioned, but the 'FIRST' instruction implies prioritization over siblings.

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

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

No annotations provided, so description carries full burden. It discloses return format (pipeworx:// citation URIs), data sources, and that it's a batch operation. However, does not explicitly state read-only nature or usage limits; but overall provides substantial behavioral context.

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

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

Description is two efficient sentences with a bullet-like list and a note; front-loaded with purpose. No fluff, but could be slightly more structured (e.g., separate sections).

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

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

For a complex tool aggregating multiple data sources with no output schema, the description covers inputs, returns, and when to avoid it. Lacks details on errors or performance, but adequate for an agent to use it correctly.

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

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

Schema coverage is 100%, but description adds extra guidance: explains that type only supports 'company', value accepts ticker or CIK, and names require prior entity resolution. This goes beyond the schema enum and 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?

Clearly states it returns a full profile of an entity across multiple packs, listing specific data sources (SEC filings, XBRL, patents, news, LEI). Distinguishes itself from siblings by noting it replaces 10-15 sequential calls and contrasts with usa_recipient_profile for federal contracts.

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

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

Explicitly tells when to use (need full entity profile) and when not to (federal contracts - use usa_recipient_profile). Also advises to call resolve_entity if only have a name, guiding the agent to proper tool selection.

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

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

No annotations provided, so the description carries full burden. It states deletion but does not disclose consequences (e.g., whether deletion is permanent, if it requires confirmation, or if it affects other data).

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

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

A single sentence of 5 words, directly conveying the purpose. No unnecessary words, but could be slightly more informative.

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

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

Given the tool's simplicity (1 param, no output schema, no nested objects), the description is minimally adequate. However, it lacks details about the result or side effects.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description adds minimal extra meaning beyond the schema, matching the baseline for high coverage.

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

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

The description clearly states the action ('Delete') and the resource ('stored memory by key'). It effectively distinguishes from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

No guidance on when to use this tool versus alternatives. For example, it does not mention that 'forget' removes a specific key, while 'remember' stores one, or that 'recall' retrieves without deleting.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the extraction process (fetches page, extracts title/description/key links) and output format, which goes beyond annotations.

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

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

The description is concise (3 sentences), front-loaded with the primary action, and contains no redundant or vague statements. 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?

Without an output schema, the description adequately explains the output (standard llms.txt markdown format, single text blob). The tool is simple with 2 parameters, and the description covers the core functionality. Minor omission: no mention of error handling or rate limits, but these are not critical for this tool.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add parameter-specific details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifies the target audience (AI crawlers), and lists concrete use cases. It distinguishes itself from siblings, none of which perform similar functions.

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 (indexing client sites, drafting own project, auditing competitors), giving clear context for when to use. It does not explicitly list when not to use, but the read-only and idempotent annotations imply safe repeated use.

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

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

With no annotations, the description carries the full burden. It discloses that the tool sends feedback (mutating action) and is rate-limited to 5 messages per day per identifier. It does not mention authentication or data handling, but for a feedback tool this is acceptable. 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 short (3 sentences) with front-loaded purpose. Every sentence provides essential information: what the tool does, usage guidance, and rate limiting. No wasted words.

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

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

Given the tool's low complexity (3 params, optional nested object, no output schema), the description adequately covers purpose, usage, and rate limits. It does not describe the return value, but for a fire-and-forget feedback tool that is acceptable. Could mention if feedback is anonymous, but overall complete enough.

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 providing usage context for the 'message' parameter ('Describe what you tried in terms of Pipeworx tools/data') and reinforcing the type options. This goes beyond what the schema provides, earning a 4.

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

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

The description clearly states the verb 'Send' and the resource 'feedback to the Pipeworx team', and lists specific use cases (bug reports, feature requests, etc.). It distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on feedback rather than 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?

The description explicitly says when to use the tool (for feedback types) and provides guidance on what to include ('Describe what you tried in terms of Pipeworx tools/data') and what to avoid ('do not include the end-user's prompt verbatim'). It also mentions rate limiting (5 per day per identifier), which helps the agent manage usage. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already indicate safety and idempotency. The description adds valuable transparency: data source (CF analytics-engine), no PII, and caching duration (5min-1h). This goes beyond annotations, fully disclosing behavioral traits.

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

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

The description is moderately concise, front-loading the main purpose. It efficiently covers all aspects without redundancy. A slightly tighter structure could improve, but it already earns its space.

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 simplicity of the tool (one parameter, no nested objects, no output schema), the description fully explains what is returned, data source, caching, and use cases. It is complete for an agent to decide and invoke correctly.

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

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

Schema covers the window parameter with enum and description. The description adds interpretative guidance on window choice ('hot' vs 'steady-state'), providing extra meaning beyond the schema. Baseline 3 is exceeded by this added nuance.

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 returns top tools, packs, and call volume over windows. It distinguishes itself from siblings by specifying the output (trending data) and provides three explicit use cases, making the purpose unmistakable.

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

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

The description lists three specific scenarios (discovering hot data sources, confirming canonical tools, aligning use cases) and explains window trade-offs. It could be improved by explicitly stating when not to use it, but the context and sibling list make it clear.

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

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

Annotations already indicate readOnly=true, non-destructive. The description adds behavioral details: walks child markets, groups related markets, checks monotonicity, returns ranked opportunities with reasoning. 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 paragraph packed with essential information: modes, examples, rationale. Every sentence adds value; no wasted words.

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

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

Despite no output schema, the description explains returns: ranked opportunities with trade direction and reasoning. It covers the two modes and their logic. Minor omission: no mention of error handling or prerequisites, but sufficient for a non-trivial 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 meaning by explaining the behavior associated with each parameter: event mode walks child markets, topic mode searches across events and groups. This goes beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket by checking monotonicity violations. It distinguishes two modes (event and topic) and explains how cross-event mode catches cases that single-event mode misses, differentiating it from sibling tools like 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 clear context for when to use each mode: event for a specific slug, topic for cross-event searches. It gives an example and explains the advantage of cross-event mode. However, it does not explicitly state when not to use the tool or compare directly to siblings.

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

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

The description provides extensive behavioral details beyond the annotations: it explains the V1 model (lognormal from FRED + coinpaprika), steps (scans top markets, groups by asset, fetches price history once, computes probabilities, ranks by edge), and output (top N with suggested trade direction). Annotations already indicate read-only and non-destructive, and the description reinforces and expands on this.

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

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

The description is moderately concise at 5-6 sentences, well-structured with a clear purpose, method, and use case. It is appropriately sized for the tool's complexity without being verbose.

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

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

Given no output schema, the description adequately explains the return format (top N ranked by edge magnitude with suggested trade direction). It also covers data sources and model, providing sufficient context for an agent to understand 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 description coverage is 100%, so each parameter is already explained in the input schema. The description adds context by explaining the overall ranking algorithm, but does not significantly enhance understanding of individual parameters beyond the schema descriptions.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, using specific verb and resource. It distinguishes from sibling tools like polymarket_arbitrage by focusing on edge-based 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?

The description explicitly states it is built for the 'what should I bet on today' question, providing context for when to use. While it doesn't list alternatives or exclusions, the context is clear enough for an agent to infer 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about why spreads arise (different participant pools, 2-25pp range) and specifies return values (raw probabilities and percentage point spread), which is consistent 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 informative but verbose, containing multiple sentences explaining context and modes. It is structured into two parts but could be 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?

The description explains the tool's functionality, two modes, and return values (prices and spread) sufficiently. Given no output schema, it covers what to expect, though the exact return structure is not detailed.

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

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

Schema coverage is 100% with descriptions for each parameter, but the tool description adds the concept of two modes and explains that explicit parameters override topic-mapped sides, providing meaningful context 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 that the tool provides the cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb+resource ('spread'). It mentions the arb signal but does not explicitly differentiate from sibling tools 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 explains two usage modes (pre-mapped topics and explicit parameters) and provides examples. However, it does not explicitly state when to use this tool versus alternatives 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?

With no annotations, the description carries full burden. It correctly describes the tool as read-only (retrieve/list) and indicates session persistence. Could add that omitting key lists all keys but that's already in description. 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 wasted words. The first sentence states core functionality; the second gives usage context. Front-loaded with the essential action.

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

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

Given no output schema, the description could mention the format of returned memories. But for a simple retrieval tool with one optional parameter, it's sufficiently complete. The mention of 'previously stored' and 'earlier in the session or in previous sessions' covers persistence context.

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

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

Schema coverage is 100% (key param described in schema). The description adds the semantics that omitting key lists all memories, which is not in schema. This clarifies the optional behavior effectively.

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 retrieves a memory by key or lists all memories when key is omitted. It uses specific verbs ('Retrieve', 'list') and a resource ('previously stored memory'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete).

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 when to use this tool ('retrieve context you saved earlier') and implies when not to use it (no key to list all). It provides clear context for the agent to decide between recall and other memory tools.

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

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

Given no annotations, the description fully explains the tool's behavior: parallel fan-out to SEC EDGAR, GDELT, USPTO; accepted date formats; return structure including URIs and total count. It does not mention error handling or rate limits but covers core behavioral traits well.

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

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

The description is concise and well-structured, starting with the main purpose, then detailing the fan-out, date formats, return values, and use cases. Every sentence adds necessary information without redundancy.

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

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

Despite lacking an output schema, the description explains return values (structured changes, total_changes, pipeworx:// URIs) and covers all aspects: purpose, parameters, behavior, and output. It is sufficiently complete for reliable tool selection.

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

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

The input schema has 100% coverage with detailed descriptions. The description adds further value by providing examples for 'since' (ISO and relative) and typical usage ('30d' or '1m'), as well as clarifying the 'value' parameter with examples like 'AAPL' or CIK.

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

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

The description clearly states the tool's function: reporting what is new about an entity since a given time, with a specific example for companies. It distinguishes itself from siblings by detailing the parallel fan-out to multiple data sources and mentioning specific use cases like 'brief me on what happened with X'.

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 gives usage scenarios ('brief me on what happened with X', change-monitoring workflows) but does not mention when not to use it or directly compare to siblings. However, the context is sufficient for typical use cases.

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?

No annotations are provided, so the description carries full burden. It discloses behavioral traits: persistent memory for authenticated users, 24-hour expiration for anonymous sessions. This adds meaningful context beyond the schema.

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

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

Three sentences, each adding distinct value: what it does, when to use it, and 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?

Given no output schema and two simple parameters, the description is complete. It explains purpose, usage, and memory persistence. Could mention that values are overwritten on duplicate keys, but not essential for a simple key-value store.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context about what values might be stored (e.g., findings, addresses) but does not elaborate on key naming conventions or constraints 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 stores a key-value pair in session memory, distinguishing it from siblings like 'recall' (retrieve) and 'forget' (delete). It uses specific verbs ('store') and resource ('session memory').

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 context for when to use this tool: to save intermediate findings, user preferences, or context across tool calls. However, it does not explicitly mention when not to use it or directly compare to alternatives like 'recall' or 'forget', so a slight deduction.

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?

No annotations are provided, so the description must fully disclose behavior. It describes inputs and outputs (ticker, CIK, company name, URIs) but omits information about error handling, rate limits, authentication requirements, or what happens if the entity is not found. This leaves significant behavioral gaps.

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

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

The description is concise, with three sentences that front-load the core purpose and provide necessary examples. Every sentence adds value without redundancy.

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

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

While the tool has no output schema, the description covers return values. However, it lacks details on edge cases, error responses, or potential limitations. For a simple entity resolution tool, it is minimally adequate but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by providing concrete examples (e.g., 'AAPL', '0000320193', 'Apple') and explaining that the output includes pipeworx:// URIs, which enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: resolve an entity to canonical IDs across Pipeworx data sources in a single call. It specifies the supported entity type (company) and provides examples of accepted inputs (ticker, CIK, name), which distinguishes it from sibling tools like ask_pipeworx.

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

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

The description implies usage by mentioning it replaces 2–3 lookup calls, but it does not explicitly state when to use this tool over alternatives like ask_pipeworx, nor does it provide when-not-to-use conditions. The guidance is present but not fully explicit.

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 and destructiveHint false. The description adds behavioral details: probes multiple entities, ranks results, returns scores, confidence, signal density. No contradictions. The description enriches the safety profile with process context.

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

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

The description is concise (4 sentences), front-loaded with the primary purpose, and each sentence provides essential information: process, use case, output format. No unnecessary words.

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

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

Given no output schema, the description covers the return format (ranked list with score, confidence, signal density). It explains inputs well, mentions the dependency on ai_visibility_check, and provides a concrete example. The description is complete for the tool's complexity and annotation richness.

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 explains all parameters. The description adds value by explaining that the first entity is treated as 'subject' for narrative and that models default to 'workers-ai' unless 'anthropic' is specified with an API key.

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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility audits.

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 specific use case (competitive AI-marketing audits) and implicitly suggests that for single-entity checks, one should use ai_visibility_check. It does not explicitly list alternatives or 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?

No annotations are provided, so the description carries the full burden. It discloses the verdict categories, structured output, citation, and efficiency benefit. It does not mention destructive behavior (none needed), authentication, or rate limits, but for a read-only fact-checking tool, the disclosure is adequate.

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

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

The description is two sentences, front-loaded with the core purpose, and each sentence adds meaningful detail. There is no wasted text, and the structure is efficient for an AI agent to parse.

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 single parameter, no output schema, and no annotations, the description covers the tool's scope, input, output, and limitations (e.g., version 1 supports only certain types). It could mention error handling or edge cases, but for this complexity level, it is largely 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?

The single parameter 'claim' has 100% schema description coverage. The description adds example values and context about natural-language format. This adds some value beyond the schema, but since the schema already includes a description, the improvement is marginal, warranting a baseline score of 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?

The description clearly specifies the tool's purpose: fact-check natural-language claims against authoritative sources. It distinguishes itself by naming the domain (company-financial claims), sources (SEC EDGAR + XBRL), and the return format (verdict, extracted form, citation). This makes it distinct from siblings like compare_entities or entity_profile.

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 states the tool supports company-financial claims for public US companies, which implies when to use it. It mentions replacing sequential agent calls, but does not explicitly provide when-not-to-use scenarios or name alternative tools for other claim types. This is clear context but lacks explicit exclusions.

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