flood

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: default model, API key handling (passed to Anthropic), return structure (per-model scores, confidence, signals, raw_response). 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?

Two sentences deliver complete information: first sentence covers purpose and default behavior, second adds API key nuance and return structure. No fluff, front-loaded with key details.

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

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

All parameters are documented with examples and purpose. The description explains default model, optional API key, and return format. For a probing tool with no output schema, this is comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful context beyond schema: explains default model for 'models' parameter, clarifies '_apiKey' is optional and passed directly to Anthropic, and notes 'context' helps disambiguate. This raises the 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?

Description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It specifies the action, resource, and output format, differentiating it from sibling tools like scan_competitor_ai_presence.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. optional API key usage. While it doesn't explicitly say when not to use, the specificity provides strong guidance; a slight mention of alternative tools would push it to 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the tool picks the right tool and fills arguments automatically, and returns a result. However, it lacks details on limitations (e.g., data source availability, error handling, rate limits) or output format, which are important for a tool with no output 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 front-loaded with the core purpose, followed by operational details and examples. Every sentence adds value: the first defines the tool, the second explains its automation, and the third gives practical examples. It is efficiently structured 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 complexity (a natural language query tool with automated backend processing), no annotations, and no output schema, the description is incomplete. It explains the input well but lacks information on what the output looks like (e.g., structured data, text summary) or potential constraints, which are critical for effective use.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value by emphasizing 'plain English' and 'natural language' for the question parameter, and provides concrete examples that illustrate the expected format and scope, enhancing understanding 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 the tool's purpose: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and distinguishes from siblings by emphasizing natural language input and automated tool selection, unlike sibling tools like 'get_flood_forecast' which are specific to certain data types.

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

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

The description provides explicit usage guidance: 'No need to browse tools or learn schemas — just describe what you need.' It contrasts with alternatives by indicating this tool handles tool selection automatically, and includes examples ('What is the US trade deficit with China?', etc.) to illustrate appropriate use cases.

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

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

The description adds significant behavioral context beyond annotations: it resolves the market, classifies the bet, fans out to appropriate packs, and returns an evidence packet with a market-vs-model comparison. This complements the readOnlyHint=true, openWorldHint=true, and destructiveHint=false 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 efficiently structured: first sentence states the core purpose, subsequent sentences add necessary detail about inputs, behavior, and use cases. Every sentence earns its place without redundancy.

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

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

Despite having no output schema, the description sufficiently explains the tool's return: an evidence packet plus a market-vs-model comparison. Given the complexity of resolving, classifying, and fanning out, the description provides complete context for an agent to understand what the tool does.

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: it explains that 'market' can be a slug, URL, or question text, and for 'depth' it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.' This 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 researches a Polymarket bet by pulling relevant Pipeworx data in one call, with a specific verb and resource. It distinguishes itself from sibling tools like ask_pipeworx by focusing solely on Polymarket bets, making its purpose 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?', or 'is there edge in this bet?'. It does not explicitly mention alternatives or when not to use, so a slightly lower score than 5 is appropriate.

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

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

Describes return values (paired data, resource URIs) and data sources (SEC EDGAR, FDA), but does not disclose side effects, authorization needs, or read-only nature. Since annotations are missing, description carries full burden; some behavioral gaps remain.

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 focused sentences with no redundancy. Purpose, entity types with examples, and value proposition are all presented efficiently.

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; description mentions 'paired data' and resource URIs but lacks detailed return structure. No mention of error handling or edge cases. Adequate for basic understanding but leaves gaps for full agent use.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra semantics by detailing the exact data fields for each entity type, going beyond the schema's enum and array 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?

Clearly states the tool compares 2-5 entities side by side in one call, with specific fields for company and drug types. Distinguishes from sequential agent calls, making its 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?

Provides clear when-to-use context by stating it replaces 8-15 sequential calls. Implicitly suggests use for multi-entity comparisons. Could explicitly mention when not to use, but guidance is strong.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (searching a tool catalog), what it returns (most relevant tools with names and descriptions), and when to use it. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some behavioral aspects uncovered.

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 appropriately sized and front-loaded: the first sentence states the core purpose, the second explains the return value, and the third provides crucial usage guidance. Every sentence earns its place with no wasted words, making it highly efficient for an AI agent.

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

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

Given the tool's moderate complexity (search functionality with 2 parameters), no annotations, and no output schema, the description does a good job of explaining purpose, usage, and returns. However, it doesn't describe the format of returned results (e.g., structured list vs. raw text) or potential errors, leaving some gaps in completeness.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (query and limit). The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining how the query is processed or providing additional examples. This meets the baseline of 3 when schema coverage is high.

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 with specific verbs ('Search the Pipeworx tool catalog') and resource ('tool catalog'), and explicitly distinguishes it from siblings by emphasizing it should be called 'FIRST when you have 500+ tools available', making it distinct from the two listed sibling tools (get_flood_forecast, get_river_discharge) which appear to be specific data retrieval tools rather than catalog search tools.

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

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

The description provides explicit usage guidelines: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This gives clear context about when to use this tool (large catalog scenarios) versus alternatives, though it doesn't name specific alternatives, the guidance is sufficiently directive for the agent.

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

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

No annotations provided, so description carries full burden. It discloses that the tool returns pipeworx:// citation URIs and that federal contracts are too slow to bundle. However, it does not mention any potential side effects or rate limits, though it is a read operation.

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 4 sentences, front-loaded with purpose, and every sentence adds value. No 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?

Given no output schema, the description covers the data types returned (SEC, XBRL, patents, news, LEI) and mentions URI format. It sufficiently informs an agent about the tool's scope, though the exact output structure is not detailed.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning beyond the schema by explaining value accepts ticker or CIK, and that names are not supported, directing users to resolve_entity. This clarifies parameter 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 returns a full profile of an entity across Pipeworx packs, enumerating specific data sources (SEC filings, XBRL financials, USPTO patents, GDELT news, LEI). It distinguishes from siblings by noting that federal contracts should use usa_recipient_profile instead.

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

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

The description explicitly mentions when to use (replaces 10–15 sequential calls) and when-not-to-use (federal contracts call usa_recipient_profile). It also provides input guidance: supports ticker or CIK, not names, and suggests resolve_entity first.

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 but only states the action ('Delete') without disclosing behavioral traits such as whether deletion is permanent, requires specific permissions, or has side effects. It adds minimal value beyond the basic action.

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, efficient sentence with zero waste, front-loading the core action. It is appropriately sized for a simple tool with one parameter.

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 deletion tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral implications (e.g., permanence, errors) and doesn't compensate for the missing structured data, leaving gaps in understanding.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter fully. The description adds no additional meaning beyond what the schema provides, such as examples or constraints, meeting the baseline for high coverage.

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

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

The description clearly states the verb ('Delete') and resource ('a stored memory by key'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'recall' or 'remember', but the action is specific enough to imply distinction.

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

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

No guidance is provided on when to use this tool versus alternatives like 'recall' (which likely retrieves memories) or 'remember' (which likely stores them). The description lacks context about prerequisites or exclusions, leaving usage unclear.

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 read-only, open-world, idempotent, non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown. This complements annotations well 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?

Three sentences, each carrying weight: first states purpose, second outlines process, third lists use cases. No filler, 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?

Given the tool's simplicity (2 params, no output schema, safe annotations), the description fully covers what the tool does, its output format, and practical applications. No gaps apparent.

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 largely mirrors schema. For 'url', schema says 'Full URL...' and description adds 'e.g. https://example.com or a specific landing page', which is slightly redundant. For 'max_links', both state default and max. No significant new meaning beyond schema.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, specifying the action (generate), resource (llms.txt), and outcome (indexable format). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

The description enumerates three explicit use cases: indexing a client's site, drafting for own project, and auditing competitor from an AI perspective. While no direct exclusions or alternatives are mentioned, the use cases provide clear context for when to invoke.

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 of behavioral disclosure. While it mentions what data is returned, it doesn't describe important behavioral aspects like whether this is a read-only operation, potential rate limits, authentication requirements, error conditions, or data freshness. For a forecasting tool with no annotation coverage, this leaves significant gaps.

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

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

The description is a single, efficient sentence that clearly states the tool's purpose. It's appropriately sized for a simple data retrieval tool and front-loads the key information. There's no wasted verbiage, though it could potentially be more structured for complex tools.

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 forecasting tool with 3 parameters and no output schema, the description provides basic purpose but lacks important context. It doesn't explain what format the forecast data returns, temporal resolution, confidence intervals, or how to interpret the discharge values. With no annotations and no output schema, the description should do more to help the agent understand what to expect.

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

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

The input schema has 100% description coverage, providing clear documentation for all three parameters. The description adds no parameter-specific information beyond what's in the schema. With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding but doesn't need to compensate for gaps.

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: 'Get a comprehensive flood forecast including river discharge, mean discharge, and max discharge for a location.' It specifies the verb ('Get'), resource ('flood forecast'), and key data elements. However, it doesn't explicitly differentiate from the sibling tool 'get_river_discharge' beyond mentioning 'comprehensive' flood forecast.

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 no guidance on when to use this tool versus the sibling 'get_river_discharge'. It doesn't mention any prerequisites, alternatives, or exclusions. The agent must infer usage from the tool name and description alone without explicit 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 the full burden of behavioral disclosure. It specifies the data source (Open-Meteo Flood API) and units (m³/s), which adds useful context beyond what the input schema provides. However, it doesn't describe important behavioral aspects like rate limits, authentication requirements, data freshness, or what the response format looks like.

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, efficient sentence that communicates the essential information without any wasted words. It's appropriately sized for this type of data retrieval tool and front-loads the key information (what it gets, what units, what API).

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 data retrieval tool with 3 parameters, 100% schema coverage, but no output schema and no annotations, the description is adequate but has clear gaps. It explains what data is retrieved but doesn't describe the response format, which is important since there's no output schema. The mention of the specific API source adds useful context.

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

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

The schema description coverage is 100%, so all parameters are well-documented in the schema. The description doesn't add any additional parameter semantics beyond what's already in the schema descriptions. It mentions 'geographic location' which aligns with the latitude/longitude parameters, but provides no new information about parameter usage or constraints.

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 specific action ('Get daily river discharge forecast'), resource ('river discharge forecast'), units ('m³/s'), and data source ('Open-Meteo Flood API'). It distinguishes from the sibling tool 'get_flood_forecast' by specifying it's for discharge data rather than general flood forecasting.

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 about when to use this tool (for river discharge forecasts at geographic locations), but doesn't explicitly state when NOT to use it or provide specific alternatives. The existence of a sibling tool 'get_flood_forecast' suggests there are related alternatives, but the description doesn't explain the distinction between 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?

With no annotations, the description carries full burden. It discloses rate limiting (5 per day) and a privacy guideline, but does not mention what happens after submission (e.g., confirmation or processing). For a low-risk feedback tool, this is adequate but not fully 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 two concise sentences, front-loaded with the action, and every sentence adds value. No wasted words.

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

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

For a simple feedback tool with no output schema, the description covers purpose, usage, rate limits, and a privacy guideline. It is complete and sufficient for correct invocation.

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

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

Schema coverage is 100% and the schema already explains each parameter well. The description adds general advice (be specific) but no additional semantic detail beyond the schema, so a baseline score of 3 applies.

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

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

The description clearly states 'Send feedback to the Pipeworx team' and enumerates specific use cases (bug reports, feature requests, etc.). This distinguishes it from sibling tools like ask_pipeworx or forget, which are for queries or memory operations.

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

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

It explicitly lists when to use (bug reports, feature requests, missing data, praise) and provides a constraint (not including end-user prompt). It does not directly contrast with alternatives, but among siblings, only this tool is for feedback, making the guidance clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the data is self-aggregating from CF analytics-engine, no PII, and cached for 5min-1h depending on window. This goes beyond annotations, though rate limits or error handling are not mentioned.

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 (~100 words) and front-loaded with the result. It uses a bullet-point list for use cases, making it scannable. Every sentence adds unique value, no filler.

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

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

Given one optional parameter, no output schema, and strong annotations, the description covers all necessary context: what is returned, how data is derived, privacy, and caching behavior. It is fully adequate for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100% with a description for the single parameter 'window' that explains the enum values. The description further adds meaning by interpreting shorter vs longer windows (hot vs steady-state), which enhances agent 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 that the tool returns 'top tools, top packs, and total call volume over a recent window'. It uses a specific verb ('returns') and clearly identifies the resource. No sibling tool performs this function, so it is well-distinguished.

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 three concrete use cases: discovering hot data sources, confirming canonical choices, and aligning with common agent needs. It does not explicitly list when not to use or alternative tools, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint and non-destructive. The description adds rich behavioral context: how it processes (walks child markets, extracts dates, sorts, reports violations) and the return format (market_a, market_b, gap_pp, suggested_trade). 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?

Three sentences, 100 words, front-loaded purpose, logical flow from concept to process to output. No extraneous text, every sentence earns its place.

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

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

Given one parameter and no output schema, the description fully covers input format, processing logic, and return structure. No gaps.

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

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

Schema coverage is 100% with a clear description of the 'event' parameter. The description adds value by explaining what the tool does with the parameter (walks child markets, extracts dates/thresholds). Exceeds baseline 3.

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

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

The description clearly states the tool's purpose: finding arbitrage via monotonicity violations in Polymarket events. It provides a specific verb ('Find') and resource ('arbitrage opportunities within a Polymarket event'), and distinguishes from siblings by unique logic.

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

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

It explicitly describes the condition for use: when an event has multiple 'by [date]' or 'by [threshold]' markets. It explains the rationale (monotonicity). However, it does not mention when to use alternative sibling tools like polymarket_edges, so not a perfect 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, destructiveHint. The description adds significant behavioral context: scanning top markets, grouping by asset, fetching price history once, using a lognormal model from FRED and coinpaprika, ranking by edge, and suggesting trade direction. 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 appropriately sized with front-loaded core action and sequential details. Each sentence adds value, but it is slightly verbose. Overall well-structured and 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?

No output schema exists, so the description should explain return values. It states returns top N ranked by edge with suggested direction, but lacks explicit output structure (e.g., fields like market name, edge, direction). Given complexity and annotations, more detail on output would be beneficial.

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 does not add explicit semantics for parameters beyond the schema; it mentions 'Top N' and default values which are already in schema. Implicit context helps but no added value.

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

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

The description clearly states the tool scans high-volume Polymarket markets, compares model probability to market price, and returns ranked opportunities. The verb 'Scan' and resource 'Polymarket markets' are specific, and the purpose distinguishes it from siblings like 'polymarket_arbitrage'.

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

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

The description explicitly states it's built for 'what should I bet on today' and helps agents discover opportunities without manual browsing. It mentions V1 covers crypto-price bets, implying scope, but does not explicitly state when not to use or list alternative 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond annotations: it explains the typical spread range (2-25pp), the arb signal nature, and the output format (leg-by-leg prices in probability 0-1, spread in percentage points). 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 structured with a clear opening, context about why the spread exists, and then two modes listed with examples. While thorough, it is slightly verbose but each sentence adds value. Could be tightened without losing information.

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

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

Given the tool has no output schema, the description compensates by detailing the return structure (leg-by-leg prices, spread). It covers both modes, example parameter values, and the range of the spread. Annotations cover safety. The description is complete for an experienced agent.

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

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

Schema coverage is 100%, giving baseline 3. The description significantly enhances meaning: it explains the purpose of the topic parameter (pre-mapped shortcuts) with explicit list, and that explicit tickers override topic-mapped sides. It also describes the output format, adding semantic 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific mention of why the spread exists (different participant pools) and two modes (topic shortcuts and explicit tickers). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on this cross-venue comparison.

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

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

The description explicitly details two usage modes: using predefined topic shortcuts (fed, btc, etc.) for quick matching, or explicit tickers for custom pairings. It explains when each mode is appropriate. However, it does not explicitly state when not to use this tool or name alternative tools, slightly reducing clarity.

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

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

With no annotations provided, the description carries the full burden. It explains the dual behavior (retrieve by key or list all) and mentions persistence across sessions, which is valuable. However, it doesn't disclose error handling, response format, or whether listing all memories might be resource-intensive for large datasets.

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 efficiently structured in two sentences: the first explains the dual functionality, and the second provides usage context. Every word contributes to understanding without redundancy, making it appropriately concise 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?

For a tool with no annotations and no output schema, the description covers basic functionality well but lacks details on return values, error cases, or performance considerations. It's adequate for simple use but could be more complete given the absence of structured metadata.

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 description adds meaningful context beyond the 100% schema coverage. While the schema documents that 'key' is optional for listing, the description clarifies the semantic choice: 'omit key to list all keys' and ties it to retrieving 'context you saved earlier.' This enhances understanding of parameter 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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete) by focusing on retrieval operations.

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 this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter to list all memories, giving clear usage 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, so description carries burden. It discloses parallel fan-out to SEC, GDELT, USPTO; date formats; and return structure (changes, count, URIs). Implies read-only operation. Lacks explicit readonly confirmation but sufficient.

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?

Five sentences, each adding essential information: purpose, sources, date formats, return fields, use cases. Front-loaded and no fluff.

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

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

No output schema, but description explains return fields (structured changes, count, URIs). Covers inputs, behavior, and outputs adequately for a 3-parameter 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 covers all 3 params (100% coverage). Description adds value by giving relative date examples ('7d','30d','1y') and typical monitoring window ('30d' or '1m'), and clarifying value as ticker or CIK. Augments schema descriptions.

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

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

Description clearly states 'What's new about an entity since a given point in time' and specifies entity type (company) with fan-out to three sources. This distinguishes it from siblings like entity_profile 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?

Explicitly suggests use cases: 'brief me on what happened with X' or change-monitoring workflows. Does not explicitly exclude other uses, but context is clear. Could mention alternatives for full 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?

With no annotations provided, the description carries the full burden and adds valuable behavioral context beyond basic functionality. It discloses persistence traits ('Authenticated users get persistent memory; anonymous sessions last 24 hours'), which are crucial for understanding data retention and session behavior, though it does not cover aspects like error handling or rate 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 appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the core purpose, and the second adds essential behavioral context without redundancy, making every sentence earn its place.

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

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

Given the tool's moderate complexity (storage with persistence rules), no annotations, and no output schema, the description is mostly complete. It covers purpose, usage, and key behavioral traits, but lacks details on return values or error cases, which would be beneficial for full contextual understanding.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with examples. The description does not add significant meaning beyond what the schema provides, such as explaining parameter interactions or constraints, meeting the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Store a key-value pair') and resource ('in your session memory'), distinguishing it from siblings like 'forget' (delete) and 'recall' (retrieve). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous and differentiated.

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

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

The description provides clear context for when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but does not explicitly state when not to use it or name alternatives. It implies usage for persistence needs but lacks explicit exclusions or comparisons to sibling tools like 'recall' for retrieval.

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

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

No annotations are provided, so the description carries full burden. It discloses the return values (ticker, CIK, company name, and resource URIs) and implies a read-only operation. Although it doesn't explicitly state non-destructiveness, the verb 'resolve' and absence of side-effect indicators make it reasonably transparent.

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

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

The description is extremely concise: two sentences front-loading the purpose and then providing key details. Every sentence adds value, and there is no redundant or extraneous 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?

For a straightforward tool with only two parameters and no output schema, the description covers the essential aspects: purpose, input constraints, and output contents. It could mention idempotency or error handling, but it is largely complete given the low complexity.

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

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

Schema description coverage is 100% with both parameters described. The description adds some context by grouping value formats and noting version limitations, but does not significantly enhance the parameter semantics beyond what the schema already 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's purpose: resolving an entity to canonical IDs across Pipeworx data sources in a single call. It specifies supported entity type ('company') and input formats (ticker, CIK, name), and distinguishes itself from siblings by highlighting it replaces 2–3 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 provides clear usage context: v1 supports only 'company' type, and it accepts ticker, CIK, or name. It indicates when to use this tool (for single-call entity resolution) and implies it's a consolidation tool, but lacks explicit when-not-to-use guidance or 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, idempotentHint, and openWorldHint, so the description doesn't need to repeat those. It adds value by describing the probing process, ranking, and return structure (score, confidence, signal density), which goes beyond annotations.

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

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

Four sentences, each adding value: purpose, mechanics, use case, output format. No fluff, well-structured 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?

Given the tool has 4 parameters, no output schema, and annotations cover safety, the description provides sufficient context: what it does, how it works, what it returns, and when to use. Minor omission: no mention of error handling or edge cases, but overall complete.

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

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

Schema description coverage is 100%, so the schema already documents all 4 parameters. The description does not add new meaning beyond what's in the schema, earning the baseline score of 3.

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

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

The description clearly states the purpose: compare AI visibility across multiple entities, using ai_visibility_check to probe each, then rank and surface most/least recognized. It distinguishes from the sibling 'ai_visibility_check' which is a single entity probe.

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

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

Explicitly states use case for competitive AI-marketing audits with an example query. Implicitly suggests when to use (multi-entity comparison) vs. the sibling tool for single entities. Lacks explicit 'when not to use', but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It details the return types (verdict, structured form, citation, delta) and the multi-step replacement benefit. It does not disclose any negative side effects, but the tool is inherently read-only and non-destructive. The description is sufficient for understanding behavior 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 two sentences, front-loaded with the core purpose. Every sentence adds critical information: scope, supported claims, output types, and efficiency benefit. 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 modest complexity (one parameter, no output schema), the description covers the return value (verdicts, citation, delta) and scope (company-financial, US public). It lacks mention of error handling or performance characteristics, but for a fact-checking tool with clear domain, it is sufficiently 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 for the single required parameter is 100%, so the baseline is 3. The description provides an example of valid claims (e.g., 'Apple's FY2024 revenue was $400 billion'), adding marginal value beyond the schema's type and description. No further detail about parameter constraints or format.

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 names the tool's action ('fact-check a natural-language claim'), specifies the resource ('authoritative sources' with concrete examples like SEC EDGAR + XBRL), and distinguishes it from siblings by noting it replaces several sequential agent calls. The scope is clearly limited to company-financial claims.

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 clearly states the supported domain ('company-financial claims (revenue / net income / cash for public US companies)'), effectively telling the agent when to use the tool. However, it does not explicitly mention when not to use it or point to alternative tools for different claim types, though siblings like compare_entities imply alternatives.

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