npm

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

The description adds behavioral context beyond annotations: it explains the cost model (free default, BYO for Anthropic), that the API key is passed directly, and the return structure. Annotations already indicate readOnly and idempotent, but the description provides valuable extra details for safe invocation.

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, concise paragraph that efficiently conveys the main action and key details. It front-loads the core purpose and includes important caveats (BYO key, default model) without unnecessary 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?

The description explains the return format (per-model {score, confidence, signals, raw_response} + combined view) and gives use cases, which is sufficient for an agent to understand the tool's output. It does not detail scoring methodology but that is acceptable given the tool's nature.

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 has 100% coverage with descriptions for all 4 parameters. The description reinforces some parameter usage (e.g., default model, _apiKey passed straight through) but does not add substantial new meaning beyond what the schema already provides.

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: probing LLMs for brand knowledge and scoring visibility (0-100). It specifies the action (probe), resource (LLMs), and outcome (score). However, it does not distinguish from a similar sibling tool 'scan_competitor_ai_presence', which may lead to confusion.

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 mentions default model and optional Anthropic with BYO key, giving some usage context. It lists use cases like AI-marketing audits and competitive monitoring, implying when to use. But it does not explicitly state when not to use or provide alternatives to avoid misuse.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it accepts natural language questions, automatically selects tools and fills arguments, and returns results. However, it doesn't mention potential limitations like response time, data source availability, or error handling for ambiguous questions.

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

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

The description is efficiently structured with a clear purpose statement followed by operational details and concrete examples. Every sentence adds value without redundancy, making it easy to understand the tool's function quickly.

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 (natural language processing with automatic tool selection) and lack of annotations or output schema, the description does well by explaining the core functionality and providing examples. However, it could benefit from mentioning what types of answers to expect or any limitations in data sources.

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

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

The schema description coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that the question should be in 'plain English' or 'natural language' and provides concrete examples, which enhances understanding beyond the schema's basic parameter documentation.

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

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

The description clearly states the tool's purpose with specific verbs ('Ask a question', 'get an answer') and resources ('best available data source'), distinguishing it from siblings by emphasizing natural language processing without needing to browse tools or learn schemas. It provides concrete examples that illustrate its unique function compared to other tools like discover_tools or search_packages.

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 this tool ('No need to browse tools or learn schemas — just describe what you need') and provides clear examples of appropriate questions, effectively distinguishing it from sibling tools that might require more technical interaction or specific parameters.

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

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

Describes internal process: resolves market, classifies bet type, fans out to appropriate packs (crypto+fred+gdelt, etc.), returns evidence and comparison. Aligns with readOnlyHint, openWorldHint, and destructiveHint 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?

Front-loaded with purpose, then explains inputs, internal logic, and use cases. Every sentence adds value. Efficiently packed with detail 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?

Covers all necessary aspects for an agent: input formats, parameter behavior, internal fan-out logic, output content (evidence packet + market-vs-model comparison). No output schema but description compensates adequately.

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?

Adds meaning beyond schema: explains 'market' can be slug, URL, or question text; 'depth' enum values defined (quick = 2-3 sources, thorough = full fan-out, default thorough). Schema coverage 100% but description enriches with context.

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

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

Clearly states it researches Polymarket bets by pulling Pipeworx data. Specifies inputs (slug, URL, question text) and output (evidence packet + comparison). Differentiates from siblings by focusing on Polymarket bet 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?

Explicitly lists use cases: 'should I bet on X?', 'what does the data say?', 'is there edge?'. Highlights that this tool is the core demo product and agents using it convert better than 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?

With no annotations, the description carries full burden. It discloses the data returned (revenue, net income, etc. for companies; adverse-event counts, etc. for drugs) and mentions output format (paired data + URIs). This is sufficient for an agent to understand behavior without hidden surprises.

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-loads the core purpose, and every sentence adds unique value. No fluff or 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?

The tool has no output schema, so the description needs to cover return values. It mentions paired data and resource URIs, but the exact structure is not detailed. However, for a comparison tool this level of detail is adequate 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?

Both parameters have descriptions in the input schema (100% coverage). The description adds value by providing concrete examples (e.g., tickers for companies, drug names) and clarifying the enum values, making the parameter usage clearer.

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

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

The description clearly states the tool's action ('Compare 2–5 entities side by side') and distinguishes between entity types with specific metrics per type. It is unambiguous and 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?

The description implies when to use it (for side-by-side comparison) and mentions efficiency gains ('Replaces 8–15 sequential agent calls'). However, it does not explicitly state when not to use it or suggest 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a search operation that returns relevant tools with names and descriptions, and it implies a ranking mechanism ('most relevant tools'). However, it lacks details on error handling, rate limits, or authentication needs, which are important for a tool with no annotation coverage.

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

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

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage guidelines without unnecessary details. Every sentence earns its place by providing critical information for agent decision-making, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity (search functionality with 2 parameters), no annotations, and no output schema, the description is reasonably complete. It covers the tool's purpose, usage context, and behavioral aspects like return format. However, it could improve by mentioning output structure or error cases, which are gaps given the lack of output schema and 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?

The schema description coverage is 100%, so the schema already documents both parameters ('query' and 'limit') thoroughly. The description adds minimal value beyond the schema by mentioning the natural language aspect of the query, but it doesn't provide additional syntax, format details, or usage examples that aren't already in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and explicitly distinguishes it from sibling tools by emphasizing its role as a discovery mechanism ('Call this FIRST when you have 500+ tools available'). It goes beyond a tautology by explaining the search functionality and the context of a large tool catalog.

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

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

The description provides explicit usage guidelines: it specifies when to use this tool ('when you have 500+ tools available and need to find the right ones for your task') and when to call it ('Call this FIRST'), offering clear context for its application. It implicitly suggests alternatives by positioning itself as an initial step, though it doesn't name specific sibling tools like 'search_packages'.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool returns `pipeworx://` citation URIs and lists included data (SEC, XBRL, patents, news, LEI). It implies a read-only operation but does not explicitly state idempotency, error handling, or rate limits. Overall, it provides adequate transparency for a profile query tool.

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

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

The description is concise (4 sentences) and front-loaded with the primary purpose. It efficiently conveys scope, input constraints, and an alternative tool without redundancy.

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

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

Given the complexity of bundling multiple data sources and the absence of an output schema, the description adequately explains what the tool returns (pipeworx URIs) and which data is included. It mentions the tool replaces many sequential calls. However, it could detail the response structure or potential size limits for 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% with descriptions for both parameters. The description adds value by explaining the `type` enum (only company supported) and elaborating on `value` (ticker or CIK, with a note that names are unsupported, recommending `resolve_entity`). This goes beyond the schema, earning a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: fetching a full entity profile across Pipeworx packs. It specifies supported data sources for companies and explicitly replaces 10–15 sequential calls, distinguishing it from the sibling tool `usa_recipient_profile` (mentioned as an alternative for federal contracts).

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

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

The description advises when to use this tool (for comprehensive profile) and when not to (federal contracts, use `usa_recipient_profile` instead). It also provides input guidance, noting that names are unsupported and directing users to `resolve_entity` as a prerequisite.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether deletion is permanent, reversible, requires specific permissions, or has side effects (e.g., affecting other data). This is a significant gap for a destructive tool with zero annotation coverage.

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

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

The description is a single, efficient sentence ('Delete a stored memory by key.') that is front-loaded with the core action and resource. There is zero waste or redundancy, making it highly concise and well-structured.

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

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

Given the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't address critical aspects like deletion consequences, error handling, or return values, which are essential for safe and effective use by 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 schema description coverage is 100%, with the single parameter 'key' documented as 'Memory key to delete'. The description adds no additional meaning beyond this, such as key format or examples. Since the schema does the heavy lifting, the 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 action ('Delete') and the resource ('a stored memory by key'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'recall' (which likely retrieves memories) or 'remember' (which likely stores them), though the verb 'Delete' implies distinction from read operations.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing memory key), exclusions, or refer to sibling tools like 'recall' for retrieval or 'remember' for storage, leaving usage context unclear.

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

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

Annotations already show read-only, idempotent, non-destructive behavior. Description adds that it fetches page, extracts title/description/key links, and emits standard markdown format. Some behavioral context added 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?

Two sentences: first covers purpose and process, second lists use cases. No wasted words, front-loaded, 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?

Tool is simple with 2 params and no output schema. Description covers output format (single text blob) and use cases. No missing information for an agent to decide.

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 already explaining url and max_links. Description does not add extra parameter meaning but is not necessary given schema completeness.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with specific verb 'Generate' and resource 'llms.txt file for any URL'. It distinguishes from siblings like 'ai_visibility_check' by focusing on standard file creation.

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 use cases: getting a client's site indexed, drafting for own project, or auditing competitors. No exclusions or alternatives mentioned, but 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool's function but lacks details on authentication needs, rate limits, error conditions, or response format. While it mentions the period parameter, it doesn't explain behavioral aspects like what happens with invalid periods or how results are structured.

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

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

The description is a single, efficient sentence that clearly communicates the tool's purpose with zero wasted words. It's appropriately sized for a simple read operation and front-loads the essential 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 read tool with 2 parameters and 100% schema coverage, the description is adequate but has gaps. Without annotations or output schema, it should ideally mention response format or data structure. The description covers basic functionality but lacks completeness for full 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema by mentioning period examples, but doesn't provide additional semantic context about parameter interactions or constraints. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('Get the download count') and resource ('for an npm package') with scope ('over a given period'). It distinguishes from sibling tools like 'get_package' (likely general package info) and 'search_packages' (search functionality) by focusing specifically on download metrics.

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 for retrieving download statistics with time-based filtering, but provides no explicit guidance on when to use this tool versus alternatives like 'get_package' (which might include download data) or 'search_packages'. No exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention permissions, rate limits, error conditions, or what happens if the package doesn't exist. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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

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

The description is a single, efficient sentence that front-loads the core purpose and includes specific examples of metadata fields. Every word earns its place with no redundancy or unnecessary elaboration.

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 (single parameter, no output schema, no annotations), the description is minimally adequate. It explains what metadata is returned but doesn't cover behavioral aspects like error handling or performance characteristics. The absence of an output schema means the description should ideally mention return format, but it doesn't.

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

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

The schema description coverage is 100%, with the single parameter 'name' fully documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema, so it meets the baseline of 3 for high schema coverage without compensating value.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed metadata for a specific npm package'), and lists specific metadata fields (version, description, dependencies, homepage, repository). However, it doesn't explicitly distinguish this from sibling tools like 'get_downloads' or 'search_packages', which likely serve 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?

The description provides no guidance on when to use this tool versus alternatives like 'search_packages' or 'get_downloads'. It doesn't mention prerequisites, exclusions, or comparative use cases, leaving the agent to infer usage from the tool name and description alone.

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

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

No annotations are provided, so the description carries full burden. It discloses a rate limit ('5 messages per identifier per day') and notes the tool is 'Free', implying no cost. However, it lacks detail on whether feedback is stored, if responses are sent, or if authentication is needed. The description adds some value but is not comprehensive.

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

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

The description is three sentences, each serving a distinct purpose: stating the action, providing usage guidance, and noting restrictions. It is front-loaded with the primary function and contains no redundant or vague wording.

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 there is no output schema and the tool is relatively simple (feedback submission), the description adequately covers purpose, usage constraints, and parameter advice. The nested 'context' parameter is optional and well-documented in the schema. Minor omissions (e.g., anonymity, response nature) prevent a perfect score.

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

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

The input schema has 100% coverage with detailed descriptions for each parameter (e.g., 'type' enum with explanations, 'message' with length limit). The tool description adds extra guidance ('Describe what you tried...'), which enhances understanding of the 'message' parameter beyond the schema. Baseline is 3 due to high schema coverage, but the additional advice raises the score.

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 'Send feedback to the Pipeworx team' and lists use cases ('bug reports, feature requests, missing data, or praise'), making the verb and resource clear. It distinguishes this tool from sibling tools (e.g., ask_pipeworx, discover_tools) which serve 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?

The description provides clear guidance on when to use the tool (bug reports, features, etc.) and what to include/exclude ('Describe what you tried in terms of Pipeworx tools/data — do not include the end-user's prompt verbatim'). It also mentions a rate limit but does not explicitly contrast with alternative tools; however, sibling tools have distinct purposes, reducing ambiguity.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive. The description adds useful context: self-aggregating signal, no PII, cached, and derived from CF analytics. 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 concise (one lead sentence plus bullet points and a caching note) and well-structured. Every sentence adds value, and the most important 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 what is returned (top tools, top packs, total call volume) and hints at structure (pack, tool, count). For a simple tool with one parameter, this is sufficient. Slight deduction for not specifying exact format.

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 valuable guidance on the 'window' parameter: default, options, and interpretation ('shorter windows surface what's hot; longer show steady-state demand'). This enriches the schema 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 uses specific verbs ('returns', 'discovering', 'confirming', 'seeing') and clearly states it returns top tools, top packs, and total call volume. It distinguishes itself from siblings like 'discover_tools' by focusing on trending usage over time windows.

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 listed, and caching behavior is noted. While it lacks explicit when-not-to-use instructions, the purpose is clear enough for an agent to decide. Slight deduction for not mentioning 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 and destructiveHint=false. The description adds behavioral context: it checks monotonicity violations and returns ranked opportunities with trade direction and reasoning. It does not contradict annotations and provides useful detail beyond the structured fields.

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

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

The description is well-structured and front-loaded with the core purpose. It uses about 5 sentences to convey modes, examples, and return value. While efficient, it could be slightly more concise, but it earns its length by providing essential guidance.

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 the return format (ranked opportunities with trade suggestion and reasoning). It covers both modes and their use cases. It lacks mention of prerequisites or performance, but overall it is sufficiently complete for an arbitrage detection tool with read-only 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 descriptive parameter definitions. The description adds extra context by clearly mapping each parameter to a mode (event slug vs. topic) and explaining their roles, which goes beyond the schema's basic 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: 'Find arbitrage opportunities on Polymarket by checking for monotonicity violations across related markets.' It distinguishes two modes (event and topic) and contrasts with sibling tools like 'bet_research' and 'validate_claim' by focusing on arbitrage detection across markets.

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

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

The description explicitly outlines TWO MODES and when to use each: event for a single event slug, topic for cross-event arbitrage. It explains why topic mode is necessary for cases where single-event mode misses monotonicity checks, providing clear guidance on alternative usage.

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

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

The description goes beyond annotations by detailing the V1 model (lognormal from FRED + coinpaprika price), the process (scans top markets, groups by asset, fetches price history once), and output (top N ranked by edge magnitude with trade direction). 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 well-structured: first sentence states main action, then model details, then process. It is front-loaded and informative without being excessively 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 no output schema, the description explains the return value (top N ranked by edge magnitude with suggested trade direction). It covers main aspects but lacks details on failure cases or dependencies.

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 additional semantic meaning beyond the schema descriptions for limit, window, and min_edge_pp.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price. It explicitly states its purpose for discovering betting opportunities, distinguishing it 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 provides context by saying it's built for the 'what should I bet on today' question and helps avoid paging through hundreds of markets. However, it does not explicitly differentiate from alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructiveness. Description augments with return format (leg prices, spread in pp). 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 with clear structure: purpose, usage context, return format. Slightly verbose in listing topics but well-organized with bullet-like formatting.

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

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

No output schema; description covers return details (prices, spreads). With annotations providing safety and idempotency, this is complete for a read-only data 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 100% with descriptions. Description adds value by explaining how topic, kalshi_event_ticker, and polymarket_event_slug interact, including override behavior and 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?

Clear verb+resource: cross-venue spread. Distinguishes from siblings by specifying venues and two modes (topic vs explicit). Lists example topics and explicit ticker formats.

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

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

Explains when to use: capturing arb signals from price deltas. Describes two modes (topic shortcuts for common events, explicit tickers for custom pairs). Does not explicitly state when not to use, but modes cover most cases.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: retrieving memories by key or listing all memories, with persistence across sessions. However, it doesn't mention potential limitations like memory size constraints or retrieval failures.

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 perfectly concise with two sentences that each earn their place. The first sentence explains the core functionality, and the second provides usage context. There's zero wasted language and it's front-loaded with the most important 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 retrieval tool with 1 parameter and 100% schema coverage, the description is nearly complete. It explains what the tool does, when to use it, and the parameter semantics. The only minor gap is the lack of output format description, but given the tool's simplicity, this is acceptable.

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

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

The schema description coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining the semantic difference between providing a key (retrieves specific memory) and omitting it (lists all keys), which goes beyond the schema's technical documentation.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings like 'remember' (which stores) and 'forget' (which deletes) by focusing on retrieval operations.

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

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

The description provides explicit guidance on when to use this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter to list all memories, giving clear usage instructions.

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

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

No annotations provided, so the description carries full burden. It details parallel fan-out to three sources (SEC, GDELT, USPTO), mentions output fields (structured changes, total_changes, URIs), and explains since formats. Lacks error handling or rate limits, but is otherwise transparent.

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

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

The description is concise with four sentences, each adding distinct information. It is front-loaded with purpose, then details behavior. No redundant or unnecessary text.

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

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

Given the tool's complexity (multiple sources, input formats) and lack of output schema, the description covers key aspects: supported sources, input syntax, output structure. Missing details like pagination or limits, but acceptable for a monitoring tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining since formats with examples ('7d', '30d'), noting type is limited to 'company', and clarifying value can be ticker or CIK. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: finding recent changes about an entity since a given time. It specifies the resource (entity) and action (what's new), and differentiates from siblings like entity_profile by focusing on change monitoring.

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 recommends using the tool for 'brief me on what happened with X' or change-monitoring workflows. While it doesn't list when not to use it or alternatives, the guidance is clear and contextual.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the storage mechanism ('session memory'), persistence differences based on authentication ('Authenticated users get persistent memory; anonymous sessions last 24 hours'), and the cross-call context utility. It doesn't cover potential limitations like storage limits or error conditions.

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

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

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose, usage, and behavioral details. Every sentence earns its place: the first states the core function and use cases, the second adds crucial behavioral context about persistence. No wasted words.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and key behavioral traits. However, it doesn't specify return values or error handling, which would be helpful despite the lack of output schema. The persistence details compensate well for missing 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 description coverage is 100%, with both parameters ('key' and 'value') well-documented in the schema. The description doesn't add significant meaning beyond what the schema provides, though it reinforces the parameter purposes through examples in the usage context. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verb ('Store') and resource ('key-value pair in your session memory'), and distinguishes it from sibling tools like 'recall' (which likely retrieves) and 'forget' (which likely deletes). It specifies what type of data can be stored ('intermediate findings, user preferences, or context across tool calls').

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

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

The description provides clear context for when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but doesn't explicitly mention when not to use it or name alternatives (e.g., 'recall' for retrieval or 'forget' for deletion). It distinguishes from siblings by function but not through explicit 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?

Given no annotations, the description carries the full burden. It discloses accepted input formats (ticker, CIK, name), returned fields (ticker, CIK, name, resource URIs), and v1 limitations (only company type). Missing details on permissions, rate limits, or error handling, but transparent enough for typical use.

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 long, front-loaded with the main action, and every phrase adds value (e.g., 'in a single call', 'Replaces 2–3 lookup calls'). No fluff 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?

The tool has 2 parameters, no output schema, and a straightforward purpose. The description covers input, output, and v1 scope adequately for an agent to select and invoke correctly without needing additional 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% with descriptions for both parameters, and the description adds significant value: explains v1 constraints, gives concrete examples, and clarifies that value can be ticker, CIK, or name—enhancing 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?

Description clearly states verb (resolve) and resource (entity to canonical IDs) and distinguishes itself by noting it replaces 2-3 lookup calls, making purpose specific and differentiated from siblings.

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

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

Description implies usage as a single-call replacement for multiple lookups, providing clear context. However, it lacks explicit when-not-to-use or direct alternatives among the sibling tools, so it stops short of full 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, openWorldHint, idempotentHint. Description adds: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns ranked list with score, confidence, signal density. This provides substantial behavioral detail 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?

Two sentences that front-load purpose and follow with usage context and output details. No extraneous 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?

Despite no output schema, description explains return structure (ranked list with score, confidence, signal density). Annotations cover safety. All parameters described with additional usage hints. Comprehensive 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 description coverage is 100%. Description adds context: first entity is 'subject', models default to workers-ai, context disambiguates names. This enhances understanding beyond the parameter descriptions.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side', with specific verb and resource. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general).

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

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

Provides clear context for competitive AI-marketing audits and includes an example question. Implicitly contrasts with ai_visibility_check but does not explicitly state when not to use it.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return fields (name, description, etc.), which is helpful, but doesn't cover important aspects like rate limits, authentication needs, error handling, or pagination behavior for a search operation.

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

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

The description is a single, efficient sentence that front-loads the core purpose and includes key return information. Every word earns its place with zero waste, making it easy for an agent to parse quickly.

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 search tool with no annotations and no output schema, the description provides basic purpose and return fields but lacks details on behavioral traits, usage context, and error handling. It's minimally adequate but has clear gaps given the tool's complexity and lack of structured metadata.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as search syntax examples or how the query interacts with the npm registry. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the action ('Search the npm registry for packages') and resource ('packages'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_package' which might retrieve specific package details rather than search across packages.

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

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

No guidance is provided about when to use this tool versus alternatives like 'get_package' or 'get_downloads'. The description lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.

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 return values (verdict, value with citation, percent delta) and composite nature (replaces 4-6 calls). No annotations, but description adequately covers behavior for a read-only tool.

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

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

Three sentences, each with unique value: purpose, scope, outputs. 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?

For a single-param tool with no output schema, description covers inputs, supported claims, output format, and comparative advantage. No gaps.

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

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

Single parameter with 100% schema coverage. Description adds example values, but schema already defines 'claim' well. No additional semantic depth beyond 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?

Clear verb-resource pair ('fact-check a claim') with specific domain (company-financial) and sources (SEC EDGAR). Distinguishes itself by replacing sequential agent calls.

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

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

Explicitly states supported claim types (revenue/net income/cash for public US companies), guiding appropriate use. Does not name sibling alternatives, but scope is well-defined.

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