Abuseipdb

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it returns per-model {score, confidence, signals, raw_response} plus combined view, notes cost implications for Anthropic, and explains default model behavior. No contradiction with annotations.

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

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

Three sentences, front-loaded with action and output, no fluff. Every clause earns its place, efficiently covering purpose, usage, and return format.

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

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

No output schema exists, so description must cover return values. It does by listing per-model fields and combined view. It covers the main use case and parameter nuances. Could mention error handling or edge cases like missing API key, but not essential.

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%, giving baseline 3. The description adds examples for entity (e.g., 'Pipeworx'), clarifies that _apiKey is only needed when anthropic is in models, and explains the context parameter for disambiguation. This adds meaning beyond the schema.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for business/brand visibility' along with scoring 0-100. It distinguishes from siblings by focusing on AI visibility auditing rather than other tools like deep research or entity profile.

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

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

The description explicitly says when to use it: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and the optional Anthropic probe with a BYO key. It lacks explicit 'when not to use' but provides sufficient context for appropriate invocation.

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 context about routing to many tools, returning structured answers with citations, and working on all tiers. This enhances transparency beyond annotations but does not contradict 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?

The description is front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and is well-structured with examples and sibling comparisons. It is somewhat verbose but every section adds value; minor redundancy could be trimmed.

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 across thousands of sources) and the lack of an output schema, the description fully covers use cases, inputs, outputs (structured answer with citations), and comparisons to siblings. It is complete and leaves no critical gaps.

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

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

Schema coverage is 100% with clear descriptions and aliases for the question parameter. The description adds value through examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and contextualizes the type of questions, helping the agent formulate the parameter correctly.

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

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

The description clearly states the tool is for asking questions about current/historical data from 4,774 tools across 1,242 sources, with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance, including example queries and conditions (e.g., factual questions about real-world entities). It also specifies when to step up to alternatives, offering clear usage boundaries.

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 readOnly, idempotent, openWorld. The description goes beyond by detailing refusal behavior, possible refusal reasons, the extra LLM call overhead, and the explicit refusal mechanism. No contradiction with annotations; adds significant context.

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

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

The description is front-loaded with the core concept and uses concise sections: purpose, mechanism, return format, usage guidance, and tradeoff. While informative, it contains some redundancy (e.g., 'Same routing as ask_pipeworx' repeated context from sibling), but every sentence serves a purpose.

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

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

Given no output schema, the description provides a complete specification of return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also explains the underlying routing and extraction mechanism, making it fully self-contained for an AI agent.

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

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

Schema coverage is 100% with detailed descriptions for the single question parameter and its aliases. The description adds 'Your question in natural language' which is already in the schema, providing no new semantic meaning beyond what the schema offers. 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 is a hallucination-resistant answer mode for high-stakes reads, extracting answers only from tool results with evidence. It differentiates from the sibling 'ask_pipeworx' by specifying it returns refusals when data doesn't directly answer, making its purpose distinct and precise.

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 defines when to use: for answers that will be quoted, cited, or acted on where fact invention is unacceptable. Also states a clear alternative: prefer 'ask_pipeworx' for casual lookups, citing the extra LLM call cost as a tradeoff.

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 safety (readOnly, idempotent, non-destructive). The description adds extensive behavioral details: how it resolves markets, classifiers, fan-out examples, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, low-confidence short-circuit, closed market handling, wide-spread liquidity warnings, and resolution-rule risk (cancellation rules). This goes well beyond the annotations.

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

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

The description is well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads purpose and usage. However, it is excessively long and contains redundant details (e.g., multiple examples of fan-out). Every sentence earns its place, but brevity could be improved without losing key information.

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

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

Given the tool's complexity (multiple fan-out paths, edge cases, safety mechanisms), the description is highly complete. It covers resolution, evidence sources, cancellation rules, liquidity warnings, error states (low confidence, closed markets), and response field details. Since there is no output schema, the description compensates thoroughly.

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% (3 parameters with descriptions). The description reinforces parameter meanings with examples and contextual notes (e.g., 'quick = 2-3 evidence sources, thorough = full fan-out' for depth; explanations of market input types; include_raw usage). While the schema already provides base info, the description adds value by clarifying behavior.

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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The purpose is specific and distinguishes it from siblings 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 clearly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-out for different bet types. However, it does not explicitly mention when not to use it or alternatives, but the context is sufficient.

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

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

Annotations (readOnlyHint, idempotentHint) indicate safe, non-destructive behavior. The description adds value by specifying the output fields (abuse confidence score, ISP, usage type, country, reports, last reported date) and listing an example input. 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 extremely concise: two sentences covering purpose, output fields, and an example. Every word adds value. It is front-loaded with the primary action and resource.

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

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

Given the tool has only 2 parameters, an output schema is implicitly described in the return fields. The description covers what the tool does, what it returns, and provides an example. It is mostly complete, though could include a brief note about data source reliability or API key handling.

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

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

Schema coverage is 100% with clear descriptions for both parameters ('ip' and '_apiKey'). The description includes an example ('check_ip("8.8.8.8")') but does not add extra meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Check' and the resource 'IP address against the AbuseIPDB database'. It lists the returned fields (abuse confidence score, ISP, etc.), which distinguishes it from sibling tools like 'report_ip' that handle reporting. The purpose is specific and unambiguous.

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 an example but does not explicitly state when to use this tool versus alternatives (e.g., 'ai_visibility_check', 'scan_dependency'). It lacks guidance on prerequisites or when not to use it. The usage context is implied but not clearly defined.

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. The description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs) and sorting behavior, which enriches transparency beyond annotations alone. However, it doesn't mention rate limits or any potential side effects.

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: starts with examples and a usage directive, then details data sources and behavior. Every sentence adds value without redundancy. Length is appropriate 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 has only two parameters with full schema coverage, no output schema is needed. The description covers all essential aspects: purpose, data sources per type, sorting, citation URIs, and replacement for sequential lookups. No gaps for an AI 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?

Schema coverage is 100%, so baseline is 3. The description adds significant meaning by explaining what data each 'type' retrieves and providing usage examples for 'values' (tickers vs. drug names, min/max items). This goes well beyond the schema's simple type/enum 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 uses specific verbs ('compare', 'side-by-side comparison') and resources ('companies or drugs'), and clearly distinguishes from siblings by stating it replaces 8–15 sequential lookups. Examples and query patterns further clarify purpose.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. Also explains what each 'type' value does, aiding selection between company vs. drug comparisons.

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 readOnly, openWorld, idempotent, non-destructive. The description adds critical context: account requirement (free tier, paid for thorough depth), 15-60s response time, output format (findings packet with evidence, confidence, gaps[]), and that it does not invent data. 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?

Well-structured, front-loading critical prerequisites (account) and alternatives. However, somewhat verbose with redundant emphasis like 'this is NOT open-web search'. Could be trimmed slightly without losing meaning.

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

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

Given complexity (2 params, no output schema, rich annotations), the description covers input, output, behavior, limitations, prerequisites, alternatives, and performance. Provides a complete mental model for correct agent usage.

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

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

Schema covers 100% of parameters. Description adds value by explaining depth enum values (quick=3, standard=5, thorough=8 with paid requirement) and that question can be broad/multi-part. Slightly exceeds baseline due to actionable nuance.

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 performs grounded multi-source research across 1242 structured data sources, decomposes questions, and routes to 4774 tools in parallel. It distinguishes from siblings like ask_pipeworx by specifying different use cases (single lookup, breaking news).

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 tells when to use this tool vs. ask_pipeworx: when not signed in, for single lookups, and for breaking/current news. Also warns that topics outside structured catalog yield empty gaps, guiding appropriate 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond annotations by stating the tool returns 'full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This contextualizes the output and confirms it is a safe, non-destructive 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 well-structured: purpose first, then usage guidelines, then return value details. It is fairly concise but includes a long list of example domains, which is informative but slightly verbose. Every sentence contributes value.

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

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

Given no output schema, the description fully explains what is returned: tool names, descriptions, and full input schemas with examples. It covers input, output, and intended usage. No gaps for this tool's purpose.

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 does not add new meaning beyond what the schema already provides; it simply restates that query accepts multiple aliases. No extra semantic context for 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?

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (browse, search, look up, discover) and the output (top-N relevant tools with schemas). This uniquely identifies the tool as a discovery mechanism, distinct from siblings which are individual task-specific 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: 'Call this FIRST when you have many tools available and want to see the option set.' It lists numerous example use cases (SEC filings, FDA drugs, etc.) and implicitly indicates not to use it when you already know which tool you need. This gives clear context for selecting this tool over alternatives.

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

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

Discloses data sources (SEC, XBRL, USPTO, etc.), return structure (cik, company_name, filings, fundamentals, patents with sunset caveat, news, LEI), and limitations (patents sunset, names unsupported). Annotations already declare read-only, but description adds rich behavioral context.

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

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

The description is front-loaded with example queries and usage guidance. While somewhat lengthy, every sentence adds value (examples, input rules, return details, limitations). No fluff, but could be slightly streamlined.

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

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

Given the tool has no output schema, the description fully enumerates return fields and their structure. It also covers edge cases (patent sunset, unsupported name input). This is complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, and the description adds meaning: specifies allowed values for 'value' (ticker or CIK), clarifies that names are not supported, and explains the 'type' parameter is restricted to 'company'. This goes beyond the enum and type definitions.

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: 'full cross-source profile of a US public company' and lists specific data sources and return fields. It distinguishes itself from sibling tools by explicitly recommending this tool over chaining individual lookups for holistic queries.

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 ('when user asks for a holistic view') and when not to use (names not supported, use resolve_entity first). Also warns against chaining and gives clear input requirements (ticker or CIK only).

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the context of clearing sensitive data, but the core behavior (deletion) is already implied by 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 concise sentences with front-loaded action. Every sentence is necessary and 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?

For a simple tool with one required parameter and no output schema, the description covers purpose, usage guidelines, and relationships to siblings, making it complete.

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

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

Schema coverage is 100% and parameter description is clear in schema. Description does not add new information about the parameter beyond what schema 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 'Delete a previously stored memory by key', using a specific verb and resource. It also distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with siblings, offering clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown, providing 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?

Three sentences with no wasted words. First sentence states purpose and outcome, second explains the process, third lists use cases. Well-structured and front-loaded.

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

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

Given the tool's simplicity, the description covers behavior, use cases, and output format. No output schema exists, but the description explains output is a 'single text blob' in 'standard llms.txt markdown format', which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning for 'url' or 'max_links' beyond what is in the schema, just restating the same 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 generates a production-ready llms.txt file for any URL, specifying the verb 'Generate' and the resource 'llms.txt file'. It distinguishes from sibling tools by focusing on this specific output format.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't mention when not to use, the use cases are clear and no direct sibling tool overlaps.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, read-only behavior. The description adds value by clarifying the blacklist is based on most-reported IPs and returns confidence scores.

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 short sentences that are front-loaded with purpose and zero waste. Every sentence adds value.

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

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

Given the simple schema, rich annotations, and output schema, the description adequately covers the tool's purpose, return content, and use case without missing essential 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%, so the description does not need to elaborate on parameters. The schema already explains 'limit' (default/max) and '_apiKey'.

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

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

The description clearly states the verb 'Get', the resource 'AbuseIPDB blacklist', and specifies it returns IPs with abuse confidence scores. It distinguishes from sibling tools like 'check_ip' which are for single IP checks.

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 'Useful for building blocklists', which provides a clear use case. However, it does not explicitly exclude alternative tools or specify 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=true, idempotentHint=true, destructiveHint=false. Description adds that default is active subscriptions and lists returned fields, complementing 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: first states purpose and return fields, second gives usage guidance. No wasted 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?

No output schema, but description lists returned fields. Adequate for a simple list tool with annotations and schema coverage. Could mention pagination or ordering, but not essential.

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

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

Schema covers 100% of parameters, and the description does not need to add extra meaning. The single parameter is a simple boolean with clear 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?

Description clearly states it lists active subscriptions and enumerates return fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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: review before adding more or find an ID to cancel. Does not explicitly state when not to use, but context from sibling tools makes it clear.

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

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

Annotations are non-informative (all false). The description adds key behavioral traits: free, doesn't count against quota, rate-limited to 5 per identifier per day. 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?

Every sentence conveys necessary information. Front-loaded with the core action ('Tell the Pipeworx team...'), then usage conditions, then details on type/message. No redundant or missing parts.

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 (3 params, 1 enum, nested object) and no output schema, the description covers all needed aspects: when, what, how, constraints. The agent has full context to use 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%, but description adds value by explaining each enum value for 'type' in practical terms (e.g., 'data_gap = data Pipeworx does not currently expose') and provides guidance for 'message' to be specific. The 'context' object purpose is clarified.

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 sends feedback (broken, missing, praise) and distinguishes it from sibling tools, which are mostly data query tools. It specifies exact use cases: bug, feature, data_gap, praise, and other.

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 tells when to use (wrong data, missing tool, positive note) and what to avoid (don't paste end-user prompt). Also mentions rate limits and quota relevance, helping the agent decide when to invoke.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and data structure (pack, tool, count). 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?

Four sentences, front-loaded with the primary action, each sentence adds distinct value. No redundancy or fluff.

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

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

Given no output schema, the description adequately explains return content (top tools, packs, call volume) and caching behavior. Sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% with one parameter (window) having enum and basic description. The description adds functional differentiation: shorter windows for hot items, longer for steady-state demand, enhancing the schema's meaning.

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

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

The description clearly states the tool returns trending data on what other AI agents are calling, specifying the resources (top tools, top packs, total call volume) and the time windows. It uniquely distinguishes from siblings by focusing on aggregate trend 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?

Explicitly provides three concrete use cases for when to use this tool (discovering hot data sources, confirming canonical choices, aligning use cases). Lacks explicit when-not or alternative tools, but the guidance is clear and actionable.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: internal logic (Jaccard similarity, partition filter), fill check against live depth, and response structure. It warns about not trading when realizable edge ≤0. 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 fairly long but well-structured: a one-line summary, then mode-by-mode explanations, followed by details on semantic anchor, partition filter, response, and fill check. It uses bullet points effectively and front-loads the main purpose. Could be slightly more concise, but appropriate for the 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?

No output schema is provided, so the description explains the response format (opportunities[], partition_check{}). It also covers fill check logic and references polymarket_fill_risk for custom sizing. Given the tool's complexity and missing output schema, the description is fairly complete, though it could mention error handling or edge cases.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains what happens with no args (trending_scan), provides examples for event/topic parameters, and describes internal processing (walking child markets, Jaccard similarity threshold). This enriches the agent's understanding of parameter usage.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via specific methods (monotonicity violations + partition-sum checks). It distinguishes between three modes (no args, event, topic) and explains their differences, making the tool's purpose unambiguous and distinct from siblings.

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

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

The description provides explicit guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event scan) and explains trade-offs (cross-event catches patterns single-event misses). It also warns about fill check and references polymarket_fill_risk for custom sizing. However, it does not explicitly state when not to use this tool relative to 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 show readOnlyHint, openWorldHint, idempotentHint, destructiveHint=true. The description adds extensive behavioral context: caching (1h KV), diagnostics for why segments are empty, model family descriptions, and why Fed bets are excluded. This greatly exceeds what annotations provide.

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

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

The description is very long and dense, with detailed explanations of model families and knobs. While it's front-loaded with purpose, it could be more concise. Some redundancy exists (e.g., repeated knob descriptions). It earns its place but could be tightened.

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 9 parameters and no output schema, the description is thorough. It explains the output structure (by_segment, diagnostics, fed_candidates) and why Fed bets are surface-level but excluded from ranking. It even explains why partitions have kelly_fraction_half=0. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning to parameters like min_kelly (explains it skips too-small opportunities), min_edge_pp (net of slippage), slippage_pp (explains Polymarket fees), and min_partition_leg_kelly (distinguishes from min_kelly for partitions). This is exemplary.

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

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

The description states a specific verb ('scan', 'return') and resource ('Polymarket markets', 'opportunities'). It clearly explains the tool's purpose: to find opportunities where Pipeworx data disagrees with market price, and it distinguishes itself from siblings by focusing on daily discovery without paging through hundreds of 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 says it's built for 'what should I bet on today' and mentions tradeable-edge knobs and filtering. It implies usage for daily betting discovery but doesn't explicitly compare to alternatives like polymarket_arbitrage or polymarket_edge_tracker. The context is clear, but exclusions are not stated.

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

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

The description discloses important behavioral traits beyond annotations: it uses snapshots with a 60-day TTL, data gaps occur when no scan happened, and decay is based on daily closes not intraday. This adds significant value beyond the readOnlyHint annotation.

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 purpose and structured logically (args, response, limits). While somewhat verbose, every sentence provides unique information. It could be slightly trimmed but remains efficient for the 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?

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) with fields and meaning, covers edge cases (gaps, TTL), and provides all necessary context for an agent to invoke the tool correctly.

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

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

The description repeats and reinforces schema details ('days' lookback default 14 max 30, 'window' snapshot family default 1wk) and also explains how parameters affect the output (e.g., window family determines snapshot set). It adds context beyond the schema, which has 100% 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description implies when to use the tool (to understand edge age and decay) and contrasts with a single current edge snapshot, but it does not explicitly name alternatives or state when not to use it. The context is clear, though lacking explicit exclusions.

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 as true, and destructiveHint false. The description adds substantial behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and warns about forced directional risk in basket mode. 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 long but well-structured with clear sections for single-market and basket modes. It front-loads key info and uses bold for emphasis. However, some repetition (e.g., side options listed twice) could be trimmed. It earns its length given 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 no output schema, the description fully specifies all return fields, explains input parameters and their interactions, and covers usage guidance. It is complete for a complex tool that checks order book depth and basket risks.

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: it explains the requirement for one of market or event, default values, interpretation of size_usd in both modes (spend vs target proceeds vs settlement notional), and how side auto-detects in basket mode. This adds significant 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 as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check.

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 tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial basket fills create directional risk), providing clear exclusion criteria.

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

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

Description goes far beyond annotations by detailing leg-by-leg price comparison, spread computation, compatibility_warning triggers, temporal alignment checking, and skipped cross type/subtype counters. Discloses that the tool does not create or modify any data, consistent with readOnlyHint and no contradictions.

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

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

The description is dense with valuable information and well-structured: first sentence states purpose, then modes, response fields, safety fields. However, it is somewhat verbose, repeating warnings (e.g., 'pre-mapped ≠ tradeable' is redundant with earlier caution). Still, every sentence earns its place.

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

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

Despite lacking an output schema, the description thoroughly explains all response components (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It addresses potential issues like non-equivalent bet shapes and temporal gaps, making the tool fully understandable for an AI agent.

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

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

Schema description coverage is 100%, but the description adds value by explaining the override behavior (explicit tickers override topic), giving concrete examples (e.g., 'KXFED-26OCT'), and listing all 10 topic shortcuts. While the schema already has descriptions, the description enriches understanding of how parameters interact.

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 spread between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than pure arbitrage.

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

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

Explicitly tells when to use topic vs explicit modes, warns that many pre-mapped topics return compatibility warnings, and advises that real spreads are rarer than the shortcut list suggests. Also explains how to interpret safety fields (compatibility_warning, temporal_alignment) to decide if the spread is meaningful.

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. Description adds scoping info (by identifier) and pairing with remember/forget, providing useful context beyond annotations.

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

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

Three sentences, front-loaded with purpose, no unnecessary words. Efficient and structured well.

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 values (value or list of keys) and is complete for an agent to use effectively.

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

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

Schema coverage is 100%; description adds meaning by explaining key is optional and omitting lists all keys, clarifying the parameter's purpose.

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 values saved via remember or lists keys, specifying the resource (saved memories) and actions. It distinguishes from siblings like 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?

Provides clear context for when to use (look up stored context) and how to omit key for listing. Does not explicitly state when not to use, but context is sufficient given sibling 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description explains the effect of mark_read:true (flags events read so next call only shows newer ones) and lists the return fields (source, citation_uri, raw event payload). This adds context not in the schema or 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 four sentences with no filler. Each sentence serves a distinct purpose: function, return fields, parameter usage, and additional context (polling/alternative access). It is front-loaded with the core action.

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

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

Given the tool has 5 parameters (all described) and no output schema, the description covers the necessary information: what it does, what it returns, how to filter, behavioral nuance (mark_read), and external alternative. 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%, but the description adds value by providing an example for the type parameter ('e.g. 'sec_8k'') and explaining the purpose of mark_read in plain language. It does not, however, explain limit or unread_only beyond what the schema says.

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 ('Pull', 'Returns') and clearly identifies the resource ('fired events from your subscription feed', 'recent alerts'). It distinguishes itself from sibling tools like list_subscriptions by focusing on alerts themselves rather than subscriptions, and mentions an alternative access method ('same feed at GET registry.pipeworx.io/alerts.json').

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 states that 'Polls work fine' and points to an alternative endpoint for scripts/dashboards, implying when to use this tool versus direct API access. However, it does not explicitly specify when not to use it or compare to other tools like search_within or entity_profile.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: fans out to multiple sources with fallback logic (GDELT→GNews), PatentsView soft-fail, return structure (changes grouped by source, total_changes, citation URIs), and parameter format details.

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 with information but front-loaded with purpose and examples. It is slightly long but every sentence adds value; no redundancy. Could be tightened but still highly 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 (multiple sources, fallback, window parameter), the description covers all aspects: source details, limitations (PatentsView sunset), return structure, and alternative tool for static profiles. No gaps remain for the agent to guess.

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 schema: explains `since` formats with examples, clarifies `value` can be ticker or CIK, and gives usage hints like 'Use "30d" or "1m" for typical monitoring.' This enriches the parameter definitions.

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 as a change feed for companies in a time window, with specific examples of queries. It distinguishes from sibling tool entity_profile by explicitly stating when to use the alternative for static profiles.

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 (for 'what's new' queries) and when to use entity_profile instead. It also includes parameter usage hints (e.g., 'Use "30d" or "1m" for typical monitoring').

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 idempotent and non-destructive. Description adds that data is key-value scoped by identifier, with persistence details (authenticated persistent, anonymous 24h). This adds 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?

Four sentences: purpose, when to use, scoping/persistence, and pairing with recall/forget. No fluff, each sentence earns its place.

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

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

Simple tool (2 required params, no output schema). Description fully covers purpose, usage, persistence, and companion tools. Nothing missing.

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 clear param descriptions. Description provides examples but no additional syntax or constraints beyond schema; 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?

Description clearly states verb (save) and resource (data to reuse later), with concrete examples like resolved ticker, target address. Distinguishes from sibling tools recall and forget by specifying pairing.

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 ('when you discover something worth carrying forward... so you don't have to look it up again') and pairs with recall/forget for lifecycle. Lacks explicit when-not or alternatives beyond these, but context is very clear.

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

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

The description states the tool 'reports' an IP, which is a write operation. However, the annotations include readOnlyHint: true, which contradicts this. The description does not disclose any behavioral traits beyond what the annotations already provide, and the contradiction is a serious flaw.

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 sentences that front-load the purpose and key requirements. Every sentence adds value, and there is no wasted 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?

The description covers the purpose, key inputs, and return value. With an output schema present, it is adequately complete for the tool's complexity. It could mention more about the return format, but the output schema likely handles that.

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 detailed descriptions for each parameter. The description adds minimal extra meaning, mainly reinforcing the requirement for category IDs with examples. Hence, a 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 verb 'Report' and the resource 'abusive IP address to AbuseIPDB'. It also specifies the requirement for category IDs and the return value (updated abuse confidence score). This distinguishes it from sibling tools like check_ip and get_blacklist.

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 the required category IDs with examples (e.g., '18,22' for DDoS + SSH brute force). It implies when to use (to report an abusive IP) but does not explicitly mention when not to use or alternatives. The context is clear enough for correct 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?

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds that it cascades through several lookup endpoints, replacing multiple manual lookups, and details return values (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand for drug). No contradiction.

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

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

Well-structured with examples and clear lists. Slightly verbose but every sentence adds value. Front-loaded with use cases.

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

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

Given 2 parameters, full schema coverage, and strong annotations, the description is complete. It explains purpose, usage, parameters, and return values (despite no output schema). No gaps.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: for 'value' it explains acceptable inputs (ticker, CIK, company name; brand or generic name) and notes auto-disambiguation for company. This adds value.

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

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

The description clearly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifier.' It provides specific query examples ('What's the ticker for...', 'find the CIK for...') and distinguishes itself from siblings by focusing on ID 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Lists supported types. While it does not list when not to use, the positive guidance is strong and the context in sibling tools helps differentiate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the probing mechanism (via ai_visibility_check), ranking logic, and return fields (score, confidence, signal density), which are beyond annotation scope.

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: first states core action and ranking, second provides usage context with an example, third specifies return format. No wasted words, front-loaded with purpose, 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 specifies return fields (score, confidence, signal density). Parameters are fully described in schema (including entity count range 2-8). The description covers comparative context and subject treatment. Complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the nuance that the first entity is treated as the 'subject' for narrative, which is not in the schema. This adds value but is not extensive; parameter semantics are largely handled by 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 a concrete usage context: 'competitive AI-marketing audits' with an example question. It implies when to use (multiple entity comparison) and implicitly contrasts with single-entity alternatives, but lacks explicit when-not or exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds significant behavioral context: fan-out to two services, graceful partial failure, timing issue (5-30s for first bundlephobia measurement), and the sources_failed field. No contradictions.

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

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

The description is appropriately detailed and front-loaded with the core purpose. It is structured with a clear sentence for responsibility, usage, return fields, ecosystem scope, and behavior. Slightly verbose but each sentence carries useful information.

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

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

Given the tool's complexity (composite, multiple data sources), the description is very complete. Annotations are rich, schema covers everything, and the return fields are listed explicitly. Additional behavioral notes (timing, partial failure) ensure the agent understands edge cases.

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 reinforces that scoped packages are accepted and version defaults to latest, but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the verb 'scan' and the resource 'dependency', and distinguishes from siblings by limiting scope to npm ecosystem and pointing to deps.dev:version for other ecosystems.

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

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

Explicitly says when to use: for questions about safety, popularity, size, or cost of adding an npm package. Also provides exclusion: PyPI, Maven, etc. fall under a different tool. This gives clear context for selection.

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

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

Annotations already show readOnlyHint, idempotentHint, etc. Description adds significant behavioral details: character offsets, similarity scores, 200K char cap with truncation flag, BGE-base-en embeddings, cosine over 500-char windows. No contradictions.

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

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

Five sentences, front-loaded with purpose, each sentence contributes unique information—usage guidelines, behavioral details, pairing advice, technical limits. No redundancy or waste.

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

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

For a search tool with 3 params and no output schema, description is remarkably complete: covers purpose, when to use, how it works (embeddings, windowing), output details (offsets, scores), limitations (200K char cap), and related tool pairing. No gaps.

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

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

Schema coverage is 100% with good descriptions. Description adds value beyond schema: explains how text is used (from fetched records) and output nature (top-N passages with offsets and scores). No contradictory meaning.

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+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself by specifying the use case (records too big for prompt) and differentiating from siblings like ask_pipeworx_grounded. The purpose is unambiguous and specific.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Also provides alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' This gives clear contextual 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?

Discloses behavioral traits beyond annotations: requires auth, returns new subscription id, delivery channels and caps. Does not contradict annotations (readOnlyHint=false, etc.).

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

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

Well-structured and front-loaded with main purpose. Each sentence adds value, though some details (like delivery channels) are explained twice in slightly different ways.

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

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

Covers purpose, required params, supported types, delivery options, and limits. No output schema, but return of subscription id is mentioned. Sufficient for a 3-parameter tool.

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

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

Adds significant meaning beyond schema: provides examples for each subscription type, explains delivery options in detail (SMS cap, webhook signing). Schema coverage is 100% but description enriches 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?

The description clearly states the verb (create), resource (proactive monitoring subscription), and scope (live-data event stream). It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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 context for when to use (proactive monitoring of specific event streams) and lists supported types with configuration details. It mentions prerequisites (Pipeworx OAuth account, phone verification) but does not explicitly state when not to use or mention alternatives.

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

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

The description adds behavioral context beyond annotations: it reveals the return structure (category-bucketed example questions with tool+argument shape) and the difference between calling with and without the topic argument. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which are consistent. 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 structured with user intents, then behavior, then return details. It is somewhat long but every sentence adds value. It could be slightly more concise, but it remains organized and front-loaded.

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

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

Given no output schema, the description adequately explains the return value (category-bucketed example questions with exact tool+argument shape). It covers both invocation modes and the list of possible topic values. The tool is simple (one optional param, no nested objects), so the description is complete enough.

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% parameter coverage with a clear description of the topic parameter and its options. The description reiterates this and adds usage nuance (e.g., 'Omit for a cross-category spread'), but it does not significantly expand beyond the schema. A baseline 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 identifies the tool as the onboarding entry point for new users, listing specific user intents ('what can I ask Pipeworx?', 'give me ideas') and explaining that it returns category-bucketed example questions with tool+argument shapes. This distinguishes it from sibling tools like ask_pipeworx and 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?

The description explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two usage modes (no arguments for full spread, topic parameter for focus). It does not mention when not to use it, but the guidance 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?

The description goes beyond annotations by explaining the deactivation behavior ('row is deactivated, not deleted') and points to where historical events remain available, adding significant context beyond the annotation values.

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

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

Two concise sentences front-load the core action, with zero waste. Every sentence adds 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 single-parameter tool with no output schema, the description fully covers purpose, constraints, behavior, and post-action guidance, making it complete.

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

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

Schema coverage is 100% and the schema describes the 'id' parameter. The description adds meaning by specifying ownership context ('your own subscriptions'), but no additional format details beyond schema.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb and resource, and distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly says when to use (cancel subscription by id), ownership enforcement ('you can only cancel your own subscriptions'), and mentions an alternative for historical data via 'recent_alerts', providing clear guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint are true, and destructiveHint false. The description adds significant behavioral context: it returns a verdict (confirmed, refuted, etc.), extracted structured form, actual value with a citation, and percent delta. It also discloses the data source (SEC EDGAR + XBRL). This is valuable 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 four sentences long and includes repetitive elements (e.g., multiple examples, restating 'company-financial claims' and 'SEC EDGAR + XBRL'). It could be tightened by omitting the list of example phrases in the first sentence. It is front-loaded with the key use case, but some sentences are redundant.

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

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

Given the tool's complexity (single parameter, no output schema, annotations present), the description covers the necessary aspects: what inputs are expected, the domain of applicability, the verdict types returned, and the fact that it consolidates multiple calls. It sufficiently prepares an agent to use the tool correctly.

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

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

The input schema has 100% description coverage for the 'claim' parameter, and the description text repeats the same examples and definition found in the schema. Since the schema already provides adequate meaning, the description adds no extra semantic value. Baseline score applies.

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 for public US companies. It uses specific verbs like 'verify' and 'confirm or refute', and the examples make it unambiguous. It also differentiates itself by noting it replaces multiple sequential calls, setting it apart from sibling tools that might handle other types of queries.

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 whenever the agent needs to check whether something a user said is factually correct.' It also delimits the scope to company-financial claims (revenue, net income, cash position) from public US companies. While it does not list when not to use it or name alternative tools for other domains, the guidance is clear and contextually adequate.

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