Excuse

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds beyond that: explains default model (Workers AI Llama-3.3-70b free), optional Anthropic with BYO key and cost implication, and return structure. 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?

Four sentences, no wasted words. Front-loaded with core purpose, then details on config and usage. Efficient and scannable.

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 specifies return format (per-model object with keys and combined view). Covers parameters, auth, cost nuance. Could mention that 'models' array accepts multiple values, but implied. Sufficient given tool complexity.

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

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

Schema covers 100% of parameters with descriptions. Description adds context: explains why _apiKey is needed (BYO key for Anthropic), disambiguation via context param, and default behavior. Baseline 3 but adds meaningful value.

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

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

The description uses a specific verb ('probe') and resource ('LLMs'), clearly stating the action and output (visibility scores 0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on scoring per model and returning detailed signals.

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

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

Explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not state when to avoid the tool or mention alternatives, but the context is clear enough.

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 convey behavioral traits. It states that Pipeworx picks the right tool and fills arguments, implying delegation, but does not disclose important details like latency, rate limits, or whether results are cached. The agent lacks information about side effects or limitations.

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) and front-loaded with the core action. It includes examples, which aid understanding. However, the second sentence could be more specific about what 'best available data source' means.

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 parameter, no output schema, no nested objects), the description is adequate but lacks details on what the answer format looks like or how errors are handled. The examples help, but more context on the tool's autonomy (e.g., selecting data sources) 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 a single parameter 'question', described as 'Your question or request in natural language'. The description adds examples of expected input (e.g., 'What is the US trade deficit with China?'), which enriches the schema's bare description. Baseline 3 is appropriate since schema already provides basic meaning.

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: asking questions in natural language and getting answers from the best data source. It uses a specific verb ('ask') and resource ('question'), and includes examples that illustrate typical use cases. However, it does not explicitly distinguish itself from sibling tools, though its role is distinct as a general question-answering tool.

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

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

The description provides examples of when to use the tool (e.g., asking for trade deficits, drug adverse events, SEC filings) but does not explicitly state when not to use it or mention alternatives. The sibling tools like 'discover_tools' and 'remember' suggest there are other query-related tools, but no guidance is given on choosing among them.

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

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

The description adds rich behavioral context beyond annotations: it resolves the market, classifies the bet, fans out to appropriate data packs, returns an evidence packet and comparison. Annotations (readOnlyHint, openWorldHint) are consistent and reinforced. No contradictions.

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

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

The description is four sentences, each adding value: core purpose, input format, process, and usage context. It is front-loaded and efficient, with no unnecessary words. It earns its length.

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

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

Despite no output schema, the description fully explains what is returned (evidence packet, market-vs-model comparison). It covers inputs, outputs, and internal logic (classification, fan-out). Very complete for a research tool.

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

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

Schema description coverage is 100%, but the description adds meaning beyond schema: it explains the market parameter can be slug, URL, or question text; clarifies depth as 'quick' or 'thorough' with defaults. This enhances understanding of parameters.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies the verb 'research', the resource 'Polymarket bet', and distinguishes from siblings like ask_pipeworx by its focus on Polymarket. The description is specific and unambiguous.

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

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

The description explicitly lists use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It also gives guidance on why to use this tool over alternatives, noting that agents using it convert better. No ambiguity about when 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 are provided, so the description must disclose behavioral traits. It describes the data returned (e.g., revenue, net income for companies; adverse-event counts for drugs) and resource URIs, but does not mention safety aspects like read-only nature, authentication requirements, or rate limits. This is adequate but not comprehensive.

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

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

The description is extremely concise, using two sentences to convey purpose, scope, data sources, and benefits. Every word adds value, with no redundancy.

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

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

Given the lack of output schema, the description adequately explains the return data for both entity types and mentions URIs. It is complete for a comparison tool, though it doesn't cover error handling or edge cases. The complexity is moderate and the description meets the need.

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 value by explaining the meaning of 'type' values and mapping 'values' to specific inputs (tickers/CIKs for company, names for drug) and linking to return fields, going beyond the schema.

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

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

The description clearly states the tool's purpose: comparing 2–5 entities side by side. It specifies the two entity types (company, drug) with distinct data sources and return fields, and distinguishes itself from sibling tools by emphasizing batch comparison in one call, replacing multiple sequential 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 when to use (multiple entities) but does not explicitly state when not to use or provide alternatives. For example, it doesn't mention that for a single entity one might use resolve_entity. The replacement statement is helpful but not a full guideline.

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 behavioral info. It states the tool returns 'most relevant tools with names and descriptions', implying a search/ranking behavior. Does not mention sorting, pagination, or what happens if query is vague. However, 'returns the most relevant' is sufficient for a discovery 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, each earning its place: first sentence states action and result, second adds usage context ('Call this FIRST'), third provides typical use case. No fluff.

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

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

Given that output schema is absent and schema coverage is high, description is complete enough for a search tool. It tells what it returns (names and descriptions) and when to use it. Minor missing: no mention of error handling or what happens if no tools match, but not critical.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add additional semantics beyond schema: schema already explains 'query' and 'limit' well. No extra context needed.

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

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

Description clearly states verb ('search'), resource ('Pipeworx tool catalog'), and purpose ('find the right tools'). Distinguishes from siblings: explicitly tells agents to call this FIRST when needing to find tools, unlike 'ask_pipeworx' for Q&A or memory tools like 'remember'/'forget'.

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

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

Explicitly states when to use ('Call this FIRST when you have 500+ tools available and need to find the right ones'), implying when not to use (when you already know the tool). No alternative tool named, but the context of 500+ tools makes this a unique entry point.

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 the tool returns 'pipeworx:// citation URIs' and replaces multiple sequential calls, implying efficiency. However, with no annotations provided, it lacks explicit statements about idempotency or safety traits, though the read-only nature is inferred.

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 compact, front-loading the core purpose, then listing data items, return format, efficiency gain, and an exclusion. Every sentence adds unique 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?

The description covers input constraints, output format (citation URIs), and data scope comprehensively. It lacks details about response structure or pagination, but for a single-call profile tool the coverage 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?

Both parameters have full schema descriptions (100% coverage). The tool description adds context by specifying acceptable identifier formats (ticker, CIK) and condition for names, enhancing the schema details meaningfully.

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 provides a 'full profile of an entity across every relevant Pipeworx pack in one call' and lists specific data types (SEC, XBRL, patents, news, LEI). It explicitly distinguishes from sibling tools by noting federal contracts should use usa_recipient_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 gives explicit when-not-to-use guidance ('For federal contracts call usa_recipient_profile directly') and conditions for input ('Names not supported — use resolve_entity first'). It also implies when to use this tool for comprehensive company profiles.

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 states the tool returns humorous or plausible text immediately, but does not disclose whether it is deterministic, idempotent, or has side effects. For a generation tool, this is moderate.

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 that front-loads the action and purpose. It is efficient but omits parameter details, earning a high but not perfect score.

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

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

Despite having an output schema, the description does not elaborate on return values or parameter behavior. With 4 parameters and no annotations, this brief description is insufficient for complete guidance.

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 low (25%), only one property described. The description adds no extra meaning beyond the schema enums (e.g., audience, excuse_quality). It fails to explain optional parameters.

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

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

The description explicitly states it generates a creative excuse for specific scenarios (late, missed deadline, ghosted). It clearly distinguishes from sibling tools (none are excuse generators).

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 when to use (when needing an excuse for these situations) and no alternative sibling exists. However, it does not explicitly state when not to use or provide prerequisites.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It states the action ('Delete') but does not mention irreversibility, required permissions, or effects on 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?

The description is a single sentence of six words, containing no fluff. Every word contributes to understanding the tool's function.

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 (1 param, no output schema, no nested objects), the description is mostly complete. It could mention that deletion is permanent or note any preconditions.

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 'key' is clearly described in the schema as 'Memory key to delete'. The description reaffirms its role, adding no extra semantics but not needing to.

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 ('Delete') and resource ('stored memory by key'), clearly distinguishing it from sibling tools 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?

The description implies usage for deletion by key but does not explicitly state when to use this tool over others or mention any prerequisites or caveats.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint false. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown, enhancing transparency beyond the annotations.

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

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

The description is four sentences, starts with the primary purpose, provides clear steps and output format, and contains no redundant information.

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

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

Given lack of output schema, the description explains the output as a single text blob for site-root/llms.txt, which is sufficient. It does not cover error handling, but for this simple tool it is nearly 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 description reiterates the max_links parameter as 'maximum number of link entries', adding no significant meaning 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 an llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation.

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: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It doesn't mention when not to use, but the context is sufficient for an agent to decide.

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 discloses rate limiting and 'free' status, but does not mention whether the tool returns any response or is asynchronous. Additional detail on expected behavior (e.g., fire-and-forget) would enhance transparency.

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

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

Three concise sentences front-load the purpose, then cover usage constraints and rate limit. No redundant 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?

For a simple feedback tool with no output schema, the description covers purpose, content guidelines, and rate limiting. Could clarify that no response is expected, but is largely sufficient for an AI agent to use correctly.

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

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

Schema coverage is 100%; the description adds value beyond schema by advising on message content (describe in terms of tools/data, avoid user prompt) and reinforcing the purpose of the 'type' enum, making parameters more actionable.

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 enumerates specific use cases (bug reports, feature requests, missing data, praise), making the purpose explicit and distinct from sibling tools.

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

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

Provides clear guidance on when to use (for feedback types) and what to include/exclude (describe in terms of tools/data, no user prompt). Mentions rate limit (5 per identifier per day). Could be improved by explicitly listing when not to use, but the context suffices.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). This goes beyond the annotations without contradiction.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. It uses a bullet-like list for use cases without extraneous words, every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the what, why, and how. It explains the data source, caching, and three usage scenarios. It could hint at the output structure more explicitly, but the description is nearly 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 'window' has full schema coverage (enum with description). The description adds semantic nuance: shorter windows for hot items, longer for steady-state, enhancing the schema's minimal 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 returns top tools, top packs, and total call volume over a recent window. It uses a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'), distinguishing it from sibling tools that focus on specific queries or entities.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment), providing clear guidance on when to use. It does not explicitly mention when not to use or alternatives, but the context is sufficient for a focused 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?

Annotations already indicate read-only, open-world, non-destructive behavior. The description adds meaningful context about monotonicity checking, two search modes, and return format (ranked opportunities with reasoning), going beyond annotations without contradicting them.

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

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

The description is concise yet comprehensive, front-loading the core purpose and then explaining the two modes efficiently. Every sentence contributes useful 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?

Given the tool's complexity (two modes, cross-event search), the description covers all essential aspects: purpose, modes, usage, and return format. No output schema is needed because the description adequately describes the returned opportunities.

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. The description adds value by explaining the modes in more detail and providing examples (e.g., 'when-will-bitcoin-hit-150k', 'Strait of Hormuz traffic returns to normal'), which aids understanding beyond the schema alone.

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

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

The description explicitly states the tool's purpose: finding arbitrage opportunities via monotonicity violations on Polymarket. It differentiates between two modes (event and topic), making it distinct from sibling tools like bet_research or validate_claim.

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

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

Provides clear guidance on when to use each mode: event for single-event subtleties, topic for cross-event comparisons. Includes a concrete example illustrating why topic mode is needed, effectively setting 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?

Annotations already mark the tool as read-only and non-destructive. The description adds substantial transparency by detailing the internal process: scans top markets, groups by asset, fetches price history once per asset, computes model probability (using FRED + coinpaprika), and ranks by edge. It also specifies the output includes trade directions.

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, dense paragraph that efficiently conveys the tool's purpose, scope, process, and output. Every sentence adds value, and it is front-loaded with the main action. No unnecessary repetition or filler.

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

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

Given the lack of an output schema, the description adequately explains what is returned (top N ranked by edge magnitude with trade direction) and the scope (crypto-price bets using a lognormal model). It covers the process and data sources, making the tool understandable. Minor omission is the exact definition of 'edge', but overall sufficient.

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

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

All three parameters (limit, window, min_edge_pp) are fully described in the input schema. The description reiterates the concept of 'top N' and 'volume window' but does not add new parameter-specific information beyond what the schema provides, so the baseline score of 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 scans high-volume Polymarket markets and returns ones where Pipeworx data disagrees most with market price, ranking by edge magnitude with trade direction. It explicitly says it is built for the 'what should I bet on today' question, differentiating it 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 that the tool is for discovering betting opportunities without manual browsing, implying use for finding edges in crypto-price bets. However, it does not explicitly contrast with sibling tools or state when not to use it, leaving some ambiguity for agents.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the output format (leg-by-leg prices in 0-1, spread in percentage points) and the typical spread range (2-25pp). No contradictions with annotations.

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

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

The description is well-structured with sections for modes and output. It is comprehensive but slightly verbose. Every sentence adds value, though it could be tightened slightly without losing clarity.

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

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

Given no output schema, the description adequately explains return values and modes. It covers the tool's complexity (3 optional params, switchable modes). Minor gap: no mention of error handling or what happens if a topic/event is not found, but acceptable given openWorldHint.

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. The description adds context about the interaction between 'topic' and explicit tickers (overrides), and lists valid topic values. This enhances understanding 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on spread across two venues. The verb 'cross-venue spread' is specific and the resource is well-defined.

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 modes (topic shortcuts and explicit tickers) and when to use each. It also explains the rationale for the spread. However, it lacks an explicit statement about when not to use this tool (e.g., for non-matching questions) or direct comparisons 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?

No annotations provided, so description carries full burden. It clearly states the tool is for retrieval (non-destructive) and implies read-only behavior. However, it doesn't specify if listing all keys returns metadata or just keys, but this is a minor gap.

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

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

Two sentences, no fluff, key information front-loaded. Slightly verbose with the second sentence being somewhat redundant, but overall efficient.

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

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

Given simple schema and no output schema, description adequately explains what the tool does and when to use it. Could mention that it retrieves from a persistent memory store, but current version 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% and description adds minimal extra meaning beyond schema: it clarifies that omitting key lists all. Baseline 3 is appropriate as schema already documents parameter well.

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 retrieves a stored memory by key, or lists all memories if key is omitted. Verb 'retrieve' and resource 'memory' are specific, and it distinguishes from sibling tools like 'remember' and 'forget'.

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

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

Explicitly says to use key for specific retrieval or omit to list all. Also advises to use this tool to retrieve context saved earlier in the session or previous sessions, providing clear context for 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 full burden. It discloses parallel fan-out to SEC EDGAR, GDELT, USPTO, acceptable since formats (ISO or relative), and return structure (changes, count, URIs). It doesn't mention rate limits or auth requirements, but for a read 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 four sentences, each serving a purpose: core definition, fan-out details, since format, return structure, and use cases. No redundant information, effectively front-loaded.

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

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

Despite lacking an output schema, the description explains the return format (structured changes, count, URIs). It covers behavior for the only supported type and provides enough context for agents 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% with descriptions for all 3 parameters. The description adds value by providing examples for since ('30d', '1m') and clarifying acceptable inputs for value (ticker or CIK). This goes beyond the schema's bare 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 'What's new about an entity since a given point in time' and details the behavior for type='company' with parallel fan-out to multiple sources. It distinguishes from siblings like entity_profile (static) and compare_entities (comparison) by focusing on time-based changes.

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 provides use cases ('brief me on what happened with X', change-monitoring workflows) and gives examples of since values. It notes the limitation that only 'company' type is supported, but doesn't cover when not to use it or alternatives beyond implied 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?

With no annotations provided, the description carries full burden. It discloses persistence behavior (authenticated vs. anonymous) and storage duration (24 hours for anonymous). This adds valuable context beyond the input 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?

Two sentences: first states purpose, second gives usage guidance. No unnecessary words. Front-loaded with the core 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?

For a simple key-value store with 2 required params, full schema coverage, and no output schema needed, the description is complete. It covers purpose, usage, and behavioral differences across auth states.

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 examples for key ('subject_property', 'target_ticker') and value ('findings, addresses, preferences, notes'), which helps the agent choose appropriate 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?

The description clearly states the verb 'store' and resource 'key-value pair in your session memory'. It differentiates from siblings like 'recall' (retrieve) and 'forget' (delete) by specifying the write nature.

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 on when to use: 'save intermediate findings, user preferences, or context across tool calls'. It also distinguishes use cases between authenticated and anonymous sessions. However, it does not explicitly say when not to use or name alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is a read operation (resolving entities), returns specific fields (ticker, CIK, name, URIs), and is a single call. It does not mention side effects, rate limits, or auth, but for a lookup 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 two sentences, front-loaded with the main purpose. Every sentence provides necessary information without redundancy or fluff.

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

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

The tool has only two parameters with full schema coverage. The description explains the output despite no output schema, and clarifies the single-call efficiency. It could mention error behavior or URI format, but it is sufficiently complete for its simplicity.

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

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

The schema already has 100% coverage with descriptions for both parameters. The description adds value by listing concrete examples (AAPL, 0000320193, Apple) and explaining the type enum structure, which is 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 resolves an entity to canonical IDs, specifies the entity type (company) and input formats (ticker, CIK, name), and explains the output (canonical IDs and URIs). The name 'resolve_entity' matches the purpose, and the description differentiates from siblings by noting it replaces multiple lookup 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 explicitly says 'Replaces 2–3 lookup calls', guiding agents to use this single call instead of multiple. It also restricts usage to 'company' type in v1. However, it does not explicitly state when not to use or compare with sibling tools, but given sibling names, this tool is clearly distinct.

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 it calls ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds behavioral 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?

The description is three sentences with no fluff. It front-loads the purpose, then mechanism and use case. Every sentence serves a clear function, making it efficient and easy to scan.

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 four parameters and no output schema, the description adequately explains the output format and the tool's internals (calling ai_visibility_check). It could mention constraints like minimum entities but is otherwise complete for its purpose.

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 value by explaining the special treatment of the first entity as the 'subject' and the optional context parameter, which enhances understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the mechanism and output.

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

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

The description gives a concrete use case (competitive AI-marketing audits) and an example question. It implies when to use but does not explicitly state when not to use or mention alternatives, though the context of sibling tools provides some guidance.

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

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

With no annotations provided, the description carries full burden. It discloses the return values (verdict, extracted form, actual value with citation, percent delta) and the supported claim types and data sources. However, it does not mention potential errors, limitations beyond 'v1 supports...', or any side effects, which would be expected for a read-only 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 highly concise with three sentences, each adding value: purpose, scope, output details, and efficiency comparison. No wasted words, and key information is front-loaded. This is an excellent example of conciseness and structure.

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 only one parameter and no output schema, the description adequately explains the output format (verdict, extracted form, etc.) and scope. It covers the main use case well, though it omits error handling or edge cases. For this complexity, a score of 4 is reasonable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context beyond the schema by specifying the domain (company-financial claims) and providing examples. This is helpful but not extensive, so a score of 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's function: fact-checking natural-language claims against authoritative sources, specifically company-financial claims for public US companies. It defines the verb (fact-check), resource (claims), and scope (financial domain). However, it does not explicitly differentiate from sibling tools like compare_entities, which could be considered a minor gap.

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 when to use the tool (for financial claim verification) and highlights efficiency by replacing sequential agent calls. However, it lacks explicit guidance on when not to use it or alternatives (e.g., compare_entities for entity comparisons), leaving usage context partially implied.

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