Giphy

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details: probes one or more LLMs, requires API key for Anthropic (cost implication), and returns per-model fields. 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?

Four sentences, each contributing unique information: core function, model options, return structure, use cases. No redundancy, well-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?

Covers parameters, return fields, and common use cases. Lacks discussion of error handling (e.g., missing API key for Anthropic) and edge cases, but sufficient for typical 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 examples for entity and context, notes default model for models parameter, and explains _apiKey is passed through. This adds 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?

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model and optional Anthropic probing, and the use cases (AI-marketing audits, brand checks) differentiate it from siblings like scan_competitor_ai_presence.

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

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

The description explicitly mentions when to use (pre-launch brand checks, competitive monitoring) and provides context on default vs. paid model. However, it does not explicitly state when not to use or directly compare to sibling tools, slightly reducing clarity.

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, indicating safe, non-destructive behavior. The description adds context about returning structured answers with stable pipeworx:// citation URIs and routing to many tools, which enriches transparency beyond the annotations.

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

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

The description is front-loaded with a strong directive ('PREFER OVER WEB SEARCH') and uses bullet-like list of examples. While slightly long, every sentence adds value, and it avoids 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 vast scope (3,745 tools), the description covers key aspects: what it does, when to use, the quality of output (citations), and examples. It lacks only explicit details on rate limits or error handling, but these are not critical for a read-only, open-world tool.

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

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

Schema coverage is 100% with clear descriptions of the 'question' parameter and its aliases. The description adds little beyond the schema, as it only reiterates that the tool accepts natural language questions. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's purpose: answering factual questions about current/historical data from many sources, preferring over web search. It lists specific categories like SEC filings, FDA data, etc., and distinguishes it from alternatives like web search and sibling tools such as 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?

The description explicitly tells when to use this tool over web search, provides trigger phrases like 'what is', 'look up', 'find', and gives concrete examples. It covers a wide range of scenarios and instructs the AI to prefer this tool for factual 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?

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are fully honored. The description adds critical behavioral details: outputs are strictly extracted from tool results, returns explicit refusal reasons on failure, costs one extra LLM call, and routes through the same mechanism as ask_pipeworx. 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 150-word description is densely informative. It front-loads key concepts (hallucination-resistant, same routing, strict extraction), defines return format with refusal reasons, and provides usage boundaries. Every sentence adds value; no filler.

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

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

Despite having no output schema, the description fully details the return object fields (answer, evidence, confidence, source, etc.) and all possible refusal reasons. It explains the tool selection mechanism and cost trade-off. For a high-complexity tool with 6 params and many siblings, this is complete.

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

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

Schema coverage is 100% with all 6 parameters (aliases) described. The description adds context by referring to the question as 'natural language' and explaining its role in routing. This goes beyond the schema's simple alias listing, but the schema already does heavy lifting.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads. It specifies the verb (answer extraction), resource (tool results from 3,745 tools across 884 sources), and distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and strict evidence-only output.

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

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

Explicitly tells when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with examples like financial verdicts and medical lookups. Also advises preferring ask_pipeworx for casual lookups, providing clear 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 already indicate read-only, idempotent, safe behavior. The description goes far beyond by detailing resolution logic, fan-out examples, response shapes, edge cases (low-confidence match, closed markets, wide spreads), and resolution-rule risk. 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 comprehensive but verbose. It front-loads the core purpose, but then includes many examples and details that could be trimmed or structured better. Still, it is organized into logical sections.

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 (classifiers, fan-outs, edge cases) and no output schema, the description is remarkably complete. It covers all important behavioral aspects and result structures, ensuring an agent can understand what to expect.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by explaining what market input formats are accepted, defining the depth enum values, and clarifying the include_raw default and its trade-offs.

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 a clear verb+resource ('Research a Polymarket bet') and explains what it does: pull Pipeworx data, resolve market, classify, fan out, return evidence. It distinguishes from siblings by focusing on Polymarket bet research, though it doesn't explicitly name alternatives.

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 use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). However, it does not mention when not to use this tool or suggest alternatives from the sibling list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of pipeworx:// citation URIs. No contradictions.

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

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

The description is dense but well-structured: starts with example queries, states usage preference, explains data sources per type, and mentions output format (sorted, with citation URIs). Every sentence adds value without redundancy.

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

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

Despite no output schema, the description covers return format (paired data + citation URIs), sorting behavior, and data freshness (latest 10-K for companies). It fully addresses the tool's complexity with two entity types, input constraints, and output clarity.

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% (both parameters described). The description adds meaning beyond the schema by explaining the format of values (tickers/CIKs for company, names for drug), enumerating the type options, and specifying min/max items (schema already has these). It also details what data each type retrieves, enriching 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?

The description clearly defines the tool's purpose: side-by-side comparison of 2-5 entities (companies or drugs). It uses specific verbs ('compare', 'rank') and resource words ('companies', 'drugs'). It distinguishes itself from siblings like entity_profile by noting it replaces sequential lookups.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides example queries. It differentiates between entity types and gives specific data sources per type, offering clear context for usage.

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

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

Discloses key behaviors beyond annotations: parallel execution, citation format, explicit gap handling, expected latency (15-60s). 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?

Relatively long but every sentence serves a purpose. Front-loaded with key capability. Could be slightly more concise but no waste.

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

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

Despite no output schema, description thoroughly covers return structure (findings packet with citations, gaps), prerequisites, and expected behavior. 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% (baseline 3). Description adds practical details: depth values map to facet counts, question accepts broad multi-part queries. Provides 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?

Clearly describes the tool's core functionality: grounded multi-source research via parallel decomposition. Distinguishes from sibling 'ask_pipeworx' by contrasting broad vs single lookups.

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

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

Explicitly states when to use (broad/multi-part questions), when not to (single lookups: use ask_pipeworx), and prerequisites (Pipeworx account, paid plan for thorough depth).

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 set readOnlyHint=true and destructiveHint=false. Description adds that it returns top-N tools with full schemas and 'curated examples', and that results are ready to call directly. 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 informative but somewhat long (six sentences). It is well-structured with a clear opening, list of domains, and key return details. Could be slightly more concise.

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

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

Given the complexity (discovery tool) and no output schema, the description fully explains what the tool returns (tool names, descriptions, schemas) and provides usage context. 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 mentions 'query' and 'limit' but does not add meaningful information beyond the schema's descriptions (e.g., aliases are already in schema). Minimal value added.

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 (SEC filings, FDA drugs, etc.). It distinguishes from sibling tools by being the discovery mechanism for all other 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This guides when to use it versus 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 already indicate safe, read-only, idempotent behavior. The description adds rich behavioral context: it fans out across multiple sources, lists specific return fields, mentions patent sunset and news fallback, and explains input constraints. No contradiction with annotations.

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

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

The description is a single paragraph with a lot of detail, but it front-loads example queries and key guidance. It could be slightly more structured (e.g., bullet points for return fields), but it remains informative without being overly verbose.

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

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

Given the tool's complexity (multiple data sources, fallbacks, input constraints) and the lack of an output schema, the description fully covers return values, caveats (patent sunset, GDELT→GNews fallback), and usage instructions, making it self-contained.

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

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

The schema has 100% description coverage, but the description adds crucial meaning: it clarifies that 'type' is currently limited to 'company' with future expansion, and explains that 'value' accepts ticker or CIK (not names), enhancing the agent's 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 uses clear, specific verbs and resources (e.g., 'full cross-source profile of a US public company in ONE parallel call') and distinguishes itself from sibling tools like 'resolve_entity' by specifying input requirements and when to prefer this tool over chaining individual lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides clear guidance on unsupported inputs ('Names not supported — use resolve_entity first if you only have a name').

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about 'clearing sensitive data' but does not discuss idempotency (annotated true) or any side effects beyond deletion.

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?

Extremely concise: two sentences that front-load the action and usage context without any unnecessary words.

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

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

For a simple 1-parameter tool with annotations, the description covers purpose and usage well, but does not mention return values, error cases, or confirm the idempotent behavior hinted by annotations.

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

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

Schema description coverage is 100% for the single 'key' parameter, and the description adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states the action 'Delete a previously stored memory by key', with a specific verb and resource. It distinguishes from siblings by referencing '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 provides contexts for use: 'stale context', 'task done', 'clear sensitive data'. Also suggests pairing with alternative tools (remember, recall), giving clear guidance on when to use this tool.

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

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

The description discloses fetching the page, extracting title/description/key links, and emitting standard markdown. Annotations already provide readOnlyHint and idempotentHint, so the description adds useful 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?

The description is concise with three focused sentences, no redundancy, and front-loaded purpose. 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?

Given the tool's simplicity (2 parameters, no output schema) and rich annotations, the description covers input, process, output, and use cases adequately. No gaps for typical usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples (e.g., 'https://example.com') and specifies defaults and maximums for max_links, offering value 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 generates a production-ready llms.txt file for any URL, with specific actions (fetch, extract, emit). It distinguishes implicitly from sibling tools like scan_competitor_ai_presence by focusing on generation rather than scanning.

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 (indexing a client's site, drafting for own project, auditing competitor). However, it does not mention when not to use or provide explicit alternatives, though no direct competitor exists among siblings.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already disclose safety and idempotency. The description adds that it returns active subscriptions by default and the include_inactive parameter controls inclusion of cancelled ones, providing additional 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 sentences: first states purpose and return fields, second provides usage guidance. No waste, 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?

Given no output schema, the description provides return fields. It covers parameter behavior and usage. Lacks mention of pagination or limits, but for a simple list tool with one optional parameter, this is nearly complete.

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

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

The schema covers the single parameter (include_inactive) at 100% with a description. The tool description adds usage context (review before adding, find id to cancel), enriching the parameter's purpose 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 lists the caller's active subscriptions and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context 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?

Annotations indicate non-readonly, non-idempotent, non-destructive. Description adds value: rate-limited to 5 per identifier per day, free, team reads digests daily. No contradictions.

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

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

Five concise sentences with clear structure: purpose first, then usage conditions, then tips, then constraints. No wasted words.

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

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

Given 3 parameters (nested object) and no output schema, description covers all needed context: what feedback types, what to include, rate limits, and that it's free. Complete for correct invocation.

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

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

100% schema coverage already explains parameters. Description reinforces 'type' enum usage and adds guidance on 'message' content (specific, 1-2 sentences, 2000 chars max), exceeding 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?

Description clearly states it's for sending feedback to Pipeworx team about bugs, features, data gaps, or praise. Unambiguous verb+resource, well-differentiated from sibling tools (none are feedback-related).

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 rules: use for wrong/stale data (bug), missing tools (feature/data_gap), or praise. Includes what not to do (don't paste end-user prompt) and constraints (rate limit, free, no quota).

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and output structure (pack, tool, count). 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 with a clear front-loaded purpose and numbered use cases, though slightly long. Every sentence adds value.

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

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

Given the simple input (one optional parameter, no output schema), the description fully covers input behavior, output structure, data source, privacy, caching, and use cases, making it complete for agent decision-making.

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

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

Schema already covers the window parameter with 100% description coverage. The description adds practical guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enriching 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 returns top tools, top packs, and total call volume over a recent window, using specific verbs and resource descriptions. It distinguishes from siblings like discover_tools and trending_gifs by focusing on Pipeworx call aggregation.

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 enumerates three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and notes window duration behavior. While it doesn't explicitly state when not to use, the context is clear enough to guide selection.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: monotonicity checks, partition-sum validation, Jaccard similarity threshold (>=0.30), placeholder filtering, and the fill check using live order book depth. 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 structured with clear sections (requirements, event mode, topic mode, semantic anchor, partition filter, fill check). It front-loads the key constraint. While verbose, every sentence adds value for a complex tool; minor redundancy could be trimmed.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context, partition_check, fill check). It covers edge cases (placeholder filtering, fill risk). Completeness is high for a 2-parameter tool with no nested objects.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: explains event vs topic modes, provides example values (slugs and seed questions), and clarifies behavior differences (single-event vs cross-event). This goes 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples. It differentiates from sibling tools like polymarket_edges, polymarket_fill_risk, and polymarket_kalshi_spread.

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 requires one of event or topic, warns against calling with no args, recommends event for specific markets and topic for cross-event scanning, and provides examples. It includes exclusions (partition filter drops placeholder slugs) and alternative tools (polymarket_fill_risk for custom sizing).

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints, which the description fully supports. It adds extensive behavioral context: edge calculation (edge_pp_net, Kelly), three model families, slippage, filters, caching (1h KV-level), and diagnostic output for empty segments. 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 lengthy (~400 words) but well-structured with segments and knob lists. It front-loads the purpose but includes repetitive technical details. Could be more concise while retaining clarity.

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 comprehensively explains response structure (by_segment, diagnostics), edge calculation, filters, and caching. It leaves little ambiguity for an agent to understand inputs and outputs.

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

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

Schema coverage is 100% with good descriptions for all 9 parameters. The description adds slight context for min_partition_leg_kelly but mostly duplicates or extends schema info. Baseline 3 is appropriate as the schema carries the burden.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific verb (Scan/return) and resource (opportunities), and differentiates from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across three model 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?

The description provides usage context with 'what should I bet on today' and explains tradeable-edge knobs. It implicitly distinguishes from alternatives, e.g., Fed bets are excluded from ranking. However, it does not explicitly state when to use other tools, leaving some 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: snapshot gaps due to cache-miss, TTL-bound history, and decay computed from daily closes (not intraday). 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 well-structured: start with purpose, then detailed response fields, then limitations. It is front-loaded with the core purpose. While slightly long, 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 absence of an output schema, the description fully explains the return values: tracked[], expired[], and snapshot_dates[], including detailed fields like trend, decay_pp_per_day, lifespan_days, and notes on data gaps. It also covers limitations (TTL, snapshot 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?

The input schema has 100% coverage. The description adds meaning by providing default values and ranges for 'days' (default 14, max 30) and explaining the 'window' options (24hr, 1wk, 1mo with default 1wk), enhancing the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and the specific question it answers: 'how long has this edge existed and is it shrinking?' It uses a specific verb+resource combination and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description implicitly provides usage context by contrasting a fresh wide edge with a 3-week-old wide edge, indicating when to use this tool to assess edge age. However, it does not explicitly state alternatives or when not to use it.

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

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

Description extensively details behavioral aspects beyond annotations (which already indicate read-only, idempotent, open world): it explains order book walking, output fields (top_of_book, vwap_fill_price, slippage, verdicts), basket-mode details (theoretical vs realizable sum, thin_legs, forced_directional_risk), and warnings about partial fills. 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 relatively long but well-structured: first sentence defines core purpose, then conditions, then mode-specific details, then usage guidance. Every sentence adds necessary context for a complex tool. A bit verbose but justifiably so.

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

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

Given the tool's complexity (two modes, multiple outputs, no output schema), the description is remarkably complete: it lists return fields for both modes, explains the risk of partial fills and directional risk, and references sibling tools. Annotations are present but the description fully compensates for the lack of an 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?

All 4 parameters are described in the schema (100% coverage), but the description adds meaning: explains side default logic per mode, clarifies size_usd interpretation for single-market vs basket, and provides constraints (clamp 10–1,000,000). This adds value beyond the minimal baseline of 3.

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

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

Description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with two modes (single-market and basket) and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use it before acting on those 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?

Explicitly states when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), explains the consequences of not using it ('partial basket fills convert an arb into an unhedged directional position'), and provides clear context for each mode.

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 numerous behavioral traits beyond annotations: the logic of comparing bet shapes, conditions for meaningful spreads, response structure (leg-by-leg prices, matched spread), and interpretation of safety fields. This is exceptionally transparent for a tool with authoritative annotations.

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

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

Although the description is long, every sentence adds value. It is structured with clear sections: overall purpose, two modes, response format, safety fields, and a caution. It is front-loaded with the key concept and uses bullet-like structure for readability.

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 the absence of an output schema, the description explains the response structure and edge cases (compatibility warnings, temporal alignment). All three parameters are covered, and limitations (real spreads are rare) are noted. The description is complete for an agent to understand when and how to use the tool.

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

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

Schema coverage is 100% and the description adds context about the two modes, including that topic is a shortcut with enumerated values and that explicit parameters override the mapped sides. Examples are provided, adding value beyond the parameter descriptions in the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and describes the output, differentiating it from sibling tools like polymarket_arbitrage.

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

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

Explicit guidance on when to use each mode, warnings that real spreads are rarer than pre-mapped list suggests, and explanation of safety fields that indicate when spreads are not meaningful (compatibility_warning, temporal_alignment). This is thorough and helps the agent decide when to call the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that the result includes title, URL, rating, and image URLs, which is useful but does not reveal additional behavioral traits beyond what annotations imply.

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

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

The description is a single concise sentence that front-loads the primary purpose and immediately mentions the optional filter. No extraneous words.

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

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

Given the simple functionality, full parameter coverage in schema, and existence of output schema, the description is complete enough. It mentions the key fields returned, leaving no ambiguity.

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

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

Schema coverage is 100% and the schema already describes 'tag' as optional with examples. The description restates this information without adding new meaning, 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 ('Get a random GIF') and the resource ('random GIF'), with an optional filter by tag. It differentiates from siblings 'search_gifs' and 'trending_gifs' which serve different 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?

The description implies usage for random selection, optionally filtered, but does not explicitly contrast with alternatives like 'search_gifs' or 'trending_gifs'. No when-not-to-use or prerequisite guidance is provided.

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

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

The description adds behavioral context beyond annotations: scoping to an identifier and pairing with other tools. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description does not contradict them.

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

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

The description is efficient: a single sentence for the core action, followed by usage context and pairing hints. No redundant 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 single parameter with full schema coverage and no output schema, the description provides sufficient context: retrieval versus listing, scoping, and relationship to other tools. Examples of saved data types enhance completeness.

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

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

Schema coverage is 100% and the schema description already covers the parameter's behavior (omit to list all keys). The description reiterates this but does not add significant new detail, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('retrieve' or 'list') and resource ('value saved via remember' or 'all saved keys'). It distinguishes this tool from siblings like 'remember' and 'forget' by explicitly pairing with them.

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

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

The description explains when to use ('to look up context the agent stored earlier') and provides an example of use cases ('user's target ticker, address, prior research notes'). It does not explicitly mention when not to use or alternative tools, but the purpose is clear.

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

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

The description adds behavioral details beyond annotations, such as mark_read side effects and polling safety. 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 that covers purpose, return format, parameters, and usage. Could be slightly more concise but is effective.

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

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

For a tool with 5 parameters and no output schema, the description thoroughly covers purpose, return fields, parameter behavior, and usage context (polling, alternative endpoint). Very 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%, but description adds meaningful context for type, since, and mark_read, explaining their behavior and output fields. Adds 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?

The description clearly states the tool pulls fired events from subscription feeds, using specific verbs and resource. It implicitly distinguishes from siblings like 'list_subscriptions' by focusing on alerts.

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

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

It mentions polling works fine and provides an alternative endpoint, offering context for when to use this tool. Lacks explicit when-not-to-use or alternatives, but the guidance is adequate.

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 detailed behavioral traits: fans out to multiple sources (SEC EDGAR, GDELT, GNews, USPTO), fallback logic, and soft-fail for patents. This adds significant context beyond the annotations which already indicate read-only, open-world, and idempotent behavior.

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

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

The description is front-loaded with example queries for quick understanding. It is somewhat long but each sentence provides necessary detail about sources and behavior. Could be slightly more condensed, but overall well-structured.

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

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

Given the tool's complexity (multiple sources, fallback, date parsing) and the presence of rich annotations but no output schema, the description covers return structure (changes[], total_changes, citation URIs) and error behavior (e.g., soft-fail for patents). It is fully complete for effective 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 meaningful context beyond schema: examples of relative date formats ('7d', '30d', '3m', '1y') and explanation of the value parameter accepting ticker or CIK. However, the description does not detail all parameter constraints beyond what's in the schema.

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

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

The description clearly defines the tool as a change feed for a company over a recent window, with specific verb phrases like 'what's new with X' and 'latest on Y'. It distinguishes from the sibling tool entity_profile by explicitly stating when to use that instead.

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

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

Provides explicit guidance on when to use this tool vs. entity_profile: 'Use entity_profile instead when you want the static profile'. It also explains the supported entity type and the fallback mechanism between GDELT and GNews.

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 key behavioral details beyond annotations: storage as key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users (24-hour retention). No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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, each serving a purpose: purpose, usage, scoping/durability, and pairing with siblings. No redundant information; front-loaded with the core action.

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

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

Comprehensive for a write tool with no output schema: covers use case, storage semantics, scoping, and temporal behavior. No missing critical information.

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 'key' and 'value'. Description adds contextual examples ('subject_property', 'target_ticker') and usage hints (store findings, addresses), enhancing understanding 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 'Save data the agent will need to reuse later', specifying the verb (save), resource (data), and scope (across conversations/sessions). It distinguishes from sibling tools like 'recall' and 'forget' by positioning itself as the write operation.

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: 'when you discover something worth carrying forward'. Mentions pairing with 'recall' and 'forget'. Lacks explicit when-not guidance, but usage context is well-defined.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by noting internal cascading through multiple endpoints, effectively replacing 2-3 manual lookups, and mentions auto-disambiguation for company input. 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 with examples front-loaded. It is slightly long but each sentence adds value—examples, use instruction, supported types, return types. Could be trimmed slightly, but overall efficient.

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

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

For a tool with no output schema, the description thoroughly explains return values for each type: company returns ticker, CIK, name, and citation URI; drug returns RxCUI, ingredient, brand. It also mentions internal complexity and input formats, making the tool fully understandable.

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

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

Schema coverage is 100% and the description goes beyond by providing concrete examples for both parameters (e.g., 'AAPL' for ticker, '0000320193' for CIK, 'ozempic' for drug). It clarifies the enum values for type and explains the format and use of each input, adding significant meaning.

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

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

The description clearly states the tool resolves a name to a canonical identifier, with specific examples like 'ticker for...' and 'find the CIK for...'. It differentiates itself by noting it should be used first when having a name but needing an ID, and it lists supported entity types, which helps distinguish from sibling tools.

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

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

Explicit instruction to 'Use FIRST whenever you have a name but need an ID' sets clear context. The description also explains what each type returns and accepts as input. It does not mention when not to use or direct alternatives, but the guidance is sufficient for a simple lookup tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds value by explaining the probing process, ranking, and return fields (score, confidence, signal density). No contradiction with annotations.

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

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

The description is two sentences: a concise summary followed by an elaboration with an example. Every sentence is necessary and adds value. It is front-loaded and efficient.

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

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

No output schema, so description must explain return values; it does so with 'ranked list with score, confidence, signal density per entity.' However, it lacks details on error handling, sorting order, and what 'signal density' means. Slight gaps but overall adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by noting that the first entity is treated as the 'subject' for narrative, which is not in the schema. This provides meaningful context beyond parameter descriptions.

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

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

The description states a specific verb ('Compare AI visibility across multiple entities side-by-side') and resource, and distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (generic). It clearly explains what the tool does.

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

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

The description provides clear context ('useful for competitive AI-marketing audits') and implies when to use it, but does not explicitly state when not to use it or differentiate from all alternatives beyond mentioning the underlying 'ai_visibility_check'.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds transparency about partial failures, timeouts (5-30s for bundlephobia), graceful degradation, and the return structure (summary block, per-advisory detail, links, alternative versions). This goes beyond annotations, though could mention rate limits or auth requirements.

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

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

The description is detailed but every sentence adds value. It is front-loaded with the main purpose and includes relevant caveats. Slightly verbose but not padded; earns its length.

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

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

With no output schema, the description compensates by listing exact return fields (summary block with is_latest, license, etc., per-advisory detail, links, alternative versions). It also covers failure modes and scope limitations. Highly complete for an information-gathering tool.

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

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

Schema coverage is 100%, baseline is 3. The description adds context: explains that package accepts scoped packages, version defaults to latest. It does not repeat schema but adds usage nuance, exceeding the baseline.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, fanning out across deps.dev and bundlephobia. It distinguishes from siblings by specifying it's for npm packages only and mentions fallbacks for other ecosystems. The verb 'scan' accurately reflects the action.

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

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

The description explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. It also excludes other ecosystems, directing to deps.dev:version directly, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds useful behavioral context by listing the returned fields (title, URL, rating, image sizes), which goes beyond the annotations.

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

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

The description is a single sentence with no extraneous information, efficiently conveying the tool's purpose and return format.

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

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

Given the full schema coverage, rich annotations, and existence of an output schema, the description is complete enough. It specifies the external source, action, and primary output fields.

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 parameter schema has 100% coverage with descriptions and examples, so the description adds minimal value by merely echoing 'by keyword'. The baseline of 3 is appropriate.

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

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

The description clearly states the tool searches Giphy for GIFs by keyword and specifies the return fields. It distinguishes the tool from siblings like random_gif and trending_gifs through its focus on keyword search, but does not explicitly differentiate.

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 usage context is implied by the keyword-based search description, but no explicit guidance is given on when to use this tool versus sibling tools such as random_gif or trending_gifs.

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 the tool as read-only, idempotent, open-world, and non-destructive. The description adds behavioral context beyond annotations: internal mechanism (BGE-base-en embeddings, cosine over 500-char windows), character cap (200K with truncation flagging), and output features (offsets for verification). No contradiction.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then provides usage instructions, a use case, pairing with a sibling, and technical details. Every sentence adds value with 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?

Despite no output schema, the description fully explains the output format (passages, offsets, scores), behavior (cap, truncation), and use case. It covers all essential aspects for an agent to correctly select and invoke the tool, given the complexity and context signals.

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 value by explaining the usage pattern for text and query parameters, providing example queries, and clarifying the limit parameter's purpose and default. This enriches the 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 does semantic search inside a fetched record. It specifies the inputs (text and query), outputs (passages with character offsets and similarity scores), and distinguishes it from sibling ask_pipeworx_grounded by explaining they pair together.

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

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

The description gives explicit guidance on when to use ('when the record is too big to cram into the prompt') and mentions pairing with ask_pipeworx_grounded. It does not explicitly state when not to use, but the context implies alternatives exist.

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=false, destructiveHint=false, and idempotentHint=true. The description aligns by confirming it's a creation operation, and adds critical behavioral details: account prerequisites, delivery caps, webhook signing, and auto-disable after 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?

The description is longer than average but well-structured with bullet points and examples. It front-loads the core purpose and each sentence adds value. Minor redundancy could be trimmed, but overall it remains clear and accessible.

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 (3 parameters, nested objects, no output schema), the description comprehensively covers all inputs, supported types, delivery channels, constraints, and side effects. It mentions the return value (subscription id) and addresses prerequisites like phone verification. No gaps identified.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema by providing per-type examples (e.g., items codes for sec_8k, topic for polymarket_edge), and delivery channel details (SMS cap, webhook signing secret retrieval). This goes beyond the schema's minimal 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 creates a proactive monitoring subscription to a live-data event stream and returns a new subscription id. It uses a specific verb ('subscribe') and resource ('subscription to a live-data event stream'), and effectively distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides extensive usage context: requires a Pipeworx OAuth account, lists supported types with concrete examples, and details delivery channels including always-on feed and optional email/sms/webhook with constraints. It implicitly tells when to use (creating a subscription) and offers clear guidance on alternatives via the context of 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?

Description adds behavioral details beyond annotations: it returns category-bucketed example questions with exact tool + argument shape, drawn from a live catalog. Annotations already declare readOnly, openWorld, idempotent, non-destructive, so description complements well.

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 thorough but somewhat lengthy; could be tightened without losing key information. Front-loads purpose well, but the detailed list of topic categories adds some verbosity.

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 and a single optional parameter, the description covers the tool's purpose, usage scenarios, parameter behavior, and expected output format. It is complete enough for an agent to understand when and how to invoke it.

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

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

Schema has 100% coverage for the single optional parameter. Description adds semantic value by listing concrete topic values (finance, pharma, etc.) and explaining that omitting the parameter gives a cross-category spread, beyond the schema's generic description.

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

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

The description clearly states that the tool returns example questions to help users understand what Pipeworx can do, and distinguishes it from the direct query tool 'ask_pipeworx'. The title and description align to convey onboarding purpose.

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

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

Explicitly recommends use when the agent does not know what Pipeworx can do, and specifies that omitting the topic gives a full spread or passing a topic focuses the results. Does not explicitly state when not to use, but context makes it clear it's for initial discovery.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and behavior. The description adds that the tool 'returns title, URL, rating, and multiple image sizes,' which provides output context but does not reveal additional behavioral traits (e.g., rate limits, data freshness). The description adds modest value beyond annotations.

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

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

The description is a single, concise sentence that directly states the tool's purpose without extraneous detail. It is front-loaded but lacks explicit usage guidance relative to siblings, which slightly reduces efficiency.

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 (one optional parameter, no required fields) and the presence of an output schema (not visible but noted), the description covers return fields adequately. However, it omits details like pagination, ratings filter, or how trending is determined, which could be useful for an agent. Still sufficient for basic 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?

The single parameter 'limit' is fully described in the schema (100% coverage), so the description need not add parameter details. It does not provide additional semantic meaning about the parameter beyond what the schema already includes. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves trending GIFs from Giphy and specifies the returned fields (title, URL, rating, multiple image sizes). This distinguishes it from sibling tools like 'search_gifs' and 'random_gif', and uses a specific verb-resource pair.

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 obtaining trending content but does not explicitly state when to use this tool versus alternatives like 'search_gifs' or 'random_gif'. No when-not-to-use or comparative guidance is provided, leaving the agent to infer 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?

Goes beyond annotations: explains that the subscription is deactivated (not deleted) and that historical events remain available. Aligns with annotations (destructiveHint=false, idempotentHint=true). 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 concise sentences, no wasted words. Information is front-loaded and efficiently communicated.

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 key behavioral aspects (ownership, deactivation) for a simple cancellation task. Could mention return value or error scenarios, but not critical given low 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 covers parameter 'id' with description; description adds no extra meaning beyond stating usage 'by id'. Baseline 3 for 100% schema coverage.

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

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

Clearly states the action ('Cancel') and resource ('subscription by id'). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation and the 'by id' scope.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions') and explains the deactivation approach, guiding when to use this tool. Does not explicitly list alternatives, but context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context about the return format (verdict, structured form, citation) and the underlying data sources (SEC EDGAR + XBRL), which goes beyond the annotations.

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

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

The description is front-loaded with trigger phrases and a clear purpose. It is slightly verbose but every sentence adds value, covering usage, domain, replacement of multiple calls, and output. Could be tightened slightly without losing 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 adequately explains the return values (verdict, structured form, actual value with citation, percent delta). It specifies the domain (company-financial) and data sources, and provides usage examples. No missing critical information.

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 'claim' has 100% schema description coverage. The description adds natural-language examples and clarifies the expected format and domain, making it more helpful than the schema alone.

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

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

The description clearly defines the tool as a natural-language claim verification tool against authoritative sources, specifically for company-financial claims. It includes trigger phrases and examples, distinguishing it from general search or fact-checking tools in the sibling list.

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

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

The description explicitly states to use it when the agent needs to check factual correctness and specifies the domain (company-financial claims). It mentions it replaces multiple sequential calls, but does not explicitly state when not to use it (e.g., non-financial claims), which would be a minor improvement.

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