Hex Pm

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

Annotations already declare readOnlyHint and idempotentHint. Description adds concrete value: mentions cost implication 'you pay Anthropic directly', return structure per-model, and that context helps disambiguate. No contradictions.

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

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

Three sentences only, each essential: first states core purpose and scoring, second details models and cost, third describes return structure. No redundant words.

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

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

No output schema, but description provides enough detail: return includes per-model {score, confidence, signals, raw_response} and combined view. Covers default model, optional parameters, and usage context. Complete for agent understanding.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: clarifies default model (Workers AI Llama-3.3-70b), optional _apiKey only for anthropic model, and context purpose. Exceeds 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?

Description uses specific verb 'Probe and score' on resource 'LLMs for what they know about an entity', with clear outcome 'score visibility (0-100) per model'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model scoring and optional API key for Anthropic.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Default model and optional Anthropic with BYO key are clearly indicated. No exclusion criteria or alternatives mentioned, but context suffices given sibling diversity.

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, open-world. The description adds that it returns structured answers with stable pipeworx:// citation URIs and routes to the right tool. No contradictions. It provides context about the output format and the routing mechanism 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 front-loaded with the key guidance 'PREFER OVER WEB SEARCH' and then provides details and examples. It is a single paragraph but not overly long; every sentence adds value. Could be slightly shorter but still 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?

Given the tool's complexity (routing to 3,336 tools) and lack of output schema, the description adequately explains the tool's purpose, when to use, and the nature of the output (structured answers with citations). It provides numerous examples. It could additionally describe the return format, but overall it's complete 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?

The input schema (100% coverage) already defines the 'question' parameter and its aliases. The description adds examples of valid questions and emphasizes natural language input. While helpful, it does not add substantial new meaning beyond the schema's description.

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

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

The description clearly states it routes questions to a vast set of tools (3,336) and returns structured answers with citations. It explicitly says 'PREFER OVER WEB SEARCH' for factual data, distinguishing it from generic web search. Examples like 'current US unemployment rate' reinforce the specific verb+resource mapping.

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: 'PREFER OVER WEB SEARCH' and lists specific query types (SEC filings, FDA drug data, etc.) and phrasings (what is, look up, find, etc.). It even says 'use whenever the user asks ... even if web search could also answer it.' This clearly tells when to 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes far beyond by detailing resolution logic, fan-out mechanisms, response shapes, safety short-circuits, closed-market handling, and tradeability warnings. No contradictions; the description richly supplements the annotations.

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

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

The description is dense but well-organized with bold headings, examples, and clear sections. While lengthy, every sentence serves a purpose for a complex tool. Slightly verbose for quick scanning, but the front-loaded purpose statement and structured format make it 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 documents all return fields (market, analysis, evidence, resolver contract, parent_event, news fields) and statuses (low_confidence_match, market_closed_or_inactive). It covers complex behaviors like parallel fan-out, safety guards, and edge cases, leaving minimal ambiguity.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description adds extra context: the `market` field accepts slug, URL, or text; `depth` defaults to thorough; `include_raw` default false with size implications. This significantly enhances understanding beyond the schema.

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

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

The description opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and concrete use cases ('should I bet on X', 'what does the data say about Y'), distinguishing it from sibling tools like polymarket_edges or 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 provides explicit when-to-use examples and covers edge cases (low confidence, closed markets, wide spreads). While it doesn't explicitly state when NOT to use the tool, the clear purpose and failure modes give strong guidance. A score of 5 would require explicit alternatives or 'do not use when' statements.

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, etc. Description adds significant context: data sources (SEC EDGAR, FAERS), a bug fix, handling of off-calendar fiscal years, return format with citation URIs, and sorting. 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?

Packed with useful information, front-loaded with purpose. Could be slightly more concise, but every sentence adds value with examples and technical details.

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

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

Without an output schema, the description explains return values (paired data, citation URIs) and sorting. Covers most behavioral aspects of a comparison tool, though could mention edge cases like missing data.

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. Description adds examples (e.g., tickers, drug names), clarifies constraints (2-5 items), and explains how 'type' determines data source, adding 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 it compares 2-5 companies or drugs side by side, with specific verbs and resource types. It distinguishes from siblings like entity_profile by noting it replaces 8-15 sequential lookups.

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., 'compare X and Y', 'X vs Y') and type-specific behavior. Does not explicitly state when not to use, 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, idempotentHint=true, destructiveHint=false. The description adds value by explaining that the tool returns top-N relevant tools with full schemas and curated examples, ready to call directly, which goes beyond the annotations.

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

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

The description is informative but slightly lengthy due to listing many example domains. However, each sentence adds value, and the structure uses colons and lists effectively. Slightly improved by front-loading the core purpose.

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

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

Without an output schema, the description explains the return format (top-N tools with names, descriptions, full input schemas). It also mentions examples in the input schema. For a discovery tool with many siblings, this provides sufficient context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that parameters like q, task, search, description are aliases for query, reducing confusion. It also explains limit's default (20) and max (50), which is not in 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 specifies the tool's purpose: finding tools by natural language description. It lists numerous example domains (SEC filings, FDA drugs, etc.) and differentiates itself from siblings by advising to call it first when many tools are available, indicating its role as a discovery 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 explicitly states when to use the tool: when needing to browse, search, look up, or discover tools. It also advises 'Call this FIRST when you have many tools available,' implying it should be used before directly invoking other tools, providing clear usage 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?

Beyond annotations (readOnlyHint, etc.), the description discloses specific behavioral traits: the return fields (filings with URIs, fundamentals with latest 10-K numbers), data freshness caveats (Run 6 fix for FY2025), sunset of USPTO API, and fallback mechanisms. This adds significant value 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 slightly dense but front-loaded with the purpose. Every sentence adds value, covering purpose, usage, parameter details, and return data. A bit lengthy but justified by the tool's complexity; could be slightly more structured but remains 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 return data: company identifiers, recent filings with URIs, fundamentals with caveats, patents status, news fallback, and LEI. It also addresses limitations and prerequisites (resolve_entity for names), making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining that 'type' only supports 'company' and 'value' accepts ticker or zero-padded CIK, and explicitly states that names are not supported. This contextual information helps the agent avoid errors.

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 comprehensive information about a US public company in a single call. It uses specific verbs ('Get everything') and resources ('US public company'), and distinguishes it from alternatives (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?

Explicit usage guidance is provided: when to use (user asks 'tell me about X', etc.) and when not to (names not supported; use resolve_entity first). It also notes the alternative of using multiple pack tools and mentions limitations (patents API sunset).

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. Description adds context about clearing sensitive data and timing, which goes beyond annotations without contradicting them.

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

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

Two sentences: first states purpose, second provides usage guidelines. No unnecessary words, front-loaded with key information.

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

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

For a simple one-parameter, no-output-schema tool, the description covers purpose, usage context, and pairing with sibling tools. No gaps remain.

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% and already describes 'key' as 'Memory key to delete'. The description does not add new meaning beyond restating the key parameter.

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 a distinct action and resource. It distinguishes from siblings 'remember' and 'recall' by naming them directly.

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 when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall, implying 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, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral detail: fetches page, extracts title/description/key links, outputs standard markdown. Consistent with annotations, 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 sentences, front-loaded with key action, no wasted words. Every sentence adds value and is efficiently structured.

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

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

Given no output schema, description sufficiently explains output format (single text blob for site-root/llms.txt). No gaps for a simple tool with good 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% with both parameters described. Description complements by explaining that url is the site to summarize and references max_links indirectly. Adds context beyond bare schema.

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

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

Description clearly states the tool generates an llms.txt file for AI crawlers, specifying verb 'generate', resource 'llms.txt file', and scope 'for any URL'. Distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence which have different purposes.

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 (client indexing, personal drafting, competitor auditing). Provides clear context for when to use, though does not mention when not to use or alternative tools.

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

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

Annotations only show readOnlyHint=false and destructiveHint=false, leaving behavioral details unclear. The description adds value by disclosing rate limits, cost, and quota impact. 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?

Description is a single paragraph but well-organized: purpose first, then usage, then constraints. Every sentence adds value, though it could be slightly more concise. Front-loaded effectively.

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 feedback tool with no output schema, the description covers input constraints, rate limits, free usage, and behavioral guidelines. It provides enough context for correct invocation without needing output schema.

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 description does not need to explain parameters. It adds some context for the 'message' parameter (e.g., avoid pasting prompts), but baseline 3 is appropriate since schema already fully documents parameters.

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

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

Description clearly states the tool is for telling the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resource identification, and the purpose uniquely distinguishes it from sibling tools like 'ask_pipeworx' or '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?

Explicitly states when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Provides constraints: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. No alternative tools mentioned, but context covers most usage 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, and 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?

The description is 5 well-structured sentences, front-loaded with the core purpose, and 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?

Despite no output schema, the description covers data source, aggregation, privacy, and caching. It sufficiently prepares the agent for invocation given the simple input schema.

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% for the single parameter 'window'. The description adds semantic guidance beyond the schema: shorter windows for hot trends, longer for steady-state demand.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows, using specific verbs and resources. It distinguishes itself from sibling tools like 'discover_tools' by focusing on trending data.

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

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

The description explicitly provides three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and notes caching behavior, giving clear context for when 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description details behavioral traits: two modes, monotonicity checks, partition-sum checks with threshold (3pp), placeholder filtering, Jaccard similarity threshold (0.30), and output structure. 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 detailed and well-structured, using clear separation for the two modes and bullet points for additional context. It is somewhat dense but every sentence adds relevant information. Slightly longer than necessary but not overly 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?

Given the tool's complexity and absence of an output schema, the description covers key components: modes, checks, filters, and response structure (opportunities array and partition_check object). It lacks precise formats for output fields but provides enough context for an agent to understand the tool's capabilities.

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 baseline is 3. The description adds value by explaining the role of each parameter ('event' for single-event mode, 'topic' for cross-event mode) and how they trigger different behaviors. 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's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges by detailing two specific modes (event and topic) and the underlying logic.

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

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

The description explains when to use each mode: 'event' for a single event slug and 'topic' for cross-event queries. It provides concrete examples and describes the filtering criteria. While not explicitly stating when not to use it, the guidance is sufficient for the agent.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing the three model families, their methodologies (e.g., 'crypto_price (lognormal barrier from 90d FRED log-returns)'), limitations (e.g., 'Fed bets... excluded from ranking'), and diagnostics for empty segments. Annotations are consistent and the description builds on them extensively.

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 long and dense, containing extensive technical methodology. While structured with segments and front-loaded with purpose, it could be more concise. The detail is valuable but length 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?

Despite no output schema, the description thoroughly explains the three response segments, per-opportunity fields (edge_pp_net, kelly_fraction, etc.), diagnostics, and limitations. It covers caching and knob effects, making the tool's behavior and outputs fully understandable.

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

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

With 100% schema description coverage, the baseline is 3. The description adds some context for knobs like min_partition_leg_kelly, explaining its role in filtering thin partitions, but mostly restates schema. No significant additional parameter 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 explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear target use case: 'what should I bet on today'. This distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx data and providing three distinct opportunity segments.

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 sets context as a daily discovery tool ('agents discover opportunities without paging hundreds of markets') and mentions knobs like min_liquidity for tradeable-edge filtering. However, it does not explicitly contrast with sibling tools or provide when-not-to-use guidance, missing a full alternative comparison.

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

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

Annotations already mark readOnlyHint, idempotentHint, and openWorldHint, but the description adds substantial behavioral context: safety fields (compatibility_warning, temporal_alignment), skipped comparisons due to metric mismatches, and the fact that spreads are mathematically meaningless without temporal alignment. 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 lengthy but well-structured with sections and bullet points. Every sentence adds useful detail, and the core purpose is front-loaded. Some redundancy could be trimmed, but the detail is justified for the tool's complexity.

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

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

Given the tool's complexity (two modes, safety fields, compatibility warnings, temporal alignment), the description is thorough. It explains the response format (leg-by-leg prices, spread, top_spreads_pp) and covers edge cases like skipped crosses and misaligned resolution periods. No output schema is provided, so the description carries full burden and succeeds.

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% (all parameters described). The description adds value by explaining the two modes and how explicit tickers override topic mappings, and by listing the exact topic enum values. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes from siblings like polymarket_arbitrage by focusing on equivalent bet shapes.

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 context on when the spread is meaningful (equivalent bet shapes) and when it's not (compatibility warnings). It warns that most pre-mapped topics return warnings, guiding agents to expect non-tradeable signals. However, it does not explicitly name alternative tools from the sibling list.

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, destructiveHint=false, idempotentHint=true. The description adds context beyond annotations: scoping to identifier and the ability to list all keys by omitting the argument. 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 three sentences, front-loaded with the main action, and every sentence adds value. No filler or 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 simple tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and related tools. It could mention persistence limits but is otherwise complete.

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

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

Schema description coverage is 100% and already notes that omitting key lists all keys. The description adds use-case examples but does not significantly extend the schema's meaning. 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 retrieves a value saved via remember or lists all saved keys if the key is omitted. It specifies the resource (memory) and distinguishes from sibling tools remember and forget.

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

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

The description provides explicit use cases (look up target ticker, address, research notes) and mentions scoping to identifier. It pairs with remember and forget, offering clear context for when to use this tool, though it doesn't explicitly state when not to use 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, openWorldHint=true. The description adds rich behavioral context: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-fail with explanation. It also details the return format (changes[] grouped by source, total_changes, citation URIs). 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 a single well-structured paragraph that front-loads purpose and examples, then covers sources, parameter details, and sibling differentiation. While slightly long, every sentence adds value with no redundancy.

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

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

Given the tool's complexity (multiple sources, fallback logic, various parameter formats) and the absence of output schema, the description is remarkably complete. It explains the fan-out, failure modes, return structure, and cite URIs. No gaps remain for effective 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?

Input schema covers all three parameters with descriptions (100% coverage). The description adds substantial value: explains that `since` accepts ISO date or relative shorthand (and gives examples), suggests defaults ('30d' or '1m'), and clarifies that `value` can be ticker or CIK. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'What's new with a company in the last N days/months?' and provides concrete use cases like 'what's happening with X', 'updates on Y'. It explicitly distinguishes from sibling tool entity_profile, which is used for static profiles regardless of window.

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

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

The description gives explicit when-to-use guidance with example queries and a clear exclusion: 'Use entity_profile instead when you want the static profile...'. It also explains the multi-source fan-out behavior, helping the agent understand what to expect.

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 idempotentHint true, destructiveHint false. Description adds behavioral context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and scoping by identifier, which exceeds annotation information.

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

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers purpose, usage, behavior, and pairing with siblings. No gaps identified.

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 both parameters described. Description does not add additional parameter meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It distinguishes from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete', providing specific verb-resource and 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?

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward'. Gives context about persistence and scoping, but does not explicitly state when not to 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's addition of internal cascading behavior and auto-disambiguation adds valuable context beyond annotations. 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 with two main sentences and a bullet-like list within the text. Every sentence provides value, and key information is front-loaded. No redundancy.

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

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

Despite no output schema, the description explains returns for each type, covers both parameters, and includes behavioral notes like cascading lookups. Annotations cover safety and idempotency. The description is fully adequate for selecting and invoking the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor extra context like auto-disambiguation and citation URIs, but the schema already describes the parameter values adequately. Thus, description does not significantly exceed schema information.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, specifying supported types (company, drug) and return values. It distinguishes itself by being the tool to use first when an ID is needed, and mentions it replaces multiple manual lookups, which differentiates it from sibling tools that may not provide such resolution.

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

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

The description explicitly says 'Use FIRST when you have a name but need an ID,' providing clear context for when to use the tool. However, it does not mention when not to use it or compare it with alternatives like entity_profile, leaving some gap in 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 declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: it explains the internal process (probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized) and the output structure (ranked list with score, confidence, signal density). No contradiction with annotations.

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

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

The description is three sentences long, front-loaded with the primary action, and every sentence adds value. No redundant or extraneous information. 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?

Despite no output schema, the description fully explains the return format (ranked list with score, confidence, signal density per entity). It covers parameters, process, and use case comprehensively. No gaps in understanding.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds extra meaning: 'entities' must be 2-8 with first as subject, 'context' is shared context applied per probe, and 'models' with '_apiKey' are explained in relation to Anthropic. This supplements the schema well.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic) by explicitly referencing the probe mechanism and ranking.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' with an example query. It implicitly suggests alternatives (single entity check uses ai_visibility_check) but does not explicitly state when not to use this tool or list direct alternates.

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 valuable behavioral context beyond the annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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 but well-structured, with two sentences: one explaining the composite function and one covering usage and limitations. Every sentence adds value, and 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?

Given no output schema, the description explains return fields (summary block, per-advisory, links, alternative versions) and partial failure behavior. Missing error handling details beyond timeouts, but overall highly informative 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?

Schema coverage is 100%, so description adds minimal value: mentions scoped packages accepted for 'package' and version defaults to latest. Baseline 3 is appropriate as the schema already documents parameters well.

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

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

The description clearly states the tool is a composite check for npm packages, covering license, advisories, version history, and bundle size. It specifically names the resources (deps.dev, bundlephobia) and distinguishes from siblings by mentioning the NPM-only 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?

Provides explicit usage scenarios ('is X safe / popular / small', 'what does adding lodash cost me') and notes the limitation to NPM ecosystem in v1, with a fallback hint for other ecosystems. Missing explicit when-not to use, but the ecosystem limitation serves as a partial exclusion.

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. The description adds significant value by detailing the return format (verdict types, structured form, actual value, citation, percent delta) and explaining it replaces multiple sequential calls. 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 a single, well-structured paragraph. It front-loads the primary purpose, then provides usage guidance, scope, and return details. Every sentence adds value without redundancy. It is concise yet comprehensive.

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 return values and domain limitations. Given the tool's simplicity (single required parameter) and richness of annotations, the description covers all necessary context for an agent to use it correctly.

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

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

The input schema has 1 parameter with 100% description coverage. The schema provides a clear description and examples. The overall description reinforces the parameter's role and expected format. This adds modest value beyond the schema, justifying a 4 rather than a baseline 3.

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

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

The description clearly states the tool's purpose: fact-checking natural-language claims, specifically company-financial claims. It uses specific verbs like 'fact-check, verify, validate' and resource 'natural-language factual claim'. It distinguishes from siblings by noting it replaces 4-6 sequential calls, which sets it apart from related tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use when an agent needs to check whether something a user said is true' and provides example queries. It also specifies the domain (company-financial claims) and version limitations. However, it does not explicitly mention when not to use this tool or suggest alternatives from the sibling list, though the context is clear.

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