Threatfox

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: the default model is free, Anthropic requires a BYO key passed directly to api.anthropic.com, and it returns structured per-model data plus a combined view. 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?

Three sentences: first states core function, second adds key details about models and API key, third describes return format and use cases. Front-loaded and concise with no extraneous information.

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

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

Given no output schema, the description adequately describes the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers all 4 parameters, explains auth and cost implications, and lists use cases. Complete for the tool's complexity level.

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

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

Schema coverage is 100% (all parameters documented). The description adds meaning: it clarifies 'entity' as a brand/business/product/topic, explains that 'models' includes a free default and that '_apiKey' is only needed with 'anthropic', and describes 'context' as a disambiguation aid. This goes beyond the schema descriptions.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and the optional Anthropic probing, distinguishing itself from siblings like scan_competitor_ai_presence by detailing the scoring mechanism and multi-model support.

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 lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when a BYO API key is needed for Anthropic. However, it does not explicitly mention when not to use this tool or provide direct comparisons to alternative sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it routes to 4,482 tools, returns structured answers with pipeworx:// citation URIs, and works on every tier. No contradiction.

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

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

Description is long but every sentence adds value. Key guidance is front-loaded ('PREFER OVER WEB SEARCH', 'START HERE'). Could be slightly more concise, but structure is logical with examples and alternatives at the end.

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

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

Given the tool's complexity (routing among many sources), the description is complete: explains when to use, what it returns (citations, structured answer), and provides multiple examples. No output schema, but description explains return format sufficiently.

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

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

Schema has 100% coverage with 6 parameters (1 required question plus 5 aliases). Description adds value with example questions and explanation of parameter aliases, going beyond schema descriptions.

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

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

The description clearly states the tool's purpose: answering factual questions about current/historical data from authoritative sources. It lists specific data types (SEC filings, FDA data, etc.) and distinguishes from siblings 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 says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides clear guidance on when to use alternatives (step up to ask_pipeworx_grounded for verbatim evidence, deep_research for broad questions). Includes example queries.

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

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

Discloses behavioral traits beyond annotations: hallucination resistance, exact return fields (answer, evidence, confidence, etc.), explicit refusal reasons, and the fact that it costs an extra LLM call. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint). Adds rich context on how the tool processes and returns data.

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 key purpose. It conveys all necessary information in a single paragraph, but some sentences are slightly verbose (e.g., listing all aliases in description is redundant with schema). Overall efficient but could be tightened.

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

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

Despite lacking an output schema, the description fully defines the return format ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all possible refusal reasons. It also covers use cases, cost trade-offs, and integration with sibling tools. No gaps for high-stakes read 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 description coverage is 100%, with each property described as an alias for question. The description adds minimal extra meaning beyond 'Your question in natural language.' It does not elaborate on expected input format or examples, so it meets baseline but does not significantly enhance parameter understanding.

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

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

Clearly states it's a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing from sibling ask_pipeworx by specifying it extracts answers only from tool results. The verb+resource+scope is specific and unambiguous.

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

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

Explicitly describes when to use: 'whenever an answer will be quoted, cited, or acted on' and for specific domains like financial verdicts, legal claims. Also provides when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to extra cost. Includes concrete criteria and 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds extensive behavioral details: it resolves markets, classifies bets, fans out to category-specific data packs, and returns evidence packets. It discloses safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread flags), resolver contract, parent_event extraction, news fallbacks with retry info, and cancellation rule parsing. 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 very long and dense, packing a lot of information. While it is front-loaded with the primary purpose, the excessive detail (classifiers, fan-out examples, response shapes, resolver contract) makes it less concise. Not every sentence is efficiently phrased for an AI agent's quick consumption.

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 (resolver, classifiers, multiple data sources, edge cases) and no output schema, the description is remarkably complete. It covers evidence packet shape, market_match_confidence levels, parent_event extraction, news fallbacks, cancellation rules, and real-world behavior like resolved markets being de-indexed. No gaps apparent.

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 enriches each parameter: 'market' with examples (slug, URL, question text); 'depth' with enum values and default; 'include_raw' with explanation of size trade-offs. This adds significant meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), action (research via Pipeworx), and input formats. It distinguishes from sibling tools by focusing on Polymarket bets and providing extensive examples.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence and warns about low-confidence matches and cancellation rules. However, it lacks explicit when-not-to-use or comparisons to alternatives like polymarket_edges.

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 annotations: it explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 efficiently structured, front-loading with example triggers and providing all necessary behavioral details concisely. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully explains return format (paired data + citation URIs) and sorting behavior. Annotations cover safety adequately. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by detailing what data is pulled per type (revenue, net income, etc. for companies; adverse-event counts for drugs) and how values should be formatted, adding value beyond schema descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, using specific verbs like 'compare' and 'side-by-side'. It distinguishes itself from sibling tools like entity_profile by explicitly recommending this over sequential single-pack lookups.

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

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

The description provides explicit usage examples ('Compare X and Y', 'X vs Y') and strongly recommends this tool over sequential lookups. However, it does not explicitly state when not to use it, though that is implied.

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?

Goes far beyond annotations by detailing account tiers, parallel routing across 4,482 tools, return format (findings packet with evidence, confidence, gaps), expected duration (15-60s), and edge cases (empty gaps for non-catalog topics).

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?

Long but information-dense, with critical caveats front-loaded. Could be slightly tighter, but no redundant sentences.

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 explains return values, including gaps array and citations. Also covers error handling (unsigned users) and typical response time.

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 both parameters fully. The description adds extra clarity (e.g., depth values explained as facets count, question described as natural language and multi-part friendly). Minor improvement over 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 precisely states the tool's function: grounded multi-source research across 1129 structured data sources with parallel decomposition. It distinguishes from siblings like ask_pipeworx by explicitly contrasting their use cases.

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 lookups via ask_pipeworx, breaking news via ask_pipeworx). Also notes account requirement and alternative for unsigned users.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds that returns top-N relevant tools with schemas and that results are ready to call. 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?

Description is somewhat long but every sentence adds value. Front-loaded with purpose. Could be slightly more concise but justified given the amount of useful information.

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

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

For a simple discovery tool with 6 parameters, description fully explains what it does, what it returns (top-N tools with schemas), and how to use it. No output schema 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?

Schema coverage is 100% with descriptions for each parameter. Description also explains aliases and provides examples. Adds meaning beyond schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains. It distinguishes itself from sibling tools (specific tools) by being a meta-tool for 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use 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 safe read-only, idempotent, non-destructive behavior. The description adds behavioral details: fans out across multiple sources, returns specific data, notes patent soft-fail due to API sunset, and discloses sorting and URI format. Sufficient context beyond annotations.

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

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

The description is a single paragraph but well-structured, starting with examples, then purpose, then return details. Each sentence adds value, though slightly dense. Could be broken into bullets but still concise and informative.

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

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

Despite no output schema, the description comprehensively lists all return fields and data sources, including caveats about patent sunset and name resolution. Covers the tool's full capability for a complex multi-source 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%, but description adds value by providing examples ('AAPL', '0000320193') and clarifying constraints (names not supported, only 'company' type). Enhances understanding beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides example queries and lists return data, distinguishing it from chaining multiple lookups and from sibling tools like resolve_entity.

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 when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies when not to use: if only a name is available, use resolve_entity first. Clear context for selection.

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

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

Adds context about clearing sensitive data, but annotations already provide destructiveHint=true and idempotentHint=true. No mention of auth needs, rate limits, or behavior on missing key.

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

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

Two concise sentences with front-loaded purpose and a useful pairing note. No wasted words.

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

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

For a simple single-parameter delete tool with annotations, the description adequately covers purpose, usage, and pairing. Missing return value info but not critical given no output schema.

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

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

Schema covers 100% and parameter 'key' is described as 'Memory key to delete'. Description does not add additional meaning or constraints beyond schema.

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

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

Description clearly states 'Delete a previously stored memory by key.' Verb 'delete' + resource 'memory' + method 'by key' is specific. Distinguishes from siblings by mentioning 'remember and recall' as paired tools.

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

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

Explicitly lists scenarios: stale context, task done, clear sensitive data. Does not explicitly state when not to use or compare with other sibling tools besides the pair.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds process details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Three sentences, front-loaded with purpose, no extraneous words. Efficient and scannable.

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, so description explains output 'single text blob ready to drop at site-root/llms.txt'. Covers behavior, parameters, and use cases. Complete for a simple generation 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 covers both parameters with descriptions. Main description does not add new parameter-level info but provides high-level context. High schema coverage gives baseline 3.

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

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

Clearly states verb 'generate', resource 'llms.txt file', and context 'for any URL'. Distinguishes from siblings by specifying AI crawlers and standard output format.

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

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

Explicitly lists three use cases (client indexing, own project, competitor audit). Does not explicitly state when not to use or alternatives, but context makes it clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns a list of subscriptions with specific fields, and that include_inactive affects cancelled subscriptions. Provides behavioral context beyond annotations.

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

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

Two concise sentences: first spells out purpose and output, second gives usage advice. No wasted words, front-loaded with essential info.

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

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

Given simple tool (1 optional param, no output schema), description covers purpose, return fields, usage scenario, and parameter effect. Sufficient 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?

Schema coverage is 100% with description for include_inactive. Description does not add extra meaning beyond schema, 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?

Verb 'List' with specific resource 'the caller's active subscriptions', lists return fields, and differentiates from siblings subscribe/unsubscribe by context. Clear and specific.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Does not mention alternatives but provides clear context.

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

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

Discloses rate limits (5 per identifier per day), free usage, no quota impact, and that team reads digests daily. Annotations are all false, so description adds all necessary behavioral context without contradiction.

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

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

Well-structured: front-loaded with purpose, then usage, then behavioral details. Every sentence adds value; no redundant or ambiguous wording.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers all necessary aspects: parameter semantics, usage scenarios, rate limits, and constraints. No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. Description adds extra context for each enum type and explains the optional context object fields, enhancing understanding beyond the schema.

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

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

The description clearly states the tool sends feedback to the Pipeworx team, listing specific use cases (broken, missing, praise). It distinguishes itself from sibling tools, none of which are for feedback.

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

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

Explicitly provides guidance on when to use each feedback type (bug, feature, data_gap, praise) and instructs what to include (tool/pack context) and what to avoid (pasting end-user prompts).

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, caching intervals (5min-1h), and return structure (top tools, top packs, volume). This goes beyond annotations without contradicting them.

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

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

The description is moderately concise but well-structured, with a lead sentence followed by bulleted use cases. Each sentence adds value, but it could be slightly shorter without losing clarity. Overall, it's effective and front-loaded.

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

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

Given the low complexity (1 optional param, no output schema), the description fully covers what the tool does, what it returns, how it works (cached analytics), and why to use it. No gaps remain for an agent to misunderstand or misuse the tool.

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

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

The single parameter (window) has a complete enum description in the schema, explaining the meaning of each option. The description reinforces this with use-case guidance ('shorter windows surface what's hot right now; longer windows show steady-state demand'). Schema coverage is 100%, so the description complements it well.

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

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

The description clearly states it returns top tools, top packs, and total call volume over specified windows (24h, 7d, 30d). It distinguishes itself from sibling tools by focusing on trending/aggregated data in Pipeworx, not specific queries or entity profiles.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases with agent demand. It also explains the signal's nature (self-aggregating, no PII) and caching behavior, helping agents decide when to call this vs. other tools.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: the Jaccard similarity threshold (≥0.30), partition filter placeholder fraction (>20% returns null), response fields (opportunities[], partition_check), and the fill check logic (realizable_edge_pp ≤ 0 means not tradable). 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: starts with usage requirement, then purpose, then mode details, semantic anchor, partition filter, response, fill check. Each sentence earns its place. Could be slightly more concise, but overall efficient given the complexity.

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

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

For a complex arbitrage tool with two modes, multiple algorithmic checks, and no output schema, the description covers almost everything: usage, algorithm, edge cases (placeholder slugs), response structure, and fill check. The tolerance values (3pp, 0.30 Jaccard, 1000 shares/leg) are specified. It is complete for practical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: concrete examples for event slugs ('fed-decision-may-2026') and topic seed questions, and behavioral details like 'walks child markets' and 'searches related events'. This elevates it 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 states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two explicit modes (event and topic), specifying the resource and verb. This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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 'REQUIRES one of event OR topic — call with no args fails.' It recommends event mode for specific markets and explains cross-event mode catches patterns single-event misses. It also mentions a sibling tool polymarket_fill_risk for custom sizing, providing clear when-to-use and when-not-to-use 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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description goes far beyond by detailing response structure (by_segment), caching (1h KV-level), model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation, and diagnostics for empty segments. 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 lengthy but well-structured with clear sections (FIVE MODEL FAMILIES, RESPONSE TOP-LEVEL, etc.). It is front-loaded with the core purpose and uses paragraphs for grouping related information. Minor verbosity is justified by complexity.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), tradeable-edge knobs, caching behavior, and model details. It covers everything an agent needs to understand and use the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value for the overall context but does not significantly enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combination. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx disagreement and edge detection.

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

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

The description states it's 'Built for "what should I bet on today"' and mentions tradeable-edge knobs for filtering. While it doesn't explicitly exclude other tools or provide comparisons, it clearly indicates when to use it (discovering opportunities without paging through markets).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: response structure, limits (60-day TTL, start date), and that decay is computed from daily closes, not intraday. 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 well-structured with a clear first sentence, explanation of response fields, and limitations. It is slightly verbose but front-loaded with key information.

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

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

Without an output schema, the description thoroughly covers the output structure (tracked[], expired[], snapshot_dates[]) and explains limits and computational details. It is complete for the tool's complexity.

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

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

Schema coverage is 100% and already describes both parameters with defaults and constraints. The description only repeats the same information (e.g., 'default 14, max 30' for days) without adding new meaning.

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

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

The description clearly states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge duration. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description implies usage for analyzing edge persistence over time but does not explicitly state when to use versus alternatives or when not to use. It mentions limits (TTL, start date) but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds rich behavioral details: walking the order-book ladder, return fields (top_of_book, vwap_fill_price, slippage, etc.), basket mode risk of forced directional exposure, and the dominant loss mode. No contradiction with annotations.

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

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

The description is lengthy but well-structured, using capitalization to highlight sections (SINGLE-MARKET, BASKET, REQUIRES) and front-loading the core purpose. Every sentence adds value, though some agents might prefer shorter text. Appropriate given tool complexity.

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

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

Given no output schema, the description completely covers return values for both modes, including edge cases (thin_legs, forced_directional_risk, max_clean_notional_usd). Also explains constraints (size clamp 10–1,000,000) and the risk of partial fills. No gaps for a read-only query tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: clarifies side default behavior for basket mode (auto based on partition sum), size_usd interpretation (settlement notional in basket), and the REQUIRES constraint for market vs event. This extra context is valuable but not essential beyond schema.

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

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

Description clearly states the tool checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' with two distinct modes (single-market and basket). It distinguishes from siblings by explicitly stating when to use this tool before polymarket_arbitrage or polymarket_edges signals.

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'. Also explains prerequisites (requires market or event) and why (theoretical overround not capturable, partial fills create directional risk).

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, openWorld, idempotent, non-destructive), the description discloses detailed safety fields: compatibility_warning conditions, temporal alignment, and skipped leg-pair counters. It explains what happens when venues have non-equivalent bet shapes or no token overlap. 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 dense but every sentence is informative. It is front-loaded with the core purpose and modes. However, it could be slightly more structured (e.g., bullet points for modes) to improve scannability. Still, 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?

Despite no output schema, the description thoroughly explains the response structure: per-venue prices, matched spreads, top_spreads_pp, safety fields, and counters. It covers all necessary context for an agent to understand inputs and outputs. With 3 optional parameters and complex behavior, no gap remains.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds significant value: it explains the two modes (topic vs explicit tickers), the override behavior, and gives concrete examples for the topic parameter (e.g., 'fed', 'btc'). This goes beyond the schema's simple descriptions.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads and unique safety fields. The verb 'spread' and the resource names are 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 provides explicit usage modes: topic shortcuts for pre-mapped macros and explicit event tickers for custom pairings. It advises when spreads are meaningful and when they are not, especially through the compatibility_warning and temporal_alignment fields. It even notes that most pre-mapped topics currently return warnings, setting realistic expectations.

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, destructiveHint, idempotentHint. The description adds valuable behavioral context: scoping to identifier, listing all keys when omitted, and pairing with remember/forget. No contradiction.

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

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

Two efficient sentences with front-loaded action: 'Retrieve a value...' No fluff, 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 simple tool with one optional parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage, behavior, and scoping. No gaps.

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

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

Schema coverage is 100% with full description. The description reinforces the schema's 'omit to list all keys' behavior, but adds no new parameter-level 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?

Clearly states the verb (retrieve/list) and resource (saved values/keys), distinguishes from siblings like remember and forget, and provides concrete use-case examples.

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 (retrieve previously stored context) and when to list all keys (omit key). Names companion tools (remember, forget) and scoping details, giving clear guidance on alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that mark_read:true flags events as read, affecting future calls. No contradictions with annotations.

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

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

Description is moderately sized with each sentence providing distinct information. First sentence states main purpose effectively. Could be slightly more concise but not verbose.

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

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

Covers return fields, parameter usage, and alternative access method. No output schema, but description sufficiently describes what to expect. Complete for agent selection.

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

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

All parameters have schema descriptions, but description adds examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies the effect of mark_read, adding value beyond schema.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific fields returned (source, citation_uri, raw event payload). Distinguishes from sibling tools as it is the only alert-specific 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?

Mentions that polls are fine and provides an alternative access method (GET registry.pipeworx.io/alerts.json). Does not explicitly state when not to use but gives good 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?

Discloses fallback logic (GDELT→GNews), soft-fail for USPTO, parallel call behavior, and return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). No contradiction with annotations (all readOnly, idempotent, non-destructive).

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

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

Single efficient paragraph with front-loaded examples, no redundancy, 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?

Despite no output schema, the description sufficiently explains output format and handles complexity (multiple sources, fallback, soft-fail). For a tool with 3 required params, it is fully complete.

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

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

Schema covers all three parameters fully (100%). Description adds relative shorthand examples, usage notes for 'since', and clarifies value accepts ticker or CIK.

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 specifies the verb 'get change feed for a company' and resource 'a company in the last N days/weeks/months'. It clearly distinguishes from sibling tool 'entity_profile' by contrasting with static profile retrieval.

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 example queries (e.g., 'What's new with X', 'latest on Y'), suggests typical 'since' values ('30d' or '1m'), and directs to use 'entity_profile' when static profile is needed.

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 tool's safe, idempotent, and open-world nature is clear. Description adds the time-based scope ('last N days'), which is useful but not critical beyond schema.

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

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

Two sentences: first states purpose, second provides usage context. No superfluous words, efficiently communicates key information.

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

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

Given the simple tool (one optional parameter, annotations covering safety, output schema existing), the description is complete. It explains what it does, when to use it, and the parameter is fully documented in the schema.

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

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

Schema description coverage is 100%: the 'days' parameter is fully described with type, range, and default. The description does not add further parameter-related meaning, aligning with baseline 3.

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

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

The description clearly states 'IOCs added to ThreatFox in the last N days', specifying the verb (retrieve), resource (IOCs from ThreatFox), and time scope. Differentiates from sibling tools like search_ioc or search_hash by focusing on recent additions.

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

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

Explicitly says 'Useful for daily threat-intel ingestion', providing a clear use case. Does not explicitly mention alternatives or when not to use, but the context is sufficient for typical selection.

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

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

Adds beyond annotations: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous. 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?

Four sentences, front-loaded with purpose, no filler. 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?

Fully covers behavior, persistence, and scoping for a simple 2-parameter tool. No missing context given annotations and parameters.

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

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

Schema coverage is 100%, so baseline 3; description adds examples (e.g., 'subject_property') that clarify format, worthy of +1.

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

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

Clearly states 'Save data the agent will need to reuse later' and specifies the resource as a key-value pair. Distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and recommends pairing with 'recall' and 'forget'. Provides clear guidance on when and how to use.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that the tool cascades through multiple internal lookups, replacing 2-3 manual steps, and details the return values for each type. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It begins with concrete example queries, states the core purpose, lists supported types with detailed explanations, and concludes with an internal efficiency note. No superfluous sentences.

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?

Annotations cover safety and idempotency. The description explains what is returned for each type and that internal lookups are performed. However, it omits error handling (e.g., what happens if the name is not found) and does not mention whether the tool handles ambiguous input beyond 'auto-disambiguated' for companies.

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 basic descriptions for 'type' and 'value'. The description significantly enriches both parameters by specifying exact return values (e.g., for company: ticker, CIK, company_name, citation URI; for drug: RxCUI, ingredient, brand). This goes well beyond the schema.

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

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

The description clearly states the tool resolves names to official identifiers, with specific examples like tickers and CIKs. It distinguishes the tool's role as a prerequisite for other tools requiring IDs, but does not explicitly differentiate from related sibling tools like 'entity_profile' or 'compare_entities'.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types and input formats. However, it does not mention when not to use this tool or suggest alternatives for cases where a different resolution is needed.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so it's a safe read operation. The description adds behavioral details: probes each entity with ai_visibility_check, ranks results, returns scores/confidence/signal density. No contradictions.

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

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

The description is a concise paragraph (about 100 words) with the purpose stated first. Every sentence adds value, no redundancy.

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

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

Given the complexity of a multi-entity comparison with ranking, the description fully explains what the tool does, how it works internally, and what the output contains (ranked list with score, confidence, signal density). With 100% schema coverage for parameters and clear annotations, the description 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 description coverage is 100%, so the schema already documents all parameters. The description adds usage context (default models, purpose of context for disambiguation) and clarifies the role of the first entity as 'subject'. This provides meaningful extra guidance beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks by score. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies multi-entity comparison but does not explicitly state when not to use or list alternatives.

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

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

The description discloses that partial failures degrade gracefully, noting bundlephobia's first measurement can take 5-30s and that sources_failed will list timeouts. It describes the return structure in detail. Annotations already mark it as read-only, idempotent, and non-destructive, and the description adds context beyond these.

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 efficient, packed with information without redundancy. It opens with the core purpose, explains mechanics, gives usage guidance, and displays limitations and output format. Every sentence serves a purpose, making it concise yet comprehensive.

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

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

The description covers all essential aspects: purpose, input parameters, output fields, failure modes, ecosystem scope, and alternatives. Despite no output schema, the description lists the return fields in detail, making the tool fully 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?

Schema coverage is 100% with clear descriptions for both parameters. The description does not add significant new semantic information about parameters beyond what the schema provides, such as the default behavior for version and acceptance of scoped packages, which are already in the schema. Thus, it meets the baseline but does not exceed it.

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

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

The description clearly states the tool is a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It specifies the scope ('NPM ecosystem only') and distinguishes from other tools by being a combined check. The purpose is precise 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?

Explicit usage scenarios are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also explains when not to use (other ecosystems) and directs to deps.dev:version directly for PyPI, Maven, etc. Clear guidance with no ambiguity.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive. The description adds no additional behavioral context such as rate limits, response structure, or how IOCs are presented, providing minimal value beyond structured fields.

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

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

The description is a single short sentence, front-loading the core purpose. It is appropriately sized with no wasted words, though it could include more detail without becoming 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?

With a single parameter and an output schema present, the description is minimally adequate but lacks explanation of what IOCs are returned (IPs, domains, etc.), pagination, or examples beyond the schema. Completeness is average for a simple 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%, and the description for the hash parameter duplicates the schema's type info (md5/sha1/sha256). No additional semantic value is added beyond what the schema already provides.

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

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

The description clearly states the tool returns IOCs associated with a file hash, specifying hash types (md5, sha1, sha256). It distinguishes from siblings like search_ioc which may handle broader IOC searches.

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?

Implied usage when you have a file hash and want associated IOCs, but no explicit guidance on when not to use it or which alternative tools (e.g., search_ioc, resolve_entity) might be better suited.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by specifying returned fields (malware family, confidence, threat-type, etc.) and clarifying the indicator types. 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?

Two sentences, zero waste. Front-loaded with verb and resource, followed by return fields listing. Every sentence earns its place.

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

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

System indicates output schema exists, so return format is covered. Description includes return fields and indicator types. Sufficient for a simple lookup tool with good annotations.

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

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

Schema coverage is 100%, so description adds minimal meaning beyond schema. It mentions 'indicator' but does not elaborate on formats or constraints. Baseline 3 is appropriate.

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

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

Description uses specific verb 'Look up' with resource 'indicator of compromise' and lists example types (IP, domain, URL, hash). It clearly distinguishes from siblings like search_hash (which is more specific) and search_malware (broader).

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

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

Description implies usage for IOC lookup but provides no explicit guidance on when to use this tool versus siblings. No exclusions or alternatives are mentioned.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no further behavioral context (e.g., pagination, rate limits). With good annotations, a 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?

Very concise, single sentence. However, the sentence is grammatically incomplete (starts with 'IOCs'), which slightly reduces clarity. No fluff.

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

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

Given the simple 2-parameter schema with 100% coverage, strong annotations, and an output schema, the description is adequate but does not fully explain what 'IOCs' include or how results are structured.

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 clear descriptions. The description adds minimal context beyond the schema (tying IOCs to malware families).

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 it returns IOCs associated with a malware family, which is clear. However, it uses a noun phrase rather than a verb, and could more explicitly describe the action (e.g., 'Search for IOCs'). It distinguishes from siblings like search_hash by focusing on malware families.

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

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

No guidance on when to use this tool vs alternatives such as search_ioc or search_hash. The description does not mention scenarios or exclusions.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds detail on embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and output features (offsets for verification). 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?

Single paragraph with efficient structure: purpose, usage guideline, pairing suggestion, technical details. Every sentence provides unique value; no redundancy.

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

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

Despite no output schema, the description explains output format (top-N passages with offsets and scores). Covers behavior, limits, algorithm, and integration context. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with concrete query examples and clarifies the text parameter's max length, going beyond schema definitions.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the verb ('search') and resource ('a fetched record'). It distinguishes from siblings by explicitly contrasting with fetching whole documents and pairing with ask_pipeworx_grounded.

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 when the record is too big to cram into the prompt.' Also offers guidance on pairing with ask_pipeworx_grounded, effectively directing the agent on alternatives and complementary tools.

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

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

Annotations provide basic hints, but description adds rich behavioral details: account requirements, delivery channels with limits (10/day SMS cap), webhook HMAC signing, and auto-disable after 10 consecutive failures. No contradictions with annotations.

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

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

Well-structured with clear sections: purpose, requirement, types, delivery channels. Every sentence adds value, though somewhat lengthy. Front-loaded with core purpose.

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

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

Given 3 parameters, no output schema, the description covers account requirements, all subscription types, delivery options, and mentions return value. Comprehensive for a subscription creation 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 covers 100% with descriptions. Description adds meaningful value by providing concrete examples for each type (e.g., sec_8k items, polymarket_edge topic) and elaborates on delivery channel specifics beyond schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create), resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe. Also mentions returns subscription id.

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 on when to use (proactive monitoring of specific events) and prerequisites (Pipeworx OAuth account). Mentions limitations (anonymous/BYO cannot persist). Lacks explicit alternatives or when-not-to-use, but context from sibling list is available.

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

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

Annotations already declare read only, idempotent, open world, and non-destructive. The description adds that it returns category-bucketed examples with exact tool+argument shapes, and that calling with no arguments gives a full spread. No contradictions.

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

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

The description is well-structured, front-loaded with trigger phrases and purpose. Every sentence contributes valuable information. Slightly lengthy but appropriate for the onboarding use case.

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

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

Given the simple one-parameter schema, comprehensive annotations, and no output schema, the description fully covers what the tool does, how to use it, what it returns, and when to use it. No gaps for an agent to call it correctly.

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

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

Schema coverage is 100% and the schema already describes the 'topic' parameter well. The description reinforces its purpose and values but adds limited new semantic meaning beyond the schema, so 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 is the 'onboarding entry point' that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs ('suggest questions', 'learn how to call') and distinguishes from siblings like 'discover_tools' by positioning itself as the first tool to use.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on passing a topic for focus. Lacks explicit 'when not to use' but context makes it clear.

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

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

The description adds significant behavioral details beyond annotations: it explains that the row is deactivated (not deleted), historical events remain available via recent_alerts, and ownership is enforced. This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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

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

The description is concise, with two sentences that front-load the primary action and efficiently convey essential context. No extraneous information.

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

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

Given the simplicity of the tool (one parameter, no output schema) and presence of annotations, the description covers key aspects: action, ownership, and side effects. It is nearly complete, though could mention how to obtain the subscription id (e.g., via list_subscriptions).

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 single parameter id, describing it as a uuid from subscribe. The tool description does not add additional semantic value beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (Cancel a subscription by id) and the resource (subscription). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation action and ownership enforcement.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like list_subscriptions or recent_alerts. It mentions ownership enforcement as a prerequisite but does not advise the agent on scenario applicability.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: returns a verdict with structured fields, actual value with citation, percent delta, and explains underlying sources (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is concise at 4-5 sentences, front-loaded with example trigger phrases, and covers purpose, usage, scope, and return format without fluff. 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?

Despite no output schema, the description explains the return format (verdict, structured form, actual value, citation, percent delta) and data source. For a simple one-parameter tool, this is sufficient. Could mention error cases or claim format requirements, but overall 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 a clear description for the 'claim' parameter. The tool description adds meaningful context beyond the schema: example claims, domain restriction to company-financial, and implicit guidance on claim format. This raises the baseline from 3 to 4.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It defines the specific domain (company-financial claims for US public companies) and contrasts with alternatives by mentioning it replaces multiple sequential calls. The verb 'validate' and resource 'claim' are 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 explicitly asks to use this tool when the agent needs to check factual correctness, with example trigger phrases. It implies scope (US public companies, financial claims) but does not explicitly state when not to use it or name alternative tools. Still, usage context is clear.

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