Oecd

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, signaling safe operation. The description adds valuable behavioral details: it calls external LLMs, returns per-model and combined views, and notes that Anthropic calls require a user-provided API key with direct payment. This enriches understanding 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 well-structured: it opens with the core action, then details default behavior, optional parameters, return format, and use cases. Every sentence adds value. It could be slightly more concise, but the organization is clear and front-loaded with the primary purpose.

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

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

Given that there is no output schema, the description compensates by specifying the return format (per-model fields and combined view). It also covers four use cases and explains parameter dependencies. While it omits error handling or rate limits, the coverage is sufficient for a probing tool with well-documented parameters and rich annotations.

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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context: it explains that 'models' defaults to workers-ai, that '_apiKey' is only required if 'anthropic' is in models, and that 'context' aids disambiguation. These additions provide practical guidance 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's function: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It uses specific verbs ('probe', 'score') and identifies the resource ('LLMs', 'business/brand/product/topic'). While not explicitly distinguishing from siblings, the unique combination of 'probe multiple LLMs' and 'visibility scoring' makes its purpose unmistakable.

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

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

The description provides clear guidance on when to use the tool, listing concrete use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains the default model and optional Anthropic integration with BYO key. However, it does not explicitly contrast with similar sibling tools (e.g., 'scan_competitor_ai_presence') or state when not to use it.

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

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

No annotations are provided, so description carries full burden. It discloses that Pipeworx picks the tool, fills arguments, and returns result. However, it does not mention potential limitations, side effects, or what happens if no data source is suitable.

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?

Very concise: two sentences plus examples. Purpose is front-loaded. Every sentence adds value. No waste.

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, description adequately covers functionality, delegation, and provides examples. Could specify return format but acceptable for a natural language query 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% with the 'question' parameter well-described. Description adds value by explaining to ask in 'plain English' and provides examples, enhancing understanding beyond 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 clearly states the tool's purpose: answering natural language questions using the best available data source. It includes specific verb (ask) and resource (question answered), and distinguishes from sibling tools by emphasizing no need to browse or learn schemas.

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: when you have a plain English question. It advises against browsing tools or schemas. Examples provide context. Lacks explicit when-not-to-use or alternatives, but sufficient for clear intent.

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 behavioral details beyond annotations: it explains the depth parameter ('quick = 2-3 evidence sources, thorough = full fan-out'), the fan-out process, and the output format (evidence packet + comparison). Annotations already mark it as read-only and non-destructive, which the description supports.

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 and front-loaded with the main action and input options. At 137 words, it is slightly verbose but every sentence adds value. Minor redundancy could be trimmed, but overall it effectively communicates the tool's functionality.

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 provides a high-level overview of the return value ('evidence packet plus a simple market-vs-model comparison') and explains the classification and fan-out process. However, it does not detail the exact return structure, which would be helpful. Given no output schema, this is acceptable.

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 covers both parameters fully (100% coverage). The description adds semantic value by explaining the depth enum: 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.' It also provides examples for the market parameter, clarifying the accepted formats.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the outputs (evidence packet and comparison). This distinguishes it from sibling tools like ask_pipeworx 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?

The description explicitly provides usage scenarios: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?". It also contrasts with manual discovery: 'agents that get bet-relevant context here convert better than ones that have to discover the packs themselves.'

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 returns paired data and resource URIs but does not mention authorization, rate limits, or potential side effects. Behavior is adequately described for a comparison tool, but lacks depth.

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 efficiently convey purpose, data details, and benefit. No wasted words, front-loaded with core 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 no output schema, the description covers return values ('paired data + pipeworx:// resource URIs') and differentiates the two entity types. It does not explain error handling or edge cases, but is sufficient for a well-defined comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying that for company type, values should be tickers/CIKs, and for drug type, names. This clarifies the schema's enum and array descriptions beyond the schema itself.

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 ('Compare') and resource ('entities'), clearly distinguishes two entity types with concrete data examples, and states it replaces 8–15 sequential calls, making its purpose and efficiency benefit explicit.

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 explains when to use the tool (for side-by-side comparison of 2–5 entities) and implies that for single entities or other tasks, different tools like ask_pipeworx would be appropriate. However, it does not explicitly list exclusions or 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 must fully disclose behavior. It only states it returns tool names and descriptions, missing details like read-only nature, rate limits, or response specifics.

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 with an example, front-loaded with the main action. 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?

Simple tool with only 2 parameters, schema covers all. Description mentions return format (names and descriptions) and includes usage context, though output schema missing 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 coverage is 100%, so baseline is 3. Description adds example queries but doesn't enhance parameter meaning beyond the schema's descriptions of query and limit.

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 'Search the Pipeworx tool catalog by describing what you need.' and provides examples, distinguishing it from sibling tools like search_dataflows or ask_pipeworx by specifying it's for finding tools among many.

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

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

Explicitly advises 'Call this FIRST when you have 500+ tools available and need to find the right ones,' giving clear context for use. Could be stronger if it mentioned when not to use, but sufficient.

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

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

Without annotations, the description carries the full burden. It lists data sources and mentions returning pipeworx:// citation URIs. However, it does not cover error conditions, rate limits, or what happens if the entity is not found. The replacement of multiple calls implies efficiency but lacks details on typical response time or pagination.

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 ~twelve sentences, front-loading the core purpose. It efficiently lists data types, return format, efficiency gain, and an exclusion case. Every sentence adds value with 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 the tool's complexity (multiple data sources) and lack of output schema, the description sufficiently covers inputs, return format (citation URIs), and scope. Minor omissions include absence of performance characteristics or handling of missing data, but overall it provides enough for an agent to decide on usage.

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

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

Schema coverage is 100%, and the description adds meaningful context: it restricts type to only 'company', clarifies value as ticker or CIK, explicitly states names are not supported, and advises using resolve_entity as a fallback. This guidance significantly enhances 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 explicitly states it returns a full profile of an entity across all relevant Pipeworx packs, listing specific data sources (SEC filings, XBRL financials, patents, news, LEI) for company type. It distinguishes itself from siblings like resolve_entity and compare_entities by being a single-call comprehensive 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?

It clearly specifies when to use this tool versus alternatives: it replaces 10-15 sequential calls, and for federal contracts it directs to usa_recipient_profile. It also advises using resolve_entity first if only a name is available, providing clear prerequisites and exclusion criteria.

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, but description discloses return type (labeled rows), result-size limits, and truncation behavior. Describes conservative behavior needed (narrow queries). No annotation 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?

Compact yet comprehensive. Single paragraph front-loads purpose, then sequentially covers examples, key format, periods, return type, and limitation. 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?

No output schema, but description notes returns 'labeled rows' and warns about truncation. Covers usage, parameters, and limitations. Slightly unclear on exact output structure, but adequate for a fetch 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%, but description adds significant value: examples for flow_ref and key format, explains period formats, and links parameter usage to quota limits. Baseline 3 exceeded.

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

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

Clearly states it fetches tidy rows from OECD dataflows, with concrete examples of flow_ref and key string. Distinguishes from siblings like search_dataflows (search vs fetch) and list_curated_flows (list vs fetch).

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 examples for start/end period formats and advises narrowing queries to avoid truncation. Implicitly tells when to use (when data rows are needed) and when to avoid (broad queries). Could explicitly state 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 provided; the description only states 'delete' without disclosing if deletion is permanent, reversible, or any side effects. For a destructive tool, more transparency is expected.

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

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

Single sentence, no wasted words. Front-loaded with action and resource. Could be slightly more informative without harming conciseness, but acceptable.

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 one-parameter deletion tool, the description covers the core functionality. However, missing details like return value, idempotency, or error behavior leaves some 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% (one param 'key' with description). The tool description adds no extra 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 'Delete a stored memory by key.' uses a specific verb 'delete' and resource 'stored memory', clearly distinguishing from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

No guidance on when to use this tool versus alternatives (e.g., when to delete vs. just forget? when to use remember instead?). The description is too brief to provide 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 indicate safe, open-world, idempotent behavior. The description adds process details (fetches page, extracts title/description/key links, emits standard markdown) and output target, providing good behavioral disclosure beyond annotations.

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

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

The description is concise, front-loaded with the main 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?

Despite no output schema, the description explains the output format (single text blob, markdown, location site-root/llms.txt). The tool is simple with 2 parameters, and all aspects are covered.

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

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

Schema coverage is 100%, so the description adds no new parameter meaning beyond what the schema already provides. It implicitly references 'key links' related to max_links, but no additional semantics.

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

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

The description clearly states the tool generates an llms.txt file for any URL, using specific verb and resource. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence, which focus on checking AI visibility rather than 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?

It provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) and implies context for when to use via sibling tool names. No explicit when-not-to-use, but the context is sufficient.

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

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

No annotations provided. Description implies it's a read-only listing but does not explicitly state behavioral traits like non-destructiveness, caching, or error handling. Adequate for a simple list 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?

Two concise sentences with front-loaded purpose. Every sentence adds value; no redundant or missing 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?

Fully sufficient for a simple list tool with one optional parameter and no output schema. Provides usage context and alternatives.

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 already describes 'topic' as optional. Description adds no additional semantic information beyond the schema. Baseline 3 due to full 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?

Describes listing pre-vetted OECD dataflow refs grouped by specific topics (gdp, labour, etc.). Clearly distinguishes from siblings like search_dataflows and fetch_dataset.

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 this tool (for pre-vetted OECD dataflows) and directs to alternatives (search_dataflows, website) for other needs.

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 exist, so description carries full burden. Discloses rate limit (5 per identifier per day) and that it's free. Does not detail internal behavior, but for a feedback submission tool, this is 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?

Three sentences, each purposeful: states purpose, provides usage guidance, and mentions rate limit. No redundancy, front-loaded with key 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 simple feedback tool without output schema, the description covers purpose, how to use, what to include, and constraints. Complete given the tool's 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 coverage is 100% (detailed enum and field descriptions). Description adds value by instructing on message content specifics, which goes beyond schema. Thus above 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?

Clearly states the tool sends feedback to Pipeworx team. Lists specific use cases (bug reports, feature requests, missing data, praise) and distinguishes it from sibling tools which are other utilities like ask or fetch.

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

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

Explicitly says when to use (bug reports, etc.) and provides specific guidance on how to write feedback (describe in terms of Pipeworx tools/data, no end-user prompt verbatim). Mentions rate limit but does not provide when-not-to-use or alternatives, which are not critical given the tool's focused purpose.

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 cover read-only, idempotent, non-destructive. Description adds valuable context: derived from CF analytics-engine, no PII, caching behavior (5min-1h). Fills gaps beyond annotations.

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

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

Concise, front-loaded with the main action. Every sentence adds value without redundancy. 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?

Tool is simple with one optional parameter and no output schema. Description covers purpose, use cases, data source, privacy, caching. Complete and self-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% with good description for the single 'window' parameter. Description further clarifies that shorter windows show hot trends, longer show steady-state demand, adding 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?

Description clearly states the tool returns top tools, packs, and call volume over a recent window. It distinguishes itself from sibling tools like discover_tools by focusing on trending/call volume data.

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

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

Provides three explicit use cases (discovering hot sources, confirming canonical tools, checking alignment). Also explains window choice for short-term vs. long-term trends. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining the logic (monotonicity checks) and the two modes. It does not contradict annotations and provides additional behavioral context beyond what annotations offer.

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

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

The description is concise and well-structured, using bullet points for modes and front-loading the core purpose. Every sentence 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?

Despite having no output schema, the description explains the return value (ranked opportunities with trade direction and reasoning). It covers both modes and their rationale, providing sufficient context for an agent to use the tool effectively.

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 significant extra context by explaining the two modes and how each parameter is used (e.g., topic mode searches across events), which improves the agent's 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 finds arbitrage opportunities by checking monotonicity violations, and it explicitly distinguishes two modes (event vs topic), making it easy for an agent to understand what the tool does and how it differs from siblings like polymarket_edges.

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

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

The description explains when to use each mode: event mode for single-event checks, topic mode for cross-event searches. It provides an example of when cross-event mode is necessary, giving clear context for selecting the correct mode, though it does not explicitly state when not to use the 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?

The description goes beyond the annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) by detailing the internal process: scanning top markets, grouping by asset, fetching price history once, computing model probability using a lognormal model from FRED and live coinpaprika price, ranking by edge magnitude, and returning top N with suggested trade direction. This provides rich behavioral context without contradicting annotations.

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

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

The description is efficient and well-structured. It starts with the main action, then provides necessary details on the underlying model and method, and ends with the intended use case. Every sentence contributes value, and the length is appropriate for the complexity of the tool.

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 adequately covers inputs (three parameters with defaults), process (data sources, model, ranking), and output (top N ranked by edge magnitude with trade direction). This is sufficient for an agent to understand and invoke the tool 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?

The input schema covers all three parameters with descriptions (limit, window, min_edge_pp), so the baseline is 3. The tool description reinforces these parameters but does not add new semantic meaning beyond what is in the schema. For example, it mentions 'returns top N' but doesn't elaborate on parameter behavior beyond the schema's defaults and ranges.

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: 'Scan the highest-volume Polymarket markets and return the ones where Pipeworx data disagrees most with the market price.' It identifies a specific verb (scan/return), resource (Polymarket markets), and unique approach (disagreement with Pipeworx data). It also distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on Pipeworx-based edge detection.

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 it's built for the 'what should I bet on today' question, indicating when to use the tool. It also notes it helps discover opportunities without manual paging. However, it does not explicitly compare with alternatives like 'bet_research' or 'polymarket_arbitrage', nor does it state when not to use it. This is a minor gap, 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?

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior. The description adds useful context: it explains that the tool returns real-time prices and spreads, and details the two operational modes. No contradiction with annotations; the description enriches understanding beyond the structured hints.

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

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

The description is concise and well-structured: it opens with the core purpose, then explains the two modes, and finally describes the output. Every sentence adds value without repetition or fluff. It is appropriately sized for the tool's complexity.

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

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

Given that there is no output schema, the description fully explains what the tool returns (prices, spreads, probability range). It also covers both usage modes and override behavior. The annotations handle safety concerns, making the description complete for an agent to correctly invoke the tool.

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

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

The input schema already covers all three parameters with descriptions, achieving 100% coverage. The tool description adds meaning by explaining the two-mode semantics: giving a topic uses pre-mapped shortcuts, while explicit tickers override the mapping. This context goes beyond the schema's basic parameter 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 spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes and the output format. However, it does not explicitly differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edges', which may reduce clarity for an agent choosing among them.

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 how to use the tool with two distinct modes (topic shortcuts or explicit tickers), including examples of topics and ticker formats. It implies usage for arbitrage by noting the delta is a real arb signal, but does not explicitly state when not to use it or provide comparisons to alternative tools, leaving some ambiguity.

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

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

No annotations are provided, so the description must convey behavioral traits. It explains the two modes (single retrieval vs listing) but does not disclose whether the operation is idempotent, has side effects, or how errors (e.g., missing key) are handled. This is adequate but not thorough.

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

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

The description consists of two concise sentences that front-load the core functionality. Every phrase is informative, and there is no unnecessary text.

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

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

Given the tool has a single optional parameter and no output schema, the description covers both usage modes adequately. It could mention return format or behavior for nonexistent keys, but overall it is sufficient 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?

Schema description coverage is 100% (the only parameter 'key' is described). The description adds 'Memory key to retrieve (omit to list all keys)', which reinforces the schema but does not add significant new semantic detail. 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 specifies 'retrieve a previously stored memory by key, or list all stored memories (omit key)', which states the verb and resource distinctively. Among siblings 'remember' and 'forget', this tool is uniquely for retrieval.

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 advises using this tool to retrieve context saved earlier, providing context. It does not explicitly mention when not to use it or suggest alternatives like 'remember' for storage, but the guidance is clear enough for basic 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?

No annotations provided, so description carries full burden. Discloses parallel fan-out sources, since parameter format, and return structure (changes, count, URIs). Lacks explicit read-only hint or rate limits, but adequately informs about behavior.

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

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

Three sentences, front-loaded with main purpose. Every sentence adds value—no filler. Efficient and well-structured.

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

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

With no output schema, description adequately covers return format and sources. Input parameters fully explained. Slight gap: no mention of pagination or error handling, but sufficient for typical agent 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%, but description adds meaningful context: explains since format with examples, notes type is limited to 'company', and gives value examples (ticker, CIK). Goes beyond schema by describing return structure.

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

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

The description uses specific verbs and resources: 'What's new about an entity since a given point in time' and details fan-out to SEC EDGAR, GDELT, USPTO. It clearly distinguishes from siblings like entity_profile and compare_entities by targeting change-monitoring workflows.

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

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

Explicitly states use cases: 'brief me on what happened with X' or change-monitoring workflows. Does not provide explicit exclusions, but context with sibling tools makes alternatives 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?

Discloses session memory and persistence based on authentication, but does not mention overwrite behavior or side effects. Since no annotations exist, description carries burden but is adequate for a simple KV store.

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

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

Two concise sentences, front-loaded with purpose, but could be slightly more structured. 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?

Covers purpose, usage examples, and persistence. Lacks mention of return value, but for a simple store operation, this is acceptable given no output schema is required.

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

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

Schema has 100% coverage with good descriptions for both parameters. The description adds minimal value beyond the schema, thus 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?

Describes the tool as storing a key-value pair in session memory, which is specific and distinguishes it from siblings like 'forget' and 'recall'.

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 concrete examples of when to use (save findings, preferences, context) and mentions persistence differences, but lacks explicit exclusions for 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 the return type (IDs and pipeworx:// URIs) and implies a read-only operation via 'resolve'. While it does not explicitly state that no data is modified, the description is sufficiently transparent about the tool's behavior for a resolution tool.

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

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

The description is concise with only three sentences: the first states the core purpose, the second elaborates on supported types, and the third notes the output and benefit. Every sentence earns its place, and it is efficiently structured.

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

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

Given the tool's simplicity (2 parameters, no annotations, no output schema), the description covers the input types and output adequately. It explains what the tool does and what it returns. However, it does not describe the output format in detail or mention any pagination or error conditions, which may be acceptable for a simple lookup tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by providing concrete examples of values for each type (e.g., ticker, CIK, name for company; brand or generic name for drug) and explaining what each type resolves to (SEC EDGAR identity vs RxCUI + ingredient + brand). This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves entities to canonical IDs across data sources, explicitly lists two entity types (company and drug) with their mappings, and mentions returning IDs and URIs. The verb 'resolve' is specific and the purpose is unambiguous, though it does not directly differentiate from the sibling 'compare_entities', but that is irrelevant for purpose clarity.

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 on when to use the tool (to get canonical IDs for company or drug entities) and even notes that it replaces 2-3 lookup calls, implying efficiency. However, it does not explicitly state when not to use it or what alternatives exist (e.g., compare_entities for comparing entities instead of resolving).

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds specifics: probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, and returns score/confidence/signal density. No contradiction with annotations.

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

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

Three sentences: purpose, process, use case + return type. No redundant 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?

Covers input, process, and output adequately without an output schema. Mentions return format. Lacks explicit note on entity count validation (schema says 2-8), but overall complete for intended 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%, but description adds meaning by explaining that entities include a subject and competitors, and that models/anthropic key are optional. It also describes the return data (score, confidence, signal density), enriching parameter understanding.

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

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

The description states the tool compares AI visibility across multiple entities side-by-side, with clear verb ('compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying competitive audit context.

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 suggests use for competitive AI-marketing audits and provides a concrete example question. It implicitly differentiates from single-entity checks, but does not explicitly state when not to use or list alternatives.

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

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

Beyond readOnly/idempotent annotations, the description discloses fan-out to two services, timing for bundlephobia (5-30s), and graceful degradation with sources_failed list. 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?

Single paragraph but well-organized: purpose first, usage, return fields, ecosystem caveat, error handling. Could be broken into sections but still concise and informative.

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

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

Given no output schema, the description thoroughly explains the return shape (summary fields, per-advisory detail, links, alternative versions) and edge cases (timeout, NPM-only). Covers all necessary context.

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

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

Schema already describes both parameters fully (100% coverage). Description adds context on scoped packages and default version behavior, but schema already does most of the work.

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 composite check for npm packages, uses a specific verb-resource structure ('should I add this npm package...'), and distinguishes from alternatives by noting the NPM-only scope and directing to deps.dev:version for other ecosystems.

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 'Use whenever an agent asks...' and provides when-not-to-use guidance for non-NPM ecosystems, pointing to deps.dev:version directly. Also mentions graceful partial failures.

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 describes the read-only search behavior and output format, but does not disclose pagination details or any limitations beyond what is in the schema. Adds refinement advice but lacks depth.

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: purpose, output and downstream use, and refinement advice. No wasted words; each sentence serves a distinct, valuable purpose. 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?

Covers key aspects: what it does, what it returns (dataflow refs for fetch_dataset), and how to refine queries. Missing output schema details, but implied by the downstream tool reference. Adequate for a search tool with good parameter descriptions.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining the query matches names and descriptions and suggesting refinement, but this is more usage guidance than additional semantic clarity. Meets baseline but does not significantly exceed it.

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 searches the OECD's SDMX dataflow registry by keyword and returns matching dataflow refs. It distinguishes from siblings by explicitly linking the output to fetch_dataset.

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: refine with more specific keyword or restrict by agency if results are noisy. Implicitly suggests using before fetch_dataset, but does not explicitly state when not to use or list alternatives.

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

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

Discloses use of SEC EDGAR + XBRL, return types (verdict, structured form, actual value with citation, delta), and that it replaces multiple agent calls. No annotations, so description carries full burden; covers key behavioral aspects.

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?

3 sentences, front-loaded with main purpose, no redundant info. Efficient and well-structured.

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

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

Given single parameter and no output schema, description sufficiently covers what the tool does and what it returns (verdict types, citation, delta). Complete for this 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?

Single parameter 'claim' has clear schema description; tool description adds domain and example, enhancing understanding beyond schema. Schema coverage 100%, so baseline 3, description adds 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?

Clearly states the tool fact-checks natural-language claims against authoritative sources, specifies domain (company-financial claims for public US companies), and lists verdict types. 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?

Specifies supported claim types (revenue/net income/cash) and scope, implying when to use. Lacks explicit when-not-to-use or alternatives, but context is clear.

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