Visualcrossing

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context about the default free model, the requirement for a BYO API key for Anthropic, and the fact that the user pays Anthropic directly. This goes beyond annotations.

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

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

The description is three sentences long, front-loading the main purpose and essential details. Every sentence provides 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 the lack of output schema, the description adequately outlines the return structure (score, confidence, signals, raw_response + combined view). It does not cover error handling or rate limits, but for a read-only probe tool 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?

Schema coverage is 100%, so the description adds value by clarifying that 'workers-ai' is the default model and that '_apiKey' is passed directly to api.anthropic.com. This provides actionable detail 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 probes LLMs about a business/brand/product/topic and returns visibility scores per model. It specifies the default model and the option to use Anthropic via API key. This distinguishes it from siblings like 'scan_competitor_ai_presence' which is more specific.

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

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

The description provides explicit use cases such as AI-marketing audits, pre-launch brand checks, and competitive monitoring. However, it does not excludively compare with alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it routes to subtools and returns structured answers with citation URIs. No contradictions, but some behavior (e.g., latency, limitations) is not mentioned, though annotations cover safety.

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?

Roughly 100 words, front-loaded with a strong preference statement. Every sentence adds value, examples are concise, and no redundant information. Excellent structure for quick comprehension.

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 (single dynamic parameter, many aliases, no output schema), the description fully explains its purpose, usage boundaries, and expected output (structured data with citations). No gaps for an MCP tool of this type.

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 for all 6 parameters (one required field with multiple aliases). Description reiterates the natural language nature of the parameter and gives examples, adding context beyond the schema. Slightly above baseline due to practical examples.

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 routes factual questions to one of 3,336 tools across 747 sources, returning structured answers with citations. It uses specific verbs like 'routes' and 'returns', and distinguishes itself from web search by preference.

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 'PREFER OVER WEB SEARCH' and provides numerous example query types and specific questions. It gives clear when-to-use guidance and covers a wide range of domains, effectively differentiating from siblings like web search or entity lookups.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds extensive behavioral details: resolver contract (match confidence, alternatives), parent_event extractor, news fallback handling, safety short-circuits for low-confidence and closed markets. This guides correct agent 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 core purpose, but is very lengthy (multiple paragraphs, over 500 words). While the detail is useful, it sacrifices conciseness. Each section earns its place, but a shorter version could be equally effective.

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

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

Despite no output schema, the description thoroughly explains the response shape (market, analysis, evidence), match confidence, parent event, news fields, and safety behaviors. It provides all necessary context for an agent to use 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining market parameter formats, depth default and behavior ('quick = 2-3 evidence sources'), and include_raw use cases. This goes 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 researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question text). It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on a single bet's detailed research.

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

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

Explicit use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), along with classification and fan-out examples. It does not explicitly state when not to use, but the context makes it clear that other tools handle comparison and trending.

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 declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral details: returns actual most-recent FY filing, handles off-calendar fiscal years, uses SEC EDGAR for companies and FAERS for drugs, returns sorted results with citation URIs. No contradictions found.

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 moderately sized but well-organized: purpose upfront, then per-type details, then result format and benefit. Every sentence adds value without being verbose.

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

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

No output schema exists, but the description adequately explains return values: paired data, citation URIs, sorted by primary metric. For a tool with two simple parameters and clear data sources, this is sufficient.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values'. The description adds context per type: for company it pulls 10-K data, for drug it pulls FAERS/approval/trial counts, and clarifies the format of values (tickers/CIKs or drug names).

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

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

The description clearly states the tool compares 2-5 companies or drugs side by side, with specific verbs 'compare' and 'rank-by-metric'. It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison and aggregation.

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

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

The description explicitly lists use cases: 'compare X and Y', 'X vs Y', 'which is bigger', rank-by-metric questions. It notes it replaces 8-15 sequential lookups. However, it does not explicitly mention when not to use it or alternatives like entity_profile for single-entity details.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds value by noting the data is 'live' and 'current', and the example demonstrates usage. 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 extremely concise: one sentence specifying the tool's purpose and an example. Every word earns its place, and the key information is front-loaded.

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

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

The tool lacks an output schema, but the description compensates by listing expected data fields (temperature, humidity, etc.). It sufficiently informs the agent about what the tool returns, though additional notes on data source could improve completeness.

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

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

Schema coverage is 100%, meaning all parameters are documented in the schema. The description only references location via example, adding no new meaning beyond schema descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves live current weather conditions for a location, specifying data points like temperature, feels-like, humidity, wind, and conditions. It distinguishes from siblings such as 'forecast' and 'weather_timeline' by focusing on current conditions.

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 is for immediate current weather data, contrasting with forecast. It provides an example but does not explicitly state when to avoid or list alternatives, though context from sibling names (e.g., 'forecast') helps.

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 a safe, idempotent read operation. The description extends this by detailing return behavior: it returns top-N relevant tools with full schemas, eliminating secondary lookups. 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 somewhat verbose but well-structured: first sentence states purpose, then lists domains, then explains output and usage. It front-loads key information, though it could be trimmed slightly.

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

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

Given no output schema, the description adequately explains what the tool returns (names, descriptions, full schemas). It covers purpose, usage, and output, but lacks details on the response format (e.g., whether results are ranked, pagination). It is complete for a discovery 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 does not add significant meaning beyond the schema; it only mentions the 'query' field and aliases, which are already documented.

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 verb ('Find tools') and resource ('by describing the data or task'), and explicitly distinguishes it from sibling tools by recommending to call it first for discovery rather than for specific answers.

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 when-to-use scenarios ('browse, search, look up, or discover what tools exist') and when-not-to-use ('not just one answer'), along with the directive to call it first when many tools are available.

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 important behavioral traits beyond annotations: patents API sunset causing soft-fail, fundamentals sorting, fix for stale numbers, and data freshness. 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 somewhat lengthy but every sentence adds value. It is front-loaded with purpose and well-structured. A minor point: could be slightly more concise, but the information density justifies the length.

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

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

Despite no output schema, the description comprehensively lists all returned fields with details (URIs, sorting, known issues). For a complex multi-source tool, this provides complete and actionable 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 coverage is 100%, but the description adds significant context: clarifies type only supports 'company', explains value format (ticker or CIK), and explicitly states names not supported, directing to resolve_entity.

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

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

The description clearly states the tool returns everything about a US public company in one call, listing specific data sources. It distinguishes 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 specifies when to use (e.g., 'tell me about X', 'research Acme') and when not to use (names not supported, use resolve_entity first). Provides clear context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the exact data returned (temp, humidity, etc.) and the 15-day timeframe, providing context beyond annotations.

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

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

The description is two sentences with an example, no extraneous words. Every sentence earns its place.

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

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

Given no output schema, the description adequately lists return fields and the 15-day scope. It lacks error or limit details, but the annotations and context signals compensate partially. Fairly complete for the domain.

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

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

Schema description coverage is 100%, so the schema already describes all three parameters. The description includes an example call, which adds contextual value but does not significantly extend 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 retrieves a 15-day daily weather forecast for a location, listing specific data fields (temp/min/max, humidity, etc.). It distinguishes from siblings like 'current_conditions' and 'weather_timeline' by specifying the 15-day scope.

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 via the example and the '15-day daily' scope, but it does not explicitly state when to use this tool versus alternatives. No 'when-not-to-use' guidance is provided.

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 destructiveHint: true and idempotentHint: true, and the description adds context about clearing sensitive data and deletion. 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?

Two sentences, front-loaded with the action, no filler. Highly 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 single-parameter tool with no output schema, the description covers purpose, usage context, and sibling relations completely.

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 'key'. The description does not add new info beyond the schema, but the example clarifies expected values.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying verb and resource, and distinguishes from siblings '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 provides when to use: when context is stale, task done, or clearing sensitive data. Mentions pairing with siblings, though lacks explicit when-not scenarios.

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 core behavior: fetches page, extracts title/description/key links, outputs markdown. Annotations already confirm read-only, idempotent, non-destructive; description adds meaningful context 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?

Three sentences, front-loaded with purpose, no unnecessary words. Every sentence contributes to understanding.

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

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

Given simple tool with rich annotations and no output schema, description covers purpose, usage, and behavior. Mentions output is standard markdown format, sufficient for an AI agent.

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

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

Schema coverage is 100% with schema descriptions for both parameters. Description adds no additional detail beyond schema, meeting baseline but not exceeding.

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 generates an llms.txt file for a URL. Action verb 'generate', specific resource 'llms.txt', and context 'AI crawlers'. No sibling tool overlaps, as listed siblings are unrelated.

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 three use cases: indexing a client's site, drafting for own project, auditing competitors. Provides clear context for when to use, though not explicitly excluding alternative scenarios.

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 (which are all false), description reveals rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that feedback impacts roadmap. 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?

Five sentences, all front-loaded. Each sentence adds unique information (purpose, usage, constraints, roadmap impact). 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 simplicity of a feedback tool (no output schema, 3 parameters), the description fully covers purpose, behavior, constraints (rate limit, quota), and parameter hints. 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 covers 100% with descriptions. Description adds value by explaining enum values (bug, feature, data_gap, praise) and gives advice on message formatting. Exceeds baseline.

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 is for providing feedback to Pipeworx about bugs, missing features, or praise. Differentiates from sibling tools by focusing on feedback rather than queries or actions.

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

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

Provides explicit use cases (bug, feature, data_gap, praise) and mentions rate limits and quota. Lacks explicit when-not-to-use, but the positive guidance is strong.

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

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

Annotations already declare readOnly and idempotent. The description adds valuable context: data source (CF analytics-engine), no PII, aggregation format, and caching behavior (5min-1h). This goes beyond annotations and gives the agent full behavioral awareness.

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 front-loaded with the core action, then lists three bullet-like use cases, and ends with caching and data source details. Every sentence serves a purpose with no redundancy. Ideal length for a simple 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 one optional parameter, good annotations, and no output schema, the description fully covers what the agent needs: what it returns (top tools, packs, volume), data freshness, and privacy. Nothing missing for effective use.

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

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

Only one parameter (window) with full schema coverage (100%). The schema description already explains the enum values and trade-offs. The tool description does not add new parameter semantics beyond what the schema provides, so baseline score 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 returns 'what other AI agents are calling on Pipeworx right now' and lists specific outputs (top tools, top packs, total call volume). It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on aggregated trending data from agent activity.

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?

Three explicit use cases are provided, covering discovery, validation, and alignment. This gives clear guidance on when to use the tool. Missing explicit when-not-to-use or alternatives, but the context from siblings and the use cases imply appropriate scenarios.

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 extensive behavioral detail: two operation modes, similarity threshold (Jaccard), placeholder filtering, and output structure, providing complete transparency 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 comprehensive and well-structured, starting with the purpose and moving into details. While slightly verbose, every sentence adds value and the information is easy to parse.

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

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

Despite no output schema, the description fully explains the return format (opportunities array with fields, partition_check object). It also covers edge cases like topic with many events, placeholders, and low similarity, making it complete for a complex 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?

Both parameters (event and topic) are fully described in the schema (100% coverage). The description adds significant meaning by explaining they are mutually exclusive modes, providing examples, and detailing how each mode processes input.

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 using monotonicity violations and partition-sum checks. It explains two distinct modes (event and topic) with specific use cases, effectively differentiating it 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 for a single event, topic for cross-event searches) and details the semantic anchor and partition filter. However, it does not explicitly state when not to use the tool 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?

The description significantly expands on the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the three model segments, caching behavior (1h KV-level), and the inclusion of a 24h-move warning. It explains edge calculation net of slippage and provides internal diagnostics. There is 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 very detailed but verbose (around 500 words). While it is front-loaded with purpose, it includes extensive technical details that could be partially moved to the schema or output schema. Some repetition (e.g., explaining segments both in prose and in the response structure) reduces conciseness.

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 absence of an output schema, the description comprehensively covers the response structure (by_segment, fed_candidates, _diagnostics), caching, and edge calculation details. It explains why Fed bets are excluded and provides diagnostics for empty segments. This makes the tool self-contained for an AI agent.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by explaining nuanced behavior, such as how min_partition_leg_kelly applies differently to partition opportunities and how slippage_pp affects edge calculation. This extra context justifies a 4.

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: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the output structure (three segments) and provides context for use ('what should I bet on today'). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage.

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

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

The description offers explicit usage guidance, including the primary use case and various knobs for filtering (e.g., min_liquidity, max_spread_pp). It also notes that Fed bets are excluded from ranking due to unreliable signal. While it provides clear context, it lacks explicit when-not-to-use instructions.

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

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

Annotations indicate readOnlyHint:true, and the description adds significant behavioral context beyond that. It explains conditions for meaningful spreads (equivalent bet shapes, temporal alignment), details safety fields (compatibility_warning, temporal_alignment), and discloses limitations (most pre-mapped topics not tradeable). 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 relatively long but well-structured: purpose first, then modes, response, safety fields. Every sentence adds value, though some redundancy could be trimmed. It is front-loaded and uses bullet-like formatting for the list of topics.

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 does a good job explaining response fields (spread, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers limitations and safety features. However, it could be more explicit about the exact output structure (e.g., JSON format) and does not mention possible response shape for invalid topics.

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

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

Schema covers 100% of parameters with descriptions. The description adds meaning by explaining the two modes, listing topic values, and describing how explicit parameters override topic mapping. It gives context beyond the schema, such as the effect of overriding a side.

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: computing cross-venue spreads between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit event tickers) and contrasts with potential siblings like polymarket_arbitrage by focusing on cross-venue comparison. The verb 'compute spread' plus resource ('cross-venue') is specific and distinguishes the tool.

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

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

The description provides explicit guidance on when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and warns that most pre-mapped topics return compatibility warnings, indicating limited tradeability. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or state when not to use this tool versus 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 declare read-only and idempotent; description adds scoping detail (by identifier) beyond annotations, with 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?

Two concise, front-loaded sentences with no redundancy; every sentence provides value.

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

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

Given simplicity, rich annotations, and complete schema, description covers purpose, scoping, and relation to siblings; no output schema needed as return behavior is explained.

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 minimal extra meaning (list all keys) beyond the schema's parameter description, meeting baseline.

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 a saved value or lists keys, with specific examples and ties to siblings (remember, forget), distinguishing it effectively.

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 (looking up stored context) and pairs with remember/forget, though no explicit when-not scenario is provided.

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 the annotations (readOnlyHint, idempotentHint, etc.), the description details the fan-out to multiple sources, fallback behavior (GDELT to GNews), and potential failures (USPTO soft-fails until reactivated). It also explains the return format, providing rich behavioral context.

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

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

The description is detailed and well-structured, starting with the main question and example uses, then covering source behavior, parameter details, and return format. While packed with information, it could be slightly trimmed without losing clarity, but it remains efficient and front-loaded.

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

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

With no output schema, the description compensates by explicitly stating it returns 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers all aspects: purpose, usage, parameters, behavior, and output, making it fully complete for an agent.

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

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

Schema coverage is 100%, but the description adds value by explaining that `since` accepts ISO or relative formats with examples ('7d', '30d', '1y'), suggests using '30d' or '1m' for typical monitoring, clarifies `type` is limited to 'company', and notes that `value` can be a ticker or CIK. This goes 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 opens with 'What's new with a company in the last N days/months?' and provides example queries like 'what's happening with X' and 'updates on Y'. It explicitly distinguishes from sibling tool entity_profile, which is for static profiles, making the purpose highly specific and clear.

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

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

It states when to use the tool ('for change-monitoring') and when to use an alternative ('Use entity_profile instead when you want the static profile'). This gives explicit usage context and alternatives, which is excellent 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 already indicate idempotence (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds value by specifying retention semantics (24-hour for anonymous, persistent for authenticated) and scope by identifier.

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 of ~80 words, front-loaded with purpose, followed by usage, then technical details. Every sentence provides 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 is needed for this simple key-value store. The description fully covers what is stored, scoping, retention, and companion tools, making it complete for 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 covers 100% of parameters with descriptions. The description adds naming conventions (e.g., 'subject_property') and value types ('findings, addresses'), enhancing meaning beyond schema.

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

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

The description clearly states the tool saves data for reuse, with specific examples (ticker, address, preference) and explicitly distinguishes it from siblings '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?

It provides explicit when-to-use guidance ('when you discover something worth carrying forward'), pairs with recall and forget, and explains persistence scoping (by identifier, with session vs. authenticated differences).

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 safe, idempotent, read-only behavior. Description adds context about cascading lookups and that it replaces multiple manual steps, which is helpful 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?

Well-structured with front-loaded purpose. Somewhat lengthy but every sentence adds value; 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?

Fully covers parameter details and output format. No gaps given no output schema. Annotations cover safety and idempotency.

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 detailed output specifics (ticker, CIK, RxCUI, citation URIs) and clarifies auto-disambiguation, 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 resolves user-spoken names to canonical identifiers. Specifically identifies supported types (company, drug) and what each returns. 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?

Explicitly says 'Use FIRST when you have a name but need an ID', providing clear direction. Lacks explicit when-not-to-use or alternatives, but the directive is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds return structure (ranked list with score, confidence, signal density) and probing behavior across models. No contradictions.

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

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

Four sentences front-loaded with purpose, then details, then use case. No redundant words. Efficient 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?

Describes output structure (ranked list with fields) despite no output schema. Covers prerequisite for Anthropic model. Could mention how to interpret confidence/signal density, but overall sufficient for a tool with 4 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?

Schema coverage is 100%, baseline 3. Description adds meaning: entities parameter specifies first as subject; models parameter lists supported options and API key requirement. Adds context 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 it compares AI visibility across multiple entities side-by-side by probing with ai_visibility_check and ranking them. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying AI-marketing 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?

Explicitly states 'Useful for competitive AI-marketing audits' with an example question. Notes that first entity is treated as subject, rest as competitors. Implicitly guides to use ai_visibility_check for single entity checks.

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 that the tool fans out to deps.dev and bundlephobia, returns specific fields, handles partial failures gracefully (bundlephobia timeout), and notes measurement delay. This adds value beyond annotations (readOnlyHint, idempotentHint) 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?

Description is detailed but well-organized, with the composite function front-loaded. While slightly verbose, each sentence contributes meaning; could be tightened slightly.

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 thoroughly explains return values (summary block, per-advisory detail, links, alternatives) and handles edge cases like partial failures. Complete for a composite tool with 2 parameters.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description adds default behavior for version and accepts scoped packages. Baseline 3 is appropriate as schema already provides 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's purpose: a composite check for adding an npm package, covering license, advisories, bundle size, etc. It distinguishes itself by specifying NPM-only scope and mentioning alternatives 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 states when to use (e.g., 'is X safe / popular / small' or 'what does adding lodash cost me') and provides exclusion guidance (NPM only in v1; other ecosystems via deps.dev:version). Sibling tools are unrelated, so no confusion.

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

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

The description discloses return types ('verdict', 'structured form', 'actual value', 'pipeworx:// citation', 'percent delta') and replaces 4-6 sequential calls, adding value beyond annotations that only note read-only, idempotent, and non-destructive behavior. 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 concise (4 sentences), front-loaded with the primary purpose, then usage guidance, then scope and output. Every sentence adds distinct value without repetition.

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

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

Given the single parameter and no output schema, the description fully covers the tool's behavior, including input format, scope limitations, and output structure. No gaps remain for an AI agent to infer.

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

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

The single parameter 'claim' is fully described in the schema (100% coverage). The description adds examples of valid inputs ('Apple's FY2024 revenue was $400 billion') and specifies natural-language format, providing useful context beyond the schema's basic description.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims, with a specific verb ('Fact-check, verify, validate') and resource ('claim against authoritative sources'). It distinguishes itself from siblings like 'ask_pipeworx' or 'compare_entities' by focusing on verification of factual statements, especially company-financial claims.

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

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

The description explicitly states when to use the tool: 'Use when an agent needs to check whether something a user said is true' with example queries. It also scopes usage to 'company-financial claims' in v1, but does not name specific sibling tools as alternatives for out-of-scope claims.

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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return field details (temp, humidity, etc.) and clarifies behavior for past vs future dates, supplementing 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?

Single paragraph, front-loaded with purpose, includes examples. Concise but dense; every sentence adds value. Slightly verbose in example but overall efficient.

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

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

No output schema, but description lists returned fields. All parameters covered, required vs optional clear, and examples illustrate usage. Complete for a tool of 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?

Schema coverage is 100%. Description adds meaning with examples, explains start_date/end_date usage, defaults, and optional fields, going 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 verb 'Get daily weather' and the resource 'for a location'. It explicitly covers both historical and forecast use cases, distinguishing from sibling tools like 'current_conditions' and 'forecast'.

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

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

Provides explicit guidance for historical weather and past-date queries, with examples. Lacks explicit when-not-to-use instructions relative to siblings, but examples serve as implicit guidance.

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