Pub Dev

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

The description discloses key behavioral traits beyond annotations: it probes LLMs (cost implications for Anthropic), returns structured per-model data, and explains the default free model. Annotations already indicate read-only, idempotent, open-world, so description adds value 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 four sentences with no fluff. The main purpose is stated first, followed by essential details on models, API key, and return format. Every sentence contributes meaning.

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 moderate complexity, the description adequately covers what the tool does, what it returns (per-model and combined), and when to use it. No gaps for an audit/monitoring 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 explaining the default model and the cost implication of the _apiKey parameter, and the combined return view. This enriches understanding beyond 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 that this tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the resource (LLMs), the action (probe and score), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multiple models and scoring.

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 contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use or compare to alternatives, but the context is strong enough to guide appropriate 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?

The description adds behavioral context beyond annotations by mentioning routing to 3,336 tools, filling arguments, and returning structured answers with citation URIs. It complements the readOnlyHint, openWorldHint, and idempotentHint annotations well.

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

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

The description is well-structured with a front-loaded key instruction, followed by elaboration and examples. It is informative without being excessively long, though it could be slightly more concise.

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

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

Given the complexity of the tool (6 parameters, many possible queries), the description covers purpose, scope, output format, and examples. It lacks comparison with sibling tools but is otherwise 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?

The schema covers all parameters with descriptions, achieving 100% coverage. The description adds context about routing and argument filling, but does not significantly enhance parameter 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 that the tool is for answering factual questions using authoritative structured data with citations, and explicitly prefers it over web search. It lists many domains and example queries, effectively distinguishing it from siblings.

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 extensive guidelines on when to use the tool, including specific domains and example query starters. It lacks explicit exclusion of scenarios where sibling tools might be better, but still offers clear 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 indicate readOnlyHint=true, openWorldHint=true, etc. The description goes far beyond, detailing resolver confidence (high/medium/low/none), parent_event extraction with peer prices, news fallback handling, safety short-circuits for low confidence and closed markets, and spread illiquidity warnings. No contradiction with annotations.

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

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

The description is dense and information-rich, with a logical flow: purpose, classifiers, fan-outs, response shapes, then behavioral details. It is long but every sentence adds value. Could benefit from clearer section headers, but remains 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, the description fully explains the output structure: market fields (bid/ask/spread/liquidity), analysis (model probability/edge/kelly), evidence keyed by source, resolver contract (confidence, alternatives, suggestions), parent_event fields, news metadata, and safety statuses. Sufficient for an agent to understand response shape.

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% for all three parameters. Description does not add significant detail beyond the schema, but provides examples for the 'market' parameter. 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: 'Research a Polymarket bet' by pulling relevant Pipeworx data. It specifies input variations (slug, URL, or question text) and output (evidence packet + comparison). It distinguishes from sibling tools focused on edges or 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?

Explicitly provides usage cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Includes numerous fan-out examples by classifier, and warns when results should not be trusted (low confidence, closed markets).

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 (readOnlyHint, openWorldHint, idempotentHint) indicate safety and recent data. Description adds critical details: for companies, pulls latest 10-K from SEC EDGAR/XBRL with fiscal year handling; for drugs, pulls FAERS, FDA approvals, trial counts; returns paired data with citation URIs, sorted by primary metric. 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?

Two paragraphs, ~6 sentences, front-loaded with usage guidance followed by technical details. Every sentence adds value without redundancy.

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

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

No output schema, but description explains return format (paired data, citation URIs, sorted by primary metric). Covers both entity types comprehensively. Could mention error handling or rate limits but acceptable given complexity.

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

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

Schema covers both parameters (type enum, values array) with descriptions. Description adds context for each type's data source and input format (tickers/CIKs for company, drug names for drug), enhancing understanding 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?

Clearly states the tool compares 2-5 companies or drugs side by side, specifying the verb 'compare' and the resources (companies/drugs). It distinguishes from siblings by noting it replaces 8-15 sequential lookups, implying a consolidated view not available in single-entity tools like entity_profile.

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

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

Explicitly identifies use cases: 'compare X and Y', 'X vs Y', 'which is bigger', or rank-by-metric questions. Mentions efficiency over multiple lookups but lacks explicit when-not-to-use or alternative tool recommendations.

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, idempotent, non-destructive. The description adds valuable behavioral context: returns top-N results with full schemas and examples, ready to call directly, beyond what annotations provide.

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

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

Two sentences, no wasted words. The first sentence states purpose clearly, the second explains usage and output, prioritizing 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?

Given 6 parameters (5 aliases), no output schema, and 20 siblings, the description adequately covers input, purpose, and behavior. It explains return value (top-N tools with schemas) and suggests when to call, though it could mention output format more explicitly.

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 does not add significant meaning beyond explaining the query as natural language and limiting results; it implicitly references the limit parameter but provides no extra syntax 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 it finds tools by describing data or task, enumerates specific domains (SEC filings, FDA drugs, etc.), and distinguishes itself by being the first call to discover the option set.

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: when browsing, searching, or discovering tools, and explicitly advises calling it first. 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?

Adds rich context beyond annotations: details on APIs used, patent deprecation, news fallback, and return format. Annotations already indicate safe read, no contradiction.

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

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

Well-structured and front-loaded, but slightly verbose with minor details like 'Run 6 fix'. Still efficient and clear.

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

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

Covers all return fields, limitations, and alternatives. No output schema exists, so description fully compensates.

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?

Describes both parameters with specific examples and constraints (e.g., zero-padded CIK, no names). Schema coverage is 100%, description adds valuable usage hints.

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 gets everything about a US public company in one call, and distinguishes itself from siblings by noting it replaces calling 10+ pack 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?

Explicitly says when to use (e.g., 'tell me about X') and when not (names not supported, use resolve_entity first). Also mentions patent soft-fail.

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 destructiveHint=true and idempotentHint=true. The description adds useful context about clearing sensitive data and stale context, but does not reveal additional behavioral traits 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?

Three sentences with no fluff: first defines action, second gives usage scenarios, third mentions related tools. Front-loaded and efficient.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description is complete. It covers purpose, when to use, and related tools.

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

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

Schema coverage is 100%, so the parameter 'key' is already fully described in the schema. The description adds minimal value beyond mentioning 'by key'. 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 action ('delete'), the resource ('memory'), and the specificity ('by key'). It distinguishes from sibling tools 'remember' 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?

Explicitly lists when to use (context stale, task done, clear sensitive data) and mentions pairing with 'remember' and 'recall', providing clear guidance on alternatives and 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?

Description details fetching, extraction, and output format, adding behavioral context beyond annotations. No contradictions; annotations (readOnlyHint, idempotentHint) are consistent. Minor gap: no mention of rate limits or site restrictions.

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 plus a bullet list of use cases. No redundancy, every part adds value. Front-loaded with core purpose, then process, then examples.

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 2 parameters and no output schema, the description fully covers what the tool does, what it outputs (text blob), and why it's useful. No missing aspects 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 coverage is 100%; description adds default and max for max_links parameter. The parameter descriptions in the schema are already clear, but the tool description provides context on the output, enhancing 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 clearly states the tool's purpose: generating an llms.txt file for URL indexing by AI crawlers. It includes specific actions (fetch, extract, emit) and distinguishes itself from sibling tools by its unique function.

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

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

Provides explicit use cases (client site indexing, personal project drafting, competitor auditing). Lacks explicit when-not-to-use or alternatives, but the clarity of contexts compensates.

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

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

Annotations indicate non-readonly and non-destructive, and the description adds key behavioral details: it's free, does not count against tool-call quota, and is rate-limited to 5 per identifier per day. No contradictions with annotations.

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

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

The description is well-structured and concise. It starts with the core purpose, then provides usage guidelines, and ends with behavioral notes. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately covers what to expect: rate limits, free usage, and the type of feedback. It is complete for a feedback submission 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 provides good descriptions for all parameters (100% coverage). The description adds value by explaining enum values and the context object further, but it does not introduce major new semantic meaning 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 is for providing feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools like 'ask_pipeworx' by specifying its unique purpose.

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 outlines when to use each feedback type (bug, feature, data_gap, praise) and provides a clear directive: 'don't paste the end-user's prompt.' It also mentions rate limits and that the call doesn't count against quota.

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 safe, read-only, idempotent behavior. Description adds useful context: aggregation source, no PII, caching details (5min-1h). No contradiction.

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

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

Single paragraph efficiently packs purpose, use cases, and behavioral details. Could be slightly more structured but remains readable and free of 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 (1 param, no output schema), and description covers all necessary aspects: purpose, usage, behavioral traits, and caching. Annotations fully cover safety. 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 provides full enum coverage, and description adds semantics by explaining the windows ('hot right now' vs 'steady-state demand'), adding 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?

Clearly states it returns top tools, packs, and call volume over windows. Provides three specific use cases that distinguish it from sibling tools like discover_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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment). Could be improved by explicitly stating when not to use, 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.

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

The description discloses extensive behavioral details beyond annotations: two modes, partition check tolerances (3pp), semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs), and response structure. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with read-only, open-world behavior.

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

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

The description is front-loaded with the main purpose and is well-structured with clear sections. While it includes many technical details, every sentence adds value given the tool's complexity. Minor redundancy exists but does not detract.

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

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

Given the tool's complexity (two modes, multiple checks, response format) and no output schema, the description is remarkably complete. It covers edge cases (placeholders, low similarity), response structure (opportunities[], partition_check{}), and failure conditions (null arb signal).

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning by defining the two modes, providing examples, and explaining the different behavior for event vs topic parameters, going 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific mechanisms, making the purpose concrete and differentiating from sibling tools like polymarket_edges.

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

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

The description explicitly outlines two modes with guidance on when to use each: event mode for a single event slug, and topic mode for cross-event patterns that single-event misses. It does not directly contrast with siblings, but the context is sufficient for correct selection.

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

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

The annotations already provide readOnlyHint and idempotentHint, but the description adds significant behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), data sources (FRED, GDELT), segment-specific algorithms (lognormal barrier, partition_overround), and output diagnostics so callers can see why a segment is empty. This transparency greatly aids agent decision-making.

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 long but well-structured with section breaks (segments, output fields, knobs). Every sentence adds value given the tool's complexity. It is front-loaded with the main purpose. While slightly dense, it is appropriately sized for a tool with 9 parameters and three distinct segments.

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?

There is no output schema, but the description details the response structure (by_segment, fed_candidates, diagnostics) and lists key fields (edge_pp_net, kelly_fraction, market fields). It explains edge calculation and slippage. However, it could be more explicit about exact field names and types in the response, which would make it fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the conceptual purpose of parameters like min_partition_leg_kelly (applies to per-leg Kelly, not parent level) and min_kelly (filters single-leg opportunities). It clarifies how parameters interact with different segments, which is not evident from 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 clearly states the tool's action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes this tool from siblings by focusing on Pipeworx disagreement and providing a unique output structure with three segments. The phrase 'Built for "what should I bet on today"' clarifies the use case.

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: it is for discovering opportunities without paging hundreds of markets. It details the three segments and tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) to filter opportunities. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage, which would make the guidance stronger.

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, openWorldHint, idempotentHint, and destructiveHint false, so the tool is safe and stateless. The description adds significant behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for skipped comparisons. This goes well beyond annotations and prepares the agent for nuanced outputs.

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

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

The description is concise yet thorough: starts with purpose, then explains modes, then response structure, then safety fields. Every sentence adds value without redundancy. It uses bold for key terms and clear structure, making it easy for an agent to parse and understand.

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 3 optional params, no output schema, and complexity of cross-venue spreads, the description covers input modes, response fields (leg-by-leg prices, spreads, safety warnings), and edge cases (compatibility_warning conditions). There are no gaps as the tool is self-contained and the response is sufficiently described.

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 descriptions for each parameter. The description adds context by explaining that the 'topic' parameter auto-fetches matching events and that explicit ticker/slug override the topic-mapped sides. This clarifies the relationship between parameters and provides usage nuance 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 starts with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This is a specific verb ('computes spread') and resource ('cross-venue between two specific platforms'), clearly distinguishing it from sibling tools like 'polymarket_arbitrage' or 'polymarket_edges' which likely focus on single-venue 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?

It explicitly describes two modes ('topic' and explicit ticker/slug) and when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'), guiding the agent to interpret results cautiously. No explicit when-not-to-use or alternative tool references, 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds useful context about scoping (anonymous IP, key hash, account ID) and pairing behavior, going beyond annotations without contradiction.

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

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

The description is concise with three sentences that front-load the main purpose, then provide usage context and pairing. Every sentence adds value without redundancy.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description fully covers purpose, usage, scoping, and relationships with siblings. 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 'key' parameter. The description adds meaning by tying it to 'remember' and 'forget', and clarifies the listing behavior when omitted.

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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It distinguishes itself from sibling tools remember and forget, providing a specific verb and resource.

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 it ('to look up context the agent stored earlier') and how it pairs with remember and forget. It also mentions scoping but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: parallel fan-out to multiple sources, fallback logic (GDELT→GNews), API sunset soft-fail, and date format handling. 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?

Dense single paragraph efficiently conveys purpose, sources, date handling, output, and alternatives. Could be slightly more structured with bullet points, but effective for its length.

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

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

Covers all aspects given tool complexity: purpose, usage, source behavior, date format, output structure (changes array, total_count, URIs), and relationship to sibling. No output schema so description compensates well.

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: explains `since` format with examples and recommendation, clarifies `type` only supports 'company', and gives examples for `value` (ticker or CIK).

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

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

Description clearly states the tool retrieves recent changes for a company, with specific verb 'fans out in parallel' and lists sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from sibling 'entity_profile' by contrasting static vs. windowed use.

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

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

Provides explicit use cases ('what's happening with X', 'updates on Y') and when not to use it ('Use entity_profile instead when you want the static profile'). Names an alternative tool.

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

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

Annotations provide idempotent and non-destructive hints. The description adds context on scope (key-value pair by identifier) and persistence (24 hours for anonymous, persistent for authenticated users), which is valuable 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 purpose, then usage, then behavior details. Every sentence adds value without redundancy.

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

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

Fully covers use cases, scope, and lifecycle. No output schema needed; the tool's simplicity is well addressed.

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 descriptions, but the description reinforces the key-value pattern and provides example keys and values, adding useful context.

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: saving data for reuse. It provides concrete examples ('resolved ticker, target address, user preference') and distinguishes it from sibling tools 'recall' and 'forget'.

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

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

Explicitly instructs when to use ('when you discover something worth carrying forward') and provides guidance on pairing with recall/forget. No 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?

Annotations already indicate read-only, idempotent, not destructive. Description adds value by describing internal cascading lookups and output specifics per type, beyond what annotations provide.

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

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

Description is well-structured and front-loaded with purpose and usage guidance. It is concise but could be slightly tighter; e.g., the list of types could be more compact.

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 explains return values adequately. It covers supported types and inputs. Missing error handling or edge cases, but sufficient for a 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%, but description adds substantial meaning: explains acceptable input formats for each type (ticker, CIK, name for company; brand/generic for drug) and what is returned (CIK, ticker, citation URI).

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

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

Description clearly states the verb 'Resolve' and the resource: user-spoken names to canonical identifiers. It differentiates from siblings by specifying 'Use FIRST when you have a name but need an ID' and listing supported entity types with distinct output formats.

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 ('Use FIRST when you have a name but need an ID'), but does not explicitly mention when not to use or name alternative tools. However, the context is clear enough for an 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds value by detailing internal behavior (probes each entity, ranks results) and output fields (score, confidence, signal density), plus narrative treatment of first entity. No contradiction.

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

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

Three sentences with clear front-loading: function, method, usage context. Every sentence provides distinct value. No redundancy or filler.

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

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

Covers purpose, method, usage, and return values (ranked list, score, confidence, signal density) despite no output schema. Mentions internal dependency on ai_visibility_check. Slightly incomplete on exact output format but sufficient for agent selection.

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

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

All parameters have full schema descriptions (100% coverage). Description reiterates entities role (first is subject) and tool purpose, but adds minimal new semantic 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 it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks by score. Differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (broader comparison) with the specific competitive audit focus.

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

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

Provides explicit use case (competitive AI-marketing audits) and example question. Implicitly directs agents to use ai_visibility_check for single-entity queries, but could strengthen with explicit when-to-use vs. 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: composite fan-out across services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 a single paragraph but is dense with information, front-loading the purpose. Every sentence adds value, though it could be slightly more structured for quick scanning. Minimal 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 thoroughly explains return fields (summary block fields, per-advisory detail, links, recent versions), behavior on partial failures, timing constraints, and ecosystem limitations. It leaves little ambiguity about what to expect.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reiterates version defaults to latest and scoped packages accepted, but adds little new meaning 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 it is a composite check for npm packages, combining deps.dev and bundlephobia, answering questions about safety, popularity, and size. It distinguishes from siblings by being the only tool focused on npm dependency scanning.

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 "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies it is for npm ecosystem only, with alternatives for other ecosystems (PyPI etc. fall under deps.dev:version). This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent and beneficial. Description adds valuable behavioral details: returns structured verdict with citation and delta, replaces multiple sequential calls, and notes v1 limitations.

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

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

Description is concise and well-structured: front-loads the core action, provides clear examples, and adds efficiency claims without unnecessary detail.

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 clearly explains return values (verdict, actual value, citation, delta). Covers input, use case, domain limitations, and replaces multiple steps, making it complete for a one-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?

Single parameter 'claim' has a schema description that is sufficient, but the tool description adds practical context (e.g., examples of valid claims, implicit domain constraint) that enriches 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?

Clearly states the tool fact-checks natural-language claims against authoritative sources, specifies the domain (company-financial claims for v1), and lists possible verdicts. Distinguishes itself from sibling tools by being a specialized verification tool.

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

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

Explicitly advises use when agents need to check factual statements, provides example queries. Does not explicitly mention when not to use or alternatives, but the context is clear enough for an AI agent to decide.

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