Abuseipdb

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses important behavior: making external API calls to Anthropic, requiring a BYO key, and directly incurring Anthropic costs. It also details the return structure. This adds significant context beyond what annotations convey.

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

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

The description is three sentences, front-loaded with the core purpose, followed by configuration details and return/use cases. Every sentence contributes valuable information with no redundancy.

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

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

Given no output schema, the description provides the return structure ({score, confidence, signals, raw_response} + combined view) and outlines use cases. It covers prerequisites (_apiKey for Anthropic) and default behavior, making it complete for an agent to select and invoke 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 all parameters are already documented. The description reinforces the default model and cost implication for _apiKey, but these are also mentioned in the schema. It adds no new parameter-level semantics beyond what the 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 uses a specific verb ('Probe'), identifies the resource ('one or more LLMs'), and states the outcome ('score visibility (0-100) per model'). It also mentions return format and use cases, clearly distinguishing the tool's function from siblings by focusing on generic LLM visibility scoring.

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

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

Provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection (default Workers AI, optional Anthropic via _apiKey). However, it does not explicitly name alternative tools or state exclusions, so it falls short of a 5.

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 readOnly/openWorld/idempotent; the description adds concrete behavioral details: it routes to sub-tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and notes it works on every tier with one fast call. There is no contradiction between the description and 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?

Although longer than a minimal description, it is front-loaded with the key 'PREFER OVER WEB SEARCH' directive and densely organized into use cases, examples, and escalation paths. Every sentence contributes to tool selection or invocation, with no filler.

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

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

For a routing/default tool with no output schema, the description covers purpose, scope, use cases, alternatives, return format (structured answer with citations), and performance characteristics. It is complete enough for an agent to decide when to invoke and 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?

The schema already covers 100% of parameters with clear descriptions of the 'question' field and aliases. The description adds meaning by providing concrete example prompts and clarifying the wide range of factual inquiries that can be passed, going slightly beyond the schema's baseline.

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

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

The description clearly states a specific action: routes questions to the right one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with citation URIs. It distinguishes itself from siblings by calling itself the 'default entry point' and naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to 'PREFER OVER WEB SEARCH' for a long list of domains and provides trigger phrases like 'what is', 'look up', 'get the latest'. It gives clear when-to-use guidance vs alternatives, including when to step up to ask_pipeworx_grounded or deep_research, and how breaking news is handled.

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 that this is a full working router, not a degraded fallback, and explains that candidate routing improvements are enabled live, with the last candidate retired on 2026-07-26. This goes beyond the readOnly/idempotent annotations to explain experimental behavior and current parity with ask_pipeworx, providing valuable context for the agent.

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

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

The description is dense but efficient: three sentences covering beta status, current parity, usage guidance, and fallback clarification. Every sentence earns its place, is front-loaded with the core purpose, and avoids unnecessary repetition.

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

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

Given the tool's complexity and the absence of an output schema, the description adequately covers what the tool is, how to use it, and its current operational state. It differentiates from siblings and explains that response shape matches ask_pipeworx, making it sufficiently complete for agent decision-making.

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

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

The schema covers all parameters with clear descriptions of the aliases and 'question'. The description's mention of 'same arguments' adds no additional meaning beyond what the schema already provides, so 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 identifies the tool as a beta version of ask_pipeworx, explicitly stating it is a universal router with the same tools, arguments, and response shape. It clearly distinguishes itself from the stable router by noting experimentally enabled routing improvements, making its purpose specific and unique among 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?

It provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate) and how results are compared against the stable router, giving clear context for when to choose 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?

Despite annotations (readOnly, idempotent, openWorld, non-destructive), the description adds substantial behavioral context: grounding behavior, exact response shape, explicit refusal reasons, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is a dense paragraph with several clauses, but each sentence carries useful information: purpose, mechanism, return structure, refusal reasons, use cases, and cost. It is front-loaded with the key value proposition, though slightly verbose.

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

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

No output schema exists, but the description fully documents the expected return format and refusal variants. It also covers use cases, alternatives, and cost. For a tool with rich annotations and a single required parameter, this is 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% with all parameters described as aliases for 'question'. The description does not add meaningful parameter-level semantics beyond the schema; it only mentions the routing step, which is internal process.

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 states a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads' with detailed mechanism (routing, fetching, extracting grounded answers). It clearly distinguishes from sibling ask_pipeworx by contrasting cost and use case, naming the sibling explicitly.

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 when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also gives an explicit alternative: 'prefer ask_pipeworx for casual lookups' and the cost trade-off.

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

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

The description goes far beyond the read-only annotations, detailing resolver contract (market_match_confidence, alternatives), low-confidence short-circuit behavior, closed-market handling, illiquid spread warnings, cancellation-rule parsing, and fallback attempts for news sources. This discloses edge cases and risks (e.g., flat-50¢ void settlements) that annotations cannot capture.

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 exceptionally well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The opening sentence front-loads the core purpose, and each subsequent section adds essential operational detail. Though dense, it earns its length given 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?

Without an output schema, the description fully compensates by documenting response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extractor, news fallback fields, and safety statuses. It also covers blocking paths and resolution-rule risks, making the tool's behavior highly predictable despite no formal output schema.

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

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

The schema already describes all three parameters with 100% coverage, so baseline is 3. The description adds valuable context: it explains the market parameter accepts slug/URL/question text, depth affects fan-out breadth, and include_raw's default and size trade-offs. This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bets), the action (research via data fan-out), and distinguishes itself from siblings by focusing on bet resolution and category-specific evidence packs. Use-case examples ('should I bet on X') further clarify its unique role.

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

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

Explicit guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This clearly indicates when to invoke the tool. However, it does not explicitly mention when not to use it or suggest alternative sibling tools (e.g., validate_claim, polymarket_edges), so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the AbuseIPDB external service context and the 0-100 score scale, which is helpful but not extensive. No contradiction with annotations.

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

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

Two concise sentences plus an illustrative example. The first sentence front-loads the purpose, and every part earns its place with no redundant 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 tool is simple, has output schema, and strong annotations. The description covers purpose, example, and key return fields. Could mention API key requirement explicitly, but the example covers it.

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

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

Schema covers 100% of parameters with descriptions. The description's example adds a realistic invocation pattern with placeholder API key and example IP, but does not add meaning beyond the schema.

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

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

The description clearly states the tool checks an IP against AbuseIPDB and lists the returned data. It does not explicitly differentiate from sibling report_ip, but the verb 'check' implies a read-only lookup distinct from reporting.

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 example of how to call the tool with an API key, which demonstrates usage. It doesn't explicitly state when to use this over alternatives like report_ip, but the read-only context is clear.

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

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

Even though annotations already mark readOnlyHint and idempotentHint, the description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, metric definitions, result sorting, and citation URIs in the return. This goes well beyond the annotations and helps the agent predict side effects and output.

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

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

The description is dense but every sentence carries information: query patterns, priority directive, per-type behavior, sorting, and output format. The only slight redundancy is 'Replaces 8–15 sequential lookups' after already saying 'ALWAYS PREFER', which is mildly repetitive but not harmful. Overall it is a well-structured, front-loaded description.

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

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

With no output schema, the description compensates by explaining the return shape (paired data + pipeworx:// citation URIs). It covers data provenance, fiscal-year nuances, entity-type differences, and sorting. It does not detail failure modes or edge cases like invalid tickers, but the description is sufficiently complete for an agent to use and understand the tool's purpose and output.

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

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

The input schema already documents both parameters with descriptions and examples, so the baseline is 3. The description adds significant semantic value by explaining what each type pulls (10-K financials for companies, FAERS/FDA counts for drugs) and how results are sorted. It could go further by clarifying exact value formats or normalization, but it clearly exceeds schema-level documentation.

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

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

The description opens with clear invocation patterns ('Compare X and Y', 'X vs Y', 'rank these companies') and states exactly what the tool does: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups and explicitly differentiates behavior by type (company vs drug).

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete example queries and clarifies entity-type selection. It does not name a specific sibling alternative like entity_profile for single-entity lookups, but the boundary between comparison and lookup is clear.

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

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

Beyond the readOnly/idempotent annotations, it discloses account and paid-tier requirements, parallel routing to 5,529 tools, the findings-packet shape, gaps[] never-invented guarantee, fetchable citation_uri behavior, hop/contradiction fields, semantic excerpting, and latency. 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?

Although long, every sentence carries distinct operational or selection information, and major caveats (account, alternative tool) are front-loaded. The dense semicolon-separated structure keeps it scannable for an agent.

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

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

With no output schema, the description fully specifies return structure: findings with verbatim evidence+confidence+source+fetched_at, explicit gaps[] for unanswered facets, contradictions[] on higher depths, hop field, citation_uri resolution, and timing. Nothing critical is left to inference.

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 descriptions already cover both parameters, so baseline is 3. The description adds meaningful nuance: examples of valid questions, decomposition of broad questions, and behavior-level differences between quick/standard/thorough (gap recovery vs. lead chasing). This is above baseline but not substantially needed for schema-covered parameters.

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

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

Description names a specific verb ('grounded multi-source research'), identifies the resource ('Pipeworx's 1455 STRUCTURED data sources') and one-call scope, and contrasts with sibling ask_pipeworx. It clearly distinguishes this from open-web search and single-lookup 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?

Provides explicit when-to-use ('broad/multi-part questions over structured data') and when-not-to-use ('single lookup', 'BREAKING or colloquial CURRENT-NEWS'), naming alternatives ('use ask_pipeworx instead'). Also gives account/tier prerequisites and depth-selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond the annotations: it returns top-N tools with full input schemas and curated examples, and each result is ready to call directly with no second schema lookup needed. This clarifies the return behavior and workflow impact.

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

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

The description is well-structured and front-loaded with the core purpose. The list of domains is long but useful for qualifying use cases. Return behavior and usage guidance are compactly stated. A slight deduction for the lengthy enumeration, though it 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?

The description covers what the tool does, when to use it, and what it returns (names, descriptions, schemas, examples). Given the tool's meta nature and strong annotations/schema, it is nearly complete. Missing explicit statements about output format, but the description sufficiently implies the result structure.

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 each parameter including aliases and the limit field. The description does not add parameter-specific details beyond the schema, but it does reinforce that the query is a natural language task description via examples. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It explicitly lists the resource (tools) and differentiates from the many sibling data tools by being a meta-tool for discovery. The verb 'Find' and the scope 'discover what tools exist' are 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 explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to invoke it and implies that for single-answer tasks, other tools may be more appropriate.

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 the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; the exact return fields; and a soft-fail behavior for the USPTO PatentsView API sunset. This goes well beyond annotation defaults.

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

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

The description is a dense single paragraph with several example queries and a full inventory of return fields. It is front-loaded with user-intent phrasing and delivers information efficiently, though it is slightly long and could be broken into bullets for faster scanning. Each 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?

With no output schema, the description masterfully fills the gap by enumerating the return structure (cik, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers limitations (names not supported, patents soft-fail) and provides fallback guidance to resolve_entity. The tool is complex, yet the description is remarkably 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?

The input schema already provides 100% coverage with detailed descriptions for 'type' and 'value', including the ticker/CIK format and the 'names not supported' caveat. The description repeats these examples but does not add new semantic meaning to the parameters, so the baseline of 3 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 opens with concrete example queries and states 'full cross-source profile of a US public company in ONE parallel call', clearly identifying the tool's function. It also distinguishes itself from sibling channels by explicitly advising preference over chaining single-pack SEC/XBRL/news lookups for holistic requests.

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 specifies when to use this tool ('when the user asks for a holistic view') and names the preferred alternative path ('use resolve_entity first if you only have a name'). It also instructs to ALWAYS PREFER this tool over chaining single-pack lookups, giving a crisp decision rule.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is clear. The description adds the context of clearing sensitive data and pairing with related tools, but does not disclose what happens if the key does not exist or whether deletion is permanent. Given the annotations cover the main behavioral traits, a score of 3 is appropriate.

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

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

The description is three sentences, each serving a purpose: the first states the action, the second gives usage scenarios, and the third relates it to sibling tools. It is front-loaded with the core purpose and contains no unnecessary wording.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It explains what the tool does, when to use it, and how it relates to other memory tools. Annotations cover the destructive and idempotent nature, so no additional context is needed.

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

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

The schema description covers 100% of the single parameter 'key' with 'Memory key to delete'. The description's phrase 'by key' mirrors the schema without adding extra detail on key format or semantics, so it does not go 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 uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key'. It clearly distinguishes itself from siblings like 'remember' and 'recall' by noting 'Pair 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?

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier'. It also mentions pairing with remember and recall, but does not explicitly mention when not to use it or alternatives beyond the pairing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description adds process details (fetches page, extracts fields, emits markdown) and output format. It doesn't mention error handling or network caveats, but the annotations cover the safety profile.

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

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

Two sentences plus a use-case list, all substantive. Front-loaded with the main action and resource, no redundant phrasing or filler.

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

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

Explains the tool's purpose, process, and output artifact ('single text blob ready to drop at site-root/llms.txt'). Missing potential failure modes or constraints (e.g., public URL requirement), but for a straightforward generator with strong annotations, it's sufficiently 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 descriptions cover 100% of parameters (url and max_links with default/max). The description doesn't add additional parameter meaning beyond what's already in the schema, so 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 uses a specific verb ('Generate') and resource ('llms.txt file'), and explains the process (fetches page, extracts title/description/key links, emits markdown). It clearly distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the output artifact rather than visibility analysis.

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

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

Provides a clear 'Useful for' list with three concrete scenarios (client site, own project, competitor audit). It doesn't explicitly name alternative tools or exclusions, but the context is clear enough to infer when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds that it returns IPs with abuse confidence scores, which is useful, but does not disclose additional behaviors like rate limits, pagination, or API key requirements beyond the schema. This is acceptable given the strong annotation coverage.

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

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

The description is three concise sentences: purpose, return value, and usage context. No wasted words, information is front-loaded, and 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?

For a read-only list tool with complete schema, annotations, and output schema, the description fully covers the essential context. The purpose, result content, and typical use case are all present. No significant gaps remain given the structured metadata available.

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

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

Schema description coverage is 100%, with both parameters (limit and _apiKey) clearly described in the schema. The description does not add any parameter-level detail beyond what the schema provides, so the baseline score of 3 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 gets the AbuseIPDB blacklist of most-reported IP addresses, which is a specific action on a specific resource. It also distinguishes itself from sibling tools like check_ip (individual lookups) and report_ip (submissions) by focusing on the blocklist output.

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 clear use case ('useful for building blocklists') and implies the tool is for bulk IP reputation data. However, it does not explicitly mention alternatives or when not to use it, though sibling names suggest alternatives. The context is clear enough for an agent to infer 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 cover read-only, idempotent, and non-destructive behavior. The description adds value by clarifying the scope ('caller's') and enumerating the returned fields, which helps the agent understand output shape. No contradictions.

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

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

Two sentences, front-loaded with the verb and resource, every word contributes. It efficiently packs purpose, return fields, and usage guidance without 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?

Despite no output schema, the description explicitly lists all returned fields. With one optional parameter, clear annotations, and a detailed list of fields, the description is complete for a low-complexity read-only tool.

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

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

Schema coverage is 100% (include_inactive is fully described). The description does not add explicit parameter details beyond the schema, but it implicitly clarifies that only active subscriptions are listed by default. Baseline 3 is appropriate since schema carries the semantic load.

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 a specific verb ('List') with a clear resource ('the caller's active subscriptions') and explicitly states the returned fields. It distinguishes itself from sibling tools like subscribe/unsubscribe by framing this as a read-oriented review tool.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It gives clear context but does not explicitly name alternatives or state when not to use, so it falls just short of a 5.

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

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

Discloses return of a claim_token for anonymous filings, rate-limiting ('Rate-limited to 5 per identifier per day'), no quota impact ('doesn't count against your tool-call quota'), and that feedback is read daily by the team. Annotations are all false, so the description carries the full burden and does so richly.

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?

Though longer than typical descriptions, it is dense and front-loaded with purpose and usage, then covers constraints. No filler; all sentences contribute operational information, but a slight trim would still preserve everything.

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 (five feedback types, context object, claim-token flow, rate limits, exclusions), the description covers everything needed for correct invocation. The absence of an output schema is mitigated by explaining the claim_token return.

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 each parameter described. The description adds extra guidance: for claim_token, 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and notes 'with no other arguments'; for message, it says to describe issues in terms of Pipeworx tools/packs and not paste the end-user's prompt.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb+resource structure and differentiates from sibling tools like ask_pipeworx by focusing on feedback rather than questions.

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 when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states an exclusion: 'ONLY for tools served by this Pipeworx connection' and directs other MCP tools to their respective servers.

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 significant behavioral context beyond the annotations: it's derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and has caching behavior (5min-1h). This complements the readOnly/idempotent annotations with valuable operational 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 slightly long due to the enumerated use cases, but every sentence serves a distinct purpose—purpose, use cases, and behavioral transparency. It's front-loaded with the core function and uses bolded labels for readability, though it 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?

With no output schema, the description adequately explains what is returned (top tools, top packs, total call volume, and the (pack, tool, count) format). It also covers caching and the aggregation source, making the tool's behavior fully understandable for an agent with no prior 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?

The sole parameter 'window' is fully documented in the schema with enum values and descriptions, achieving 100% schema coverage. The tool description reiterates the values but adds no new meaning beyond what the schema already provides, so the 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 returning trending AI agent calls on Pipeworx, specifying top tools, top packs, and call volume over a defined window. The verb 'returns' and resource 'top tools/packs/call volume' make the purpose specific and distinct from siblings like discover_tools.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choices, aligning use cases) which provide clear when-to-use guidance. It does not explicitly state when not to use or mention sibling alternatives, but the context is sufficient to infer 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 declare read-only, open-world, idempotent, and non-destructive hints. The description adds substantial context beyond these hints: it explains the semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs, >20% placeholder fraction returns null), the fill check process (theoretical vs realizable edge at 1000 shares/leg), and the exact response fields. It also discloses limitations like realizable_edge_pp ≤ 0 meaning the edge exists only at last-trade. This goes far beyond annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with a clear purpose sentence, then each mode is explained, followed by labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that are highly specific. The structure uses capitalized headers for readability, and there is no redundant or overlapping content. For a tool with this complexity, the length is appropriate.

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 that there is no output schema, the description must fully explain return values and behavior. It covers the response structure for all modes (opportunities[], partition_check), explains the trending_scan default, and details the fill check mechanism. With 2 optional parameters and rich annotations, the description is exceptionally complete, leaving no critical gaps for an agent to invoke and interpret 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?

Although the schema descriptions already cover 100% of parameters, the tool description enriches them significantly. It gives concrete examples for event ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k') and for topic ('Strait of Hormuz traffic returns to normal'), explains the difference between single-event and cross-event scanning, and notes that full Polymarket URLs are accepted. This adds meaning well beyond the baseline schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb and resource, and distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and referencing fill check and custom sizing. The three invocation modes (no args, event, topic) are explicitly described, further clarifying scope.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It labels event as 'recommended for a specific market' and explains the trade-offs between modes. It also references polymarket_fill_risk for custom sizing, signaling when to use that alternative, and warns against trading when fill check shows non-realizable edge.

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 readOnly=true annotations, the description discloses caching ('Cached 1h at the KV level keyed on all knobs'), response diagnostics (_diagnostics with funnel counters), and filter semantics (tradeable-edge knobs drop opportunities). It also warns about 24h-move price edge decay and explains why Fed bets are excluded.

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

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

The description is dense but organized into model families, response top-level, knobs, and diagnostics. The first sentence is clear, but the wall of domain-specific details (per-sport α values, Run 8 history, FRED log-returns) could be trimmed. Still, every major section 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?

With no output schema, the description fully specifies the response structure: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains empty-segment causes and caching, making it self-sufficient for complex 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 coverage is 100%, but the description adds value by labeling min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS', explaining that min_partition_leg_kelly applies to per-leg Kelly because parent-level Kelly is 0 by design, and clarifying that slippage_pp is subtracted before ranking.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling Polymarket tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on model-driven edge discovery.

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 tool is explicitly positioned for 'what should I bet on today' and helps agents avoid paging hundreds of markets. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full when-not guidance.

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

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

Annotations already declare read-only and idempotent, but the description adds substantial behavioral context: snapshots are written on cache-miss, gaps mean no scan that day, history is bounded by a 60-day TTL, and decay is computed on absolute edge value with sign indicating direction. These details are not present in annotations and significantly improve transparency.

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-organized with capitalized sections (ARGS, RESPONSE, LIMITS) and each sentence carries distinct information—from response fields to computation details to data gaps. No filler or redundant restatement; it is dense but efficiently structured.

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

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

With no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) including fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It also covers data availability limitations and computation basis, making it fully self-sufficient for understanding the tool's behavior.

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

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

The input schema already covers both parameters with 100% coverage (days, window, defaults, clamps). The description restates defaults and clamps but adds minimal extra meaning beyond calling window a 'snapshot family', which is a minor clarification. Since schema coverage is high, a score of 3 is appropriate per the baseline.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question ('how long has this edge existed and is it shrinking?'), distinguishing it from siblings like polymarket_edges by focusing on historical time-series rather than current edges. The verb 'tracks' and resource 'polymarket_edges snapshots' make its function explicit.

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 gives clear context on when to use the tool via the question it answers and the example comparing fresh vs. old edges. However, it doesn't explicitly name alternatives (e.g., 'use polymarket_edges for current edges') or state when not to use it, so it lacks 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?

Beyond annotations (readOnly, idempotent), the description discloses detailed runtime behavior: walks the order-book ladder, returns specific fields per mode, interprets size_usd differently for buys/sells/basket, and warns about partial-fill risks. 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 long but well-structured with clear SINGLE-MARKET and BASKET sections, a front-loaded purpose, and every sentence contributes necessary detail. It is somewhat dense, but the complexity of the tool justifies the length.

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

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

Despite having no output schema, the description enumerates all return fields for both modes, explains defaults, mode selection, and risk implications (thin legs, forced directional risk). It covers edge cases and the tool's operational context thoroughly, making it complete for correct invocation.

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

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

Schema coverage is 100% and descriptions are already rich, so baseline is 3. The description adds value by clarifying the mutual exclusivity of market vs event ('REQUIRES one of'), and refining size_usd semantics with concrete examples (max spend vs target proceeds, settlement notional). This goes beyond schema wording.

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

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

The description opens with a precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial fills on thin books convert arb into unhedged directional positions), giving both positive and negative use 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing the matching algorithm, compatibility_warning trigger conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also honestly states that real cross-venue spreads are rarer than the shortcut list suggests. This provides the agent with rich behavioral context beyond 'read-only'.

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-organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes essential information about behavior, limitations, or output interpretation. It is front-loaded with the core purpose and then dives into necessary details. Slightly verbose in the safety-fields paragraph, but the density is justified by 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?

There is no output schema, so the description must explain the response structure itself, which it does thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also addresses edge cases like semantically unrelated events and temporal mismatches. Given the tool's complexity and lack of an output schema, the description is complete and actionable.

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

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

The input schema already has 100% description coverage, giving the baseline of 3. The description enriches this by explaining the two modes, providing the full list of topic shortcuts, and noting that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also clarifies that these are optional but that their presence changes the tool's behavior, which adds meaningful semantics beyond the schema.

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

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

The description opens with a specific statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This distinguishes it from the sibling tools like polymarket_arbitrage and polymarket_edges, which focus on single-venue or different comparison types. The two modes (topic vs explicit) and the response fields are clearly identified.

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 explains when to use topic shortcuts vs explicit ticker/slug pairings, and warns that most pre-mapped topics currently return compatibility_warning, so 'pre-mapped ≠ tradeable.' It also indicates when spreads are meaningful (equivalent bet shapes) and when the tool will report non-equivalence. However, it does not explicitly compare against sibling tools or state 'use X instead,' so it lacks a full when-not-to-use/alternatives discussion.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving a specific value or listing all keys. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary action, and includes practical examples and pairing with related tools. Every sentence contributes meaning with zero filler.

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

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

With one optional parameter, strong annotations, and a clear description covering usage, scoping, and return modes, the description is fully complete for this simple tool. No output schema exists, but the behavior is self-explanatory.

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

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

Schema description coverage is 100%, and the single parameter 'key' already has a clear description. The tool description repeats that omitting it lists all keys but adds no additional syntax or format details. The schema carries the burden, so 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 states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It also clarifies the two modes (with and without the key argument) and gives concrete use cases, distinguishing it 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?

Explicitly states when to use: 'Use to look up context the agent stored earlier' and mentions it avoids re-derivation. It also names alternatives: 'Pair with remember to save, forget to delete,' providing clear context and 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?

The description states that setting mark_read:true flags events as read, a state change. This directly contradicts the readOnlyHint=true annotation, which asserts no state changes. The contradiction is significant and could mislead agents relying on the 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?

Three dense sentences with no filler. Front-loads the purpose, then describes payload, filtering, mark_read, and polling. Every sentence earns its place and the structure is logical.

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

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

With no output schema, the description compensates by explaining return payload contents (source, citation_uri, raw event payload). It also covers filtering, mark_read, and polling. A minor gap is lack of explicit pagination behavior, but the limit parameter in the schema addresses 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 coverage is 100%, and the description goes beyond: it gives a concrete type example ('sec_8k'), explains mark_read semantics ('flag returned events read so the next call only shows newer ones'), and mentions the return payload structure. This adds real 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?

Clear verb+resource: 'Pull fired events from your subscription feed.' It distinguishes from siblings like list_subscriptions (manage feeds) and recent_changes (system changes). The name and description are aligned 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?

Provides clear usage context: filtering by type and since, polling suitability, and an alternative HTTP endpoint for scripts/dashboards. Does not explicitly name alternative tools or exclusions, but the intended use case is evident from the description.

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 (readOnly, idempotent, openWorld), the description discloses rich behavioral details: the fan-out to SEC EDGAR, GDELT→GNews fallback with conditions (rate-limited/5xx), USPTO soft-fail due to PatentsView API sunset, accepted `since` formats, and return structure (changes[], total_changes, citation URIs). This significantly exceeds the annotation information.

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

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

The description is a single dense paragraph that covers many aspects, but every clause contributes useful information—no filler. It could be slightly more structured with bullet points or sections, but given the complexity, it remains appropriately concise.

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

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

The tool has multiple sources, fallbacks, and parameter formats; the description covers all of them in a cohesive way. It explains the return structure (structured changes[] + total_changes + URIs) despite no output schema, and provides a clear pointer to the static-profile alternative. This is comprehensive for an agent to invoke 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 the baseline is 3. The description adds practical value by illustrating `since` formats ('7d', '30d', '3m') and recommending '30d' or '1m' for typical monitoring. It also reinforces that value can be a ticker or CIK, though this is already in the schema. This extra guidance justifies a score above baseline.

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

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

The description clearly defines the tool as a change feed for a company within a recent time window, with example queries like 'What's new with X' and 'updates on Acme.' It also distinguishes from entity_profile by explicitly stating when to use the alternative, 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?

The description provides explicit when-to-use guidance through example user queries and explicitly names an alternative: 'Use entity_profile instead when you want the static profile.' It also details the coverage (filings, news, patents) and fallback logic, which helps an agent decide when this tool is appropriate.

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 important behavioral context beyond annotations: storage as a key-value pair scoped by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This reveals scoping and lifecycle details that annotations do not convey. 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 front-loaded with the primary purpose and uses five compact sentences. Every sentence adds value: purpose, usage, storage details, persistence, and sibling relationships. No redundant or filler content.

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 having no output schema and only two parameters, the description is complete for its complexity. It covers what the tool does, when to use it, how data is stored and scoped, persistence semantics, and how it relates to recall and forget. No critical information is 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 coverage is 100% with detailed descriptions for both parameters (key and value). The description reinforces these semantics with examples (ticker, address, preference) but does not add significant new meaning beyond the schema, so the 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 states the tool saves data for reuse across conversations or sessions, using a specific verb ('Save') and resource ('data'). It distinguishes itself from sibling tools by explicitly pairing with recall and forget, making its 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?

The description provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference, research subject) and mentions paired tools (recall, forget). However, it does not specify when not to use the tool, so it falls short of the top score.

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 says 'Report' and 'Returns the updated abuse confidence score,' implying a state-changing write operation, while annotations declare readOnlyHint=true. This is a direct contradiction: the description describes a write while the annotation claims read-only. This inconsistency is critical for an agent deciding whether to invoke the tool.

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

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

Two concise sentences, front-loaded with the main action, followed by the key requirement and return value. Zero 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?

The description covers purpose, key requirement, and return value, and the schema/annotations fill in parameter and safety details. However, it lacks usage context to differentiate from sibling tools and the contradiction with readOnlyHint creates confusion, leaving notable 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 all four parameters described in detail, including category IDs and examples. The description's mention of '18,22' for DDoS + SSH brute force merely repeats what the schema already provides, adding no new parameter semantics.

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

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

The description clearly states the tool reports an abusive IP address to AbuseIPDB, with a specific verb ('Report') and resource. It distinguishes from sibling tools like check_ip, which likely checks reputation instead of submitting a report.

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

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

The description implies usage for reporting abusive IPs but does not explicitly state when to use it versus alternatives such as check_ip or get_blacklist. It lacks exclusions or explicit 'use this when' 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?

The description adds significant behavioral context beyond the readOnly/openWorld/idempotent annotations: it explains that the tool cascades through multiple internal lookup endpoints, degrades gracefully when GLEIF or OpenFIGI is unavailable, labels every identifier with its source, and explicitly reports unresolved identifiers under `unresolved`. This is rich, non-obvious behavior.

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

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

The description is long but well-organized: opening examples, a clear purpose statement, and a structured breakdown by type. Every sentence adds useful detail; however, the example list is somewhat redundant with the purpose statement, and a slightly tighter edit could preserve value while reducing length.

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

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

For a tool with only 2 parameters and no output schema, this description gives a near-complete picture: it lists all returned identifier fields, explains ownership data, notes the citation URI for drugs, clarifies unresolved-identifier handling, and covers fallback behavior when enrichment services fail. This is sufficient for an agent to understand what the tool returns and how to handle partial results.

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?

Although schema coverage is 100%, the description enriches parameter meaning substantially: it details what 'company' returns (CIK, ticker, company_name, LEI with parent/ownership, FIGI), what 'drug' returns (RxCUI, ingredient, brand, citation), and the accepted input forms for `value` (ticker, CIK, name, brand/generic). This goes well beyond the schema's basic type 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 a specific verb-phrase ('resolve a user-spoken NAME to the canonical/official identifiers') and clearly distinguishes the tool from siblings by stating it produces IDs that 'other tools require as input.' It also enumerates supported entity types and example queries, making the tool's purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke the tool. However, it does not explicitly mention when not to use it or compare against alternatives like entity_profile, so it stops short of full when/when-not coverage.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it discloses that the tool makes multiple probes, ranks results, and specifies the output fields (score, confidence, signal density). This goes beyond the structured data and clarifies the orchestration behavior.

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

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

The description is four sentences, front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side'). Each sentence adds a distinct piece of value: action, mechanism, use case, and return format. There is no filler or redundancy.

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

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

With no output schema, the description appropriately covers return value details (ranked list with score, confidence, signal density) and explains the purpose with a concrete use case. It also references ai_visibility_check, linking to the sibling tool. While it does not mention rate limits or credential nuances, those are in the schema, making this generally sufficient for a multi-entity comparison tool.

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

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

Schema coverage is 100% with detailed descriptions for all parameters, including the rule that the first entity is the subject and the rest are competitors. The description adds no new parameter-level information; it mentions 'your brand + N competitors' but this is already in the schema. Thus it meets the baseline without going beyond.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and explains the process: probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It explicitly distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

The description gives a clear use case for competitive AI-marketing audits with an example query, and the mention of ai_visibility_check implies the single-entity alternative. However, it does not explicitly state 'use ai_visibility_check for single entities' or list exclusions, so there is implicit but not fully explicit guidance.

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

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

Annotations already declare this as readOnly, idempotent, non-destructive. The description adds valuable behavioral context beyond annotations: it discloses partial failure handling ('sources_failed will list it if it times out, the rest still returns') and the 5-30s latency for bundlephobia's first measurement. This is exactly the kind of context that helps agents set expectations.

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

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

The description is dense but every sentence adds value. It sequentially covers purpose, usage triggers, output details, ecosystem scope, and failure behavior. It is well-structured and front-loaded with the core purpose, making it easy to scan.

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 having no output schema, the description enumerates the returned fields (summary block, per-advisory detail, links, alternative versions) and explains the composite nature and edge cases (timeouts, ecosystem limitations). For a tool of this complexity, the description is complete enough for an agent to invoke it correctly and interpret results.

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 both parameters ('package' with scoped-package note, 'version' with default behavior). The description adds no extra parameter semantics beyond what the schema already provides, so the 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 states the tool's purpose: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It specifies the resource (npm package) and the verb (scan/check), distinguishing it from sibling tools like validate_claim or scan_competitor_ai_presence.

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 it: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to an alternative tool/method.

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 well beyond the annotations, which only state readOnly, idempotent, and non-destructive. It discloses the embedding model ('BGE-base-en embeddings'), the chunking method ('500-char overlapping windows'), the input limit ('cap is 200K chars (longer inputs are truncated and flagged)'), and the output includes character offsets for verification. 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 concise yet information-dense. It opens with a clear verb-phrase, then contextualizes use cases, pairs with a sibling, and finishes with technical limitations. Every sentence serves a distinct purpose—no filler or repetition. The structure is logically ordered from 'what' to 'when' to 'how.'

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

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

For a tool with no output schema, the description fully explains the return format (passages with offsets and scores). It also covers input constraints, the algorithm, and integration with ask_pipeworx_grounded, making the tool's capabilities and limitations clear. The agent can confidently select and invoke this tool without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The schema already describes each parameter (e.g., text with 'max ~200K chars', query with example phrases). The description adds minimal param-specific meaning; it frames 'text' as 'the text you already pulled' and 'query' as 'a natural-language query,' but these are already implied in the schema. No significant added value beyond what the 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 the tool's function: 'Semantic search INSIDE a fetched record.' It names the specific resource type ('a SEC 10-K body, an article, a long tool result') and the expected output ('top-N passages with character offsets and similarity scores'). This distinguishes it from sibling tools like ask_pipeworx or deep_research, which operate on broader sources.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt' and it explains the benefit ('saves context, returns only the passages that matter'). It also names an alternative/complementary tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives the agent clear decision 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?

The description adds substantial behavioral context beyond the annotations: OAuth is required, anonymous/BYO cannot persist subscriptions, SMS requires phone verification with a 10/day cap, and the feed is always on. This is clearly useful for an agent to understand side effects and prerequisites.

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

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

The description is dense but well-organized, using colons and parentheses to pack multiple pieces of information into a compact block. It avoids fluff but is still long; each clause carries useful info, so it earns a high score rather than a perfect one.

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 return value (subscription id), authentication requirements, supported types, and delivery channels. It does not explicitly mention error handling or idempotency details, but the annotations provide idempotentHint=true, so this is acceptable.

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

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

The input schema already covers all parameters with thorough examples. The description adds semantic value by explaining 'items:["5.02"] = officer change' and clarifying that polymarket_edge is about cross-venue mispricings, which is not fully explicit in 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 uses the specific verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It clearly distinguishes from siblings by mentioning how the feed can be pulled via recent_alerts or registry URL, making the tool's function immediately clear.

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

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

The description provides context on when to use the tool (persistent subscriptions requiring OAuth) and mentions an alternative for reading the feed (recent_alerts or the registry URL). However, it does not explicitly name sibling tools like list_subscriptions or unsubscribe for related operations, so it stops short of full differentiation.

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 useful behavioral context: it explains the return format (category-bucketed questions with exact tool + argument shapes) and that results come from a live catalog. This complements the readOnly/idempotent annotations without contradicting them; the safety profile is already declared, so no need for destruction warnings.

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 user query variations and then covers return format, topic usage, and when to use it. It's slightly long but every clause contributes; still, it could be tightened into a more structured overview.

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?

Considering there's no output schema, the description adequately describes the return value (category-bucketed example questions with tool call shapes) and gives use-case context. It also names the meta-tools it helps learn, making it complete for an onboarding function.

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

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

The input schema already documents the optional topic parameter with an enum-like list and the omit-to-get-full-spread behavior. The description adds a few example values but largely echoes the schema, so it doesn't significantly enrich parameter semantics beyond the existing 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 what the tool does: it is the onboarding entry point that returns category-bucketed example questions for what Pipeworx can answer. It uses specific verbs and resource scope, and distinguishes itself from sibling discovery tools by focusing on question suggestions rather than tool introspection.

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 recommends using this tool first when the agent doesn't know Pipeworx's capabilities, and explains how to use optional topic filtering. However, it doesn't explicitly state when to prefer sibling tools like discover_tools or ask_pipeworx, only naming them as meta-tools to learn about.

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 well beyond the annotations. Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description explains the actual behavior: ownership enforcement, the row is deactivated (not deleted), and historical events remain accessible via recent_alerts. This adds valuable context that helps the agent predict 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 three sentences, each earning its place: the action, the ownership constraint, and the deactivation behavior with a link to recent_alerts. There is no redundancy or filler, making it appropriately compact.

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

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

For a single-parameter tool with no output schema, the description covers all essential aspects: what it does, who can use it, what happens to the row, and how historical data remains accessible. No critical information is 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?

The input schema has 100% coverage for the sole parameter 'id', including its type and origin ('Subscription id (uuid) returned by subscribe'). The description does not add any extra meaning beyond what the schema already provides, so the 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 states the action: 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription), and the mention of ownership enforcement distinguishes it from general subscription management tools. The purpose is unambiguous and distinct from siblings 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?

The description provides clear context for when to use this tool: when you want to cancel a subscription. It also includes an important constraint ('you can only cancel your own subscriptions') and explains the consequence (deactivation not deletion). However, it does not explicitly mention alternatives or situations where another tool would be preferred, so it stops short of a full 5.

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 read-only, open-world, idempotent, and non-destructive hints, and the description adds critical non-obvious behaviors: the full verdict enum, the distinction between 'could_not_verify' and 'unsupported' (including how callers must present them), the citation format (pipeworx://), and the two execution paths (SEC EDGAR/XBRL vs. grounded pipeline). This goes far beyond the annotations and materially changes how an agent should interpret and handle results.

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 every sentence earns its place. It front-loads the purpose with user phrasings, then provides usage, routing, return value details, and important caller warnings. The structure is logical, though slightly dense; it could be tightened without losing content, but it's not excessively verbose for the complexity it covers.

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

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

With no output schema, the description carries the full burden of explaining return semantics. It lists all verdicts, describes the actual-value + citation + reasoning output, and explicitly defines error states ('could_not_verify' vs 'unsupported') with guidance on how to present them. It also accounts for both structured and grounded pipelines, making the tool's behavior fully comprehensible to an agent without external documentation.

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 both parameters have descriptive texts. The description adds extra semantic value by explaining that tolerance_pct overrides the wording-implied tolerance, gives a concrete use case ('set 1–2 for hallucination detection'), and clarifies the claim format with examples. This elevates it above the bare schema baseline.

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

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

The description opens with concrete example phrasings ('Is it true that...', 'fact check'), then names the resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from siblings by focusing on fact-checking and claim verification, and even notes it replaces 4–6 sequential calls, making its unique role explicit.

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

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

The description gives a clear trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing for company-financial claims versus other factual claims, which is an important when-to-use nuance. It doesn't explicitly name sibling tools to avoid or say 'don't use this for open-ended research,' but the guidance is strong and can be inferred.

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