Epa Echo

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

The description explains that the tool picks the right source and fills arguments automatically, which is helpful behavioral context. With no annotations provided, it carries the full burden; it effectively communicates that the tool is a query router with delegation 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 concise at three sentences, front-loading the core purpose and immediately providing 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?

Given no output schema and a single parameter, the description is largely complete. It explains input format and behavior, but could briefly mention that results are returned as text or the range of data sources.

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 only parameter 'question' is well-described in the schema. The description adds semantic meaning by explaining how the parameter is used (plain English, auto-routed), going beyond the schema's generic description.

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

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

The description clearly states it accepts a plain English question and returns an answer by selecting the best data source. It contrasts with siblings by emphasizing natural language queries and automated tool selection, distinguishing it from structured search tools like echo_facility_search.

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

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

The description provides examples of appropriate queries and implies it should be used for natural language questions rather than structured tool calls. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint and openWorldHint. Description adds internal behavior: resolves market, classifies bet, fans out to packs (e.g., crypto+fred+gdelt for BTC), and returns evidence packet with comparison. No contradictions; adds specific context beyond annotations.

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

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

Concise yet informative. First sentence states core function, then elaborates with process and use cases. Every sentence adds value, no fluff. Front-loaded with main 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?

No output schema, but description fully explains output: evidence packet plus market-vs-model comparison. Covers resolution, classification, fan-out, and purpose. Agent has sufficient context to invoke correctly without guessing about return format.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning for 'depth' parameter: quick vs thorough with details on number of sources and fan-out, which is not in schema. Market parameter description in schema already adequate, description reinforces but does not add new semantics beyond the 3 input forms.

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 researches Polymarket bets by pulling Pipeworx data, using market slug, URL, or question text. It distinguishes itself as the core demo product and mentions agents using it convert better than discovering packs themselves, differentiating 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?

Explicitly lists use cases: 'should I bet on X?', 'what does the data say...', 'is there edge?'. Implies when not to use by contrast with agents that discover packs themselves, but does not name a specific alternative tool or state when not to use.

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

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

Despite no annotations, description discloses return data (paired data, URIs) and specific fields per type (revenue, net income, etc.). It implies read-only behavior without explicit statement, but sufficient for a comparison 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?

Three sentences with no filler: first states purpose, second explains types, third describes output. Highly efficient and front-loaded.

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

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

With only two simple parameters and no output schema, the description adequately covers purpose, usage, and output. Minor omission of edge cases, but schema covers constraints.

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

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

Schema coverage is 100% with descriptions. The description adds value by specifying the exact returned metrics for each type (e.g., 'revenue, net income' for company), enhancing understanding beyond enum values.

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

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

Description clearly states the tool compares 2-5 entities side by side, specifying two distinct types (company with SEC EDGAR metrics, drug with FDA stats) and mentions output format. It distinguishes from sibling tools like echo_* and memory 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?

Indicates when to use (comparing entities) and that it replaces sequential calls, providing clear context. While alternatives aren't explicitly listed, sibling tools are dissimilar enough to avoid confusion.

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 tool's search behavior and that it returns tool names and descriptions. However, it does not mention any limitations, such as whether the search is case-sensitive, handles synonyms, or requires exact phrasing. It also doesn't indicate if the tool has any side effects or state changes, though for a search tool, this is less critical.

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 at three sentences, with the most important information front-loaded. The first sentence defines the core action, the second explains the output, and the third provides usage guidance. There is no unnecessary information, though the third sentence could be slightly more precise about '500+ tools' being a general scenario.

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 the tool has a simple search interface with two parameters and no output schema, the description is nearly complete. It explains the purpose, usage guidance, and parameter usage. However, it doesn't mention the format of the results (e.g., list of tool names and descriptions) or any error handling (e.g., what happens if query matches nothing). For a search tool, this is acceptable but could be slightly more thorough.

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 context by explaining how to use the 'query' parameter (natural language description) and what the 'limit' parameter controls (max tools returned), which goes beyond the schema's basic description. The example values in the query description further clarify 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 clearly states the tool's purpose: to search the Pipeworx tool catalog by describing what you need. It specifies the action ('search'), the resource ('Pipeworx tool catalog'), and the expected outcome ('returns the most relevant tools'). This distinguishes it from sibling tools, which are all about specific data queries or memory 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 explicitly states when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear guidance on priority and context, differentiating it from other tools that perform specific actions.

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 behavioral traits. It mentions returns of compliance status, violations, inspections, and enforcement actions, but does not specify if the tool is read-only, potential rate limits, or data freshness. For a data retrieval tool with no annotations, more detail is expected.

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-loading the purpose and listing returned data types efficiently. 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 the single parameter and no output schema, the description adequately covers what the tool does and what it returns. However, it lacks details on potential empty results, pagination, or filtering options that might be present in sibling tools.

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 one parameter (registry_id). The description adds context by noting the ID comes from echo_facility_search results, which is helpful but not essential 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 retrieves compliance and enforcement history for a specific EPA-regulated facility, listing specific data types returned (compliance status, quarters in violation, inspection dates, enforcement actions). This distinguishes it from sibling tools like echo_enforcement_actions and echo_violations.

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 specifies the tool is for a specific EPA-regulated facility and mentions the required parameter (registry_id from echo_facility_search). However, it does not explicitly state when not to use it or compare with sibling tools like echo_enforcement_actions or echo_violations.

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 bears full burden. It discloses that the tool retrieves enforcement details and penalties, but does not mention authentication needs, rate limits, or any side effects. For a read-only tool, this is adequate but not thorough.

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 concisely states the purpose and includes the key resource and data types. No wasted words.

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

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

Given the tool's simplicity (single parameter, no output schema), the description provides essential information but lacks details on return format or pagination. For a straightforward retrieval tool, it is minimally complete but could mention if results are limited or require additional context.

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

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

The input schema has 100% description coverage, explaining the single parameter 'registry_id' and its source. The description adds no further parameter details, but the schema already fully documents it. Baseline 3 is elevated to 4 because the tool has only one parameter and the schema description is complete.

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 ('Get'), identifies the resource ('enforcement case details for a facility'), and lists included data types (formal/informal actions, penalties, amounts). It clearly differentiates from siblings like echo_compliance_history and echo_violations.

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 after obtaining a registry_id from echo_facility_search, but does not explicitly state when to use this tool versus siblings. No alternatives or exclusions are mentioned.

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

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

The description discloses the types of data returned (registry IDs, addresses, compliance status, program affiliations) but does not reveal behavioral traits beyond what is implied. With no annotations, the description provides basic behavioral context but lacks details on rate limits, authentication needs, or any 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 a single sentence that conveys all necessary information without redundancy. It is concise and front-loaded with the tool's 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 that the tool has no required parameters and no output schema, the description adequately covers the search capabilities and return types. It is complete enough for an agent to understand the tool's functionality.

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, so the description adds little beyond summarizing the search fields. It does not elaborate on parameter semantics 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 verb 'Search' and the resource 'EPA-regulated facilities', and lists specific search fields (name, state, ZIP, city, NAICS code) and return data (registry IDs, addresses, compliance status, program affiliations). It effectively distinguishes from sibling tools like echo_compliance_history or echo_enforcement_actions.

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 for searching facilities but provides no explicit guidance on when to use this tool versus alternatives like echo_search_by_violation. It does not specify that all parameters are optional or that at least one is recommended for narrowing results.

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 states the tool finds facilities in significant non-compliance and supports filtering, but does not disclose behavioral traits like data freshness, pagination, or the meaning of 'significant non-compliance'. The limit parameter is in the schema, so partial credit.

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 concise sentence of 16 words, front-loading the purpose. It is appropriately sized but could be more informative within the same length.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is somewhat complete for filtering but lacks guidance on return format, sorting, or result interpretation. It adequately covers the search purpose but leaves 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 description coverage is 100%, so baseline is 3. The description mentions 'state' and 'program' filters, matching the schema, but does not add extra meaning beyond the schema's own descriptions (e.g., that 'state' is a two-letter abbreviation or that 'program' uses acronyms). It adds no value beyond the schema.

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

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

The description clearly states it finds facilities in significant non-compliance, specifying the resource (facilities) and action (search/find). The title echoes this, but it doesn't distinguish from sibling tools like 'echo_compliance_history' or 'echo_violations', which may overlap.

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 mentions filtering by state and/or program, giving usage context. However, it does not provide explicit guidance on when to use this tool vs alternatives like 'echo_violations' or 'echo_compliance_history', nor does it mention 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 provided, the description carries the full burden. It explains the filter behavior but does not disclose details like pagination, rate limits, or what constitutes a 'detailed' record. A score of 3 is adequate as it covers the main function.

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, clear sentence that front-loads the core action and lists filter options succinctly. No wasted words.

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

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

For a tool with two parameters, 100% schema coverage, and no output schema, the description is sufficient. It explains the purpose and filter options. It could mention the output type or source, but the sibling tools hint at ECHO data, so it's reasonably complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds context by linking registry_id to echo_facility_search results and explaining the program parameter options (CWA, CAA, RCRA) with defaults, which goes beyond the schema's 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 it retrieves violation records for a facility, with an optional filter by environmental program. This is a specific verb+resource combination that distinguishes it from sibling tools like echo_compliance_history or echo_enforcement_actions.

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 mentions the optional filter by program, but does not explicitly state when to use this tool versus other violation-related siblings like echo_search_by_violation. However, the context suggests it is for a known facility, which is implicit.

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?

Although no annotations exist, the description discloses that the tool aggregates data from multiple sources in one call, returns citation URIs, and currently only supports 'company'. It could mention potential performance implications or response size, but overall it provides adequate transparency for a read‑only profile 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, using three sentences to convey purpose, inputs, and outputs. It front‑loads the main purpose and lists data categories efficiently without extraneous 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?

While the description covers purpose, inputs, and citations, it lacks details about the output structure (e.g., JSON fields) and does not mention pagination or size limits. For a profile tool without an output schema, more guidance on the returned format would improve completeness.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value by clarifying that 'value' accepts ticker or CIK (not names) and that 'type' is restricted to 'company', directing users to 'resolve_entity' for name resolution.

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 ('Full profile'), the resource ('entity'), and the scope ('across every relevant Pipeworx pack in one call'). It lists specific data categories returned for 'company' type, distinguishing it from sibling tools like 'resolve_entity' and 'compare_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?

Explicit guidance is given: use when you need a full profile, and if you only have a name, use resolve_entity first. It also notes the supported type ('company only') and input format (ticker or CIK), providing clear when-to-use and when-not-to-use instructions.

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

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

No annotations provided, so description must carry the burden. Description clearly states deletion, which implies irreversibility. However, no details about side effects or confirmation, but acceptable for a simple key-based delete.

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 sentence, no waste. Front-loaded with verb and resource.

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 simplicity (1 required param, no output schema, no nested objects), description is complete enough. No need for return value details.

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

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

Schema description coverage is 100%, so description adds no extra semantics beyond schema's 'Memory key to delete'. Baseline 3 is appropriate.

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

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

Description clearly states the verb (delete) and resource (stored memory by key), and 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?

Implied usage: use when you need to delete a memory. No explicit when-not or alternatives, but given the tool's simplicity, it's adequate.

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

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

With no annotations, the description carries the full burden. It discloses the rate limit ('5 messages per identifier per day') and notes it is 'Free,' indicating no cost. It does not detail confirmation or visibility, but for a feedback tool this 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 very concise: four sentences, each adding distinct value. It front-loads the core purpose, then lists use cases, then guidelines, then rate limit. No wasted words.

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

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

Given the tool's simplicity (3 parameters with full schema, no output schema), the description covers purpose, usage, behavioral constraints, and parameter semantics completely. No gaps remain for an agent to misuse it.

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

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

Schema coverage is 100%, so parameters are well-described in the schema. The description adds value by clarifying the meaning of each type (bug, feature, data_gap, praise, other) and providing guidance on writing the message (be specific, 1-2 sentences, 2000 chars max). 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 'Send feedback to the Pipeworx team' and lists specific use cases: bug reports, feature requests, missing data, or praise. This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which serve different purposes.

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 of use, including what to 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 notes the rate limit. However, it does not explicitly mention when not to use or suggest alternatives, but the purpose is self-contained.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds significant behavioral context: it explains the algorithm (monotonicity checking), the two modes of operation, and the output format (ranked opportunities with trade direction and reasoning). No contradiction.

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

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

The description is well-structured, front-loaded with the main purpose, and logically organized into two modes. While slightly lengthy, every sentence contributes meaning. Could be slightly tighter but still effective.

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

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

Given the complexity (two modes, cross-event logic) and lack of output schema, the description adequately covers what the tool does, how it works, and what it returns (ranked opportunities with reasoning). It addresses both usage modes and their rationale.

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 beyond the schema by explaining the two modes, giving examples of valid inputs (e.g., event slug, topic phrase), and clarifying how each parameter triggers a specific search mode.

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

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

The description clearly states the tool's purpose: find arbitrage opportunities on Polymarket by checking monotonicity violations. It specifies two distinct modes (event and topic) with concrete examples, making the resource and action unambiguous.

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

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

The description provides explicit guidance on when to use each mode: single-event for within-event checks, cross-event for across-events, and explains why cross-event catches cases single-event misses. It also mentions the topic mode for seed questions, giving clear usage 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 (readOnlyHint, openWorldHint, destructiveHint), the description details the process: scanning top markets, grouping by asset, fetching price history once, computing model probability, and ranking by edge magnitude. This adds 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?

The description is a single coherent paragraph that front-loads the main purpose and includes all necessary details. While somewhat lengthy, every sentence adds value, so it is appropriately concise 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?

Given no output schema, the description effectively explains the return (top N ranked by edge magnitude with trade direction) and covers the process, data sources (FRED, coinpaprika), and input parameters. It is complete for an agent to select and invoke correctly.

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

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

Input schema has 100% description coverage, so the description adds no new meaning beyond what the schema already provides (e.g., limit, window, min_edge_pp). The description restates schema details without enhancing parameter semantics.

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

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

The description clearly states the tool scans highest-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, specifying the verb, resource, and purpose. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection rather than 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 indicates it is built for the 'what should I bet on today' question and mentions it covers crypto-price bets, providing context for when to use. However, it does not explicitly state when not to use or directly name alternative tools, leaving some room for ambiguity.

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 that memories persist across sessions ('saved earlier in the session or in previous sessions'), which is critical behavioral context not captured in any annotations. However, it does not mention whether retrieval is read-only or any 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?

Two sentences, front-loaded with the primary purpose, no wasted words. Every clause 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?

For a simple parameterless-or-one tool with no output schema, the description fully explains the two modes of operation and the persistence behavior. No gaps remain.

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

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

Schema coverage is 100% with a single parameter described clearly. The description adds the dual behavior (omit key to list all) beyond what the schema's 'omit to list all keys' states, adding context about cross-session persistence.

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 'retrieve' and resource 'stored memory', with explicit dual functionality: single key retrieval or listing all keys when omitted. This distinguishes it 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 specifies when to use (retrieve context saved earlier) and implies when to omit key (to list all). However, it does not explicitly exclude use cases or mention alternatives beyond the sibling context implied by the tool names.

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

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

Describes parallel fan-out behavior, accepted date formats, and return structure (changes, count, URIs). Since no annotations exist, the description carries full burden and discloses key behavioral traits, though could mention rate limits or error handling.

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?

Comprises three focused sentences: purpose, details, and usage. No redundant words, front-loaded with the main purpose, 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?

Covers all main aspects: inputs, behavior, outputs, and use case. Lacks details on potential errors or time window limits, but for a monitoring tool it is sufficiently complete given the good parameter descriptions.

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

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

Adds significant meaning beyond the schema: explains 'type' only supports 'company', gives 'since' examples (ISO and relative), and explains 'value' can be ticker or CIK. Also describes return format, which compensates for lack of output 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?

Clearly states the tool retrieves changes about an entity since a given time, with specific details for 'company' type fanning out to SEC, GDELT, USPTO. Distinguishes from siblings like 'entity_profile' by focusing on recency and change monitoring.

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: 'brief me on what happened with X' or change-monitoring workflows. Does not explicitly exclude cases, but the context is clear and implies when to prefer this over snapshot 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?

With no annotations provided, the description carries the full burden. It discloses persistence behavior (authenticated users get persistent memory; anonymous sessions last 24 hours) and the nature of the operation (store/save). This is good behavioral context beyond just 'store a key-value pair.' However, it does not mention if overwriting an existing key is allowed or if there are size limits.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. The first sentence states the action, the second adds usage guidelines and persistence context. 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 the tool's simplicity (2 simple params, no output schema, no annotations), the description covers the key aspects: purpose, typical usage, and persistence behavior. It lacks mention of overwrite behavior or limits, but for a straightforward memory store this is sufficient.

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

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

Schema coverage is 100%, so the schema already documents both parameters with examples. The description adds no additional parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool stores a key-value pair in session memory, specifying the resource (session memory) and verb (store). It distinguishes itself from siblings 'forget' and 'recall' by focusing on writing data.

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

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

The description says 'Use this to save intermediate findings, user preferences, or context across tool calls,' which provides clear when-to-use guidance. It also mentions persistence differences for authenticated vs anonymous users, but does not explicitly say when not to use it or compare to alternatives beyond the implicit contrast with recall/forget.

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. Description adds efficiency context ('single call', 'replaces 2-3 lookup calls') and return format. However, it does not disclose idempotency, rate limits, or whether it requires authentication. Adequate for a simple resolver but could be more transparent.

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

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

Four concise sentences: purpose, scope with examples, output listing, and benefit. No wasted words. Information is front-loaded and easy 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 tool's simplicity (2 parameters, no output schema) and sibling tools (many unrelated echo/memory tools), the description covers input, output, and use case. Could explain return value structure more, but it lists fields clearly.

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 parameters are documented. Description adds practical examples (AAPL, 0000320193, Apple) and explains the enum constraint ('v1 supports company'). This provides 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 the verb 'resolve', the resource 'entity', and the outcome 'to canonical IDs'. It distinguishes from siblings by specifying it replaces multiple lookup calls, making its unique value proposition clear.

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

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

Explicitly mentions input formats (ticker, CIK, name) and version scope (v1 type='company'). States it replaces 2-3 lookup calls, implying efficiency. Could explicitly state when not to use it, but the context is sufficient.

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 discloses the return format (verdict, structured form, actual value, citation, percent delta), domain limitations (only company-financial claims), and data sources (SEC EDGAR + XBRL). It does not mention error handling or rate limits but provides solid transparency for a non-destructive validation 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 (3-4 sentences), front-loaded with the action, then scope, then returns, then benefit. Every sentence adds meaningful information without redundancy.

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

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

The description covers the tool's purpose, domain, output, and benefit. It lacks details on error handling or edge cases (e.g., unsupported claim types) but is reasonably complete given the tool's simplicity and lack of output schema.

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

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

The schema already has 100% coverage with a description and examples for the 'claim' parameter. The description adds value by reinforcing the supported claim types and format, going beyond the schema's basic definition.

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 'fact-check' and the resource 'claim against authoritative sources', specifies the domain (company-financial claims for US public companies), and distinguishes itself from siblings by noting it replaces multiple sequential agent 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 implies use for efficiency by stating it replaces sequential calls, but does not explicitly state when to use or not use it compared to alternatives. However, among siblings there is no direct competitor, so context is clear.

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