Data Seattle

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

Annotations already declare safe, read-only, idempotent behavior. The description adds value by disclosing the payment model (BYO key for Anthropic), the return structure (per-model data + combined view), and the default model. 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 three sentences, front-loading the core purpose and then providing model details and return format. Every sentence is informative without redundancy.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no nested objects), the description fully covers behavior, return data structure, and use cases. Annotations provide safety profile. The description is 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?

Input schema has 100% coverage with good descriptions. The tool description further enriches parameter meaning by explaining the default model behavior and the role of `_apiKey`. With full schema coverage, the baseline is 3; the added context justifies a 4.

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

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

The description uses a specific verb-resource pair ('probe...LLMs') and clearly defines the tool's output (visibility score 0-100 per model). It distinguishes from siblings by focusing on probing AI knowledge rather than scanning competitor presence, which is a different use case.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides model selection guidance (default free model, optional Anthropic with BYO key). It does not mention when to avoid this tool or name specific sibling alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds behavioral details: uses 4,774 tools across 1242 sources, returns structured answer with stable pipeworx:// citation URIs, works on every tier, one fast call. No contradictions.

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

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

The description is well-structured with a strong opening directive ('PREFER OVER WEB SEARCH') and clear sections for usage, examples, and alternatives. While a bit lengthy, every sentence adds value; it could be slightly tighter but remains effective.

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

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

Given no output schema, the description fully explains the return format (structured answer with citations). It covers scope (4774 tools, 1242 sources), usage boundaries (when to use alternatives), and behavioral traits (fast call, works on all tiers). Complete for an AI agent to decide when to invoke.

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 minimal extra meaning beyond the schema's description for 'question' parameter ('Your question or request in natural language'). The schema also lists aliases. Baseline 3 is appropriate; description does not significantly enhance parameter understanding.

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

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

The description specifies a verb ('routes') and resource ('question to one of 4,774 tools'), exactly states what it does: returns structured answers with citations for factual queries. It clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives specific when-to-use criteria (any factual question about real-world entities, events, or numbers) and when to step up (e.g., ask_pipeworx_grounded for hallucination-resistant answers). Provides examples and contrasts with 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?

Discloses refusal mechanics, return format, and extra LLM call cost. Annotations already indicate safe read, so no contradiction. Adds value beyond annotations.

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

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

Front-loaded with purpose, then usage guidelines. Includes some redundant details (e.g., exact counts of tools/sources) 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?

Comprehensively explains return format, failure modes, and cost. No output schema, but description fully covers what agent needs to know.

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 alias descriptions. Description adds minimal extra meaning beyond 'Your question in natural language.' 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, distinguishing itself from ask_pipeworx. Provides specific verb: extracts answer using only tool result.

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

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

Explicitly says when to use (when answer will be quoted/cited/acted on) and when to prefer sibling (casual lookups). Also mentions extra cost.

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 is exceptionally transparent, detailing resolution logic, classifier categories, fan-out examples, response shapes (including market, analysis, evidence), safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. This goes far beyond the annotations (readOnlyHint, idempotentHint) and provides a comprehensive behavioral model.

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

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

The description is front-loaded with the core purpose but becomes verbose with extensive detail on classifiers, fan-out examples, and response shapes. While comprehensive, it could be more concise by organizing information more hierarchically or using bullet points. Every sentence is earned, but readability suffers from density.

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 (3 parameters, no output schema, many sibling tools), the description covers every aspect: input options, processing pipeline, classifier list, fan-out examples, response fields, resolver contract, parent_event extractor, news fallback notes, safety checks, and cancellation rules. It is exceptionally complete, leaving no gaps for an agent to fail.

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 marginal value by repeating the market input flexibility and clarifying include_raw's effect on response size. It does not elaborate on depth beyond the schema's enum. Overall, description adds little new insight 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 it researches Polymarket bets by pulling Pipeworx data. It specifies three input types (slug, URL, question) and outlines the process (resolve, classify, fan-out). This distinguishes it from siblings like polymarket_edges or ask_pipeworx, which have narrower focuses.

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

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

The description explicitly says to use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides concrete examples. However, it does not explicitly state when NOT to use this tool or mention alternatives like polymarket_edges for edge-specific 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs, enhancing transparency 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?

Description is moderately long but well-structured with examples first and details later. Could be slightly more concise, but front-loading of examples aids quick understanding.

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 2 entity types and multiple data sources, the description covers key aspects: data provenance, sorting, citation URIs, and handling of fiscal years. No output schema exists, but response format is hinted.

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 significant nuance: explains how 'type' and 'values' interact, gives examples for each type (tickers/CIKs for companies, drug names), and clarifies min/max constraints.

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 side-by-side comparison of 2–5 entities (companies or drugs), with specific data sources and sorting. It distinguishes from sequential single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example natural language queries, 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?

Goes beyond annotations by detailing the internal process (decomposition, parallel tool routing), expected output (findings packet with evidence, confidence, source, citations, gaps), and performance characteristics (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?

While the description is long, it is well-structured with critical information front-loaded (account requirement, alternative). Every sentence adds meaningful guidance, though some repetition exists (e.g., mentions of ask_pipeworx).

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, the description is remarkably complete: it covers prerequisites, behavior, output format, timing, and alternatives. With no output schema, it thoroughly explains what the agent can expect.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8) and reinforcing that the question should be natural language and multi-part, but baseline is already high due to 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 explicitly states it performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions into facets, and routes to 4,774 tools in parallel. It clearly distinguishes from siblings like ask_pipeworx by noting use cases for single lookups or current news.

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

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

Provides explicit when-to-use (broad/multi-part questions over structured data) and when-not-to-use (single lookups, current news), as well as an alternative tool (ask_pipeworx) and account requirements including a 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N most relevant tools with full input schemas and examples, ready to call directly. This adds behavioral context beyond annotations, though could mention potential result size limits.

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

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

The description is front-loaded with purpose and efficiently conveys all necessary information. While slightly long, every sentence adds value with no repetition.

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

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

Given the large number of sibling tools (30+), the description effectively explains the tool's role in the ecosystem. It states what the tool returns (names, descriptions, schemas) and that results are ready to call directly. No output schema, but the description covers the return content adequately.

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

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

Schema coverage is 100% so baseline is 3. The description adds natural language examples and context for the query parameter (e.g., 'Natural language description of what you want to do'), providing meaning beyond the schema's descriptions. Also explains aliases.

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 'Find' and resource 'tools', and distinguishes from siblings by specifying it's for browsing/searching/discovering tools. It lists many example domains (SEC filings, FDA drugs, etc.), making the purpose unambiguous.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. This clearly indicates when to use and implies when not to (when you already know 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 mark the tool as read-only, idempotent, and safe. The description adds important behavioral details: it 'fans out across multiple sources', notes the USPTO PatentsView API sunset ('soft-fails until reactivated'), and specifies the exact return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). 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 well-organized, starting with example queries and then explaining scope, sources, and return fields. It could be slightly more concise, but every sentence adds value. The structure is logical and 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 the tool's complexity (multiple data sources, no output schema), the description thoroughly explains what is returned and under what conditions (e.g., patent API soft-fail). It covers failure modes and provides sufficient detail for an agent to understand the tool's behavior and output format without needing to discover it by trial.

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

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

Schema coverage is 100% and both parameters are described in the schema. The description adds context: the 'type' parameter is limited to 'company', and 'value' accepts ticker or zero-padded CIK but not names. This reinforces schema information and clarifies usage beyond 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 explicitly states it provides a 'full cross-source profile of a US public company' and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs. It distinguishes itself from siblings like resolve_entity and compare_entities by focusing on holistic profiling in one parallel call.

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 clear guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when NOT to use it (names not supported) and directs to resolve_entity for name resolution, providing a direct alternative.

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; description adds context about clearing sensitive data, consistent with annotations.

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

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

Two sentences, front-loaded with action, minimal 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?

Simple delete tool; no output schema needed; annotations cover idempotency and destructiveness, but could mention idempotent behavior.

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

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

Only one parameter with 100% schema coverage; description adds 'by key' but schema already states 'Memory key to delete'.

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 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from siblings remember and recall.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data, and explicitly pairs with remember and recall for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details such as fetching the page, extracting title/description/links, and outputting standard markdown. It does not mention rate limits or failure modes, which would add further transparency.

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

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

The description is concise with three sentences: purpose, process, and use cases. Each sentence adds value without redundancy, front-loading the core function.

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

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

For a tool with only two parameters and no output schema, the description is fully adequate. It explains the input, processing, output format, and practical applications, leaving no major 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 covers 100% of parameters with descriptions. The tool description does not add additional meaning beyond the schema, as it omits explicit mention of the 'max_links' parameter. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file creation 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 provides three specific use cases (client site indexing, personal project drafting, competitor auditing) giving good context. However, it does not explicitly state when not to use this tool or compare to alternatives, missing some exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, so the description's mention of returning fields and filtering (include_inactive) adds useful context beyond annotations, though no behavioral traits like rate limits are noted.

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

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

The description is three sentences with the main purpose first, no wasted words. Every sentence adds value.

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

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

Despite no output schema, the description lists return fields. The tool is simple (one optional param), so the description is mostly complete, though it could mention pagination if applicable.

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

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

Schema coverage is 100% with one parameter (include_inactive) fully described. The description does not add extra meaning beyond the schema, so baseline 3.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies return fields (id, type, params, etc.), distinguishing it from siblings like subscribe and unsubscribe.

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

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

The description provides explicit guidance on when to use the tool: to review monitoring before adding more subscriptions or to find an id to cancel. It does not cover when not to use it, but the guidance 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 discloses behavioral traits beyond the annotations: rate limited to 5 per identifier per day, free usage not counting against tool-call quota, and that the team reads digests daily. This adds valuable context that annotations do not capture, enhancing transparency.

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

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

The description is concise with four sentences, each serving a purpose: stating the tool's function, listing use cases, providing usage guidance, and noting limitations. It is front-loaded and contains no redundant or extraneous information.

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

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

Given the tool's simplicity (submitting feedback), the description is complete: it covers purpose, use cases, required parameters, optional context, constraints (rate limit, quota), and communication advice. No output schema is expected for this tool, so no gap exists.

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?

Despite 100% schema description coverage, the description adds meaningful context: it explains the enum values (bug, feature, data_gap, praise, other) with concrete examples, advises on message content, and clarifies that the context parameter is optional. This goes beyond the schema's own 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: sending feedback to the Pipeworx team about bugs, missing features, or praise. It uses specific verbs like 'tell' and enumerates distinct use cases, distinguishing it from sibling tools that are primarily informational or query-based.

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

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

The description provides explicit guidance on when to use the tool (e.g., 'when a tool returns wrong/stale data') and what not to do ('don't paste the end-user's prompt'). It also mentions the rate limit and quota, offering clear usage boundaries. There are no direct sibling alternatives for feedback, so the context is sufficient.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's disclosure of caching (5min-1h) and data source (CF analytics-engine, no PII) adds valuable transparency beyond the annotations. It does not contradict any 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 moderately long but well-structured with clear paragraphs and bullet points. Every sentence adds value, and the information is front-loaded. Slightly more conciseness could be achieved, but it is efficient given the content.

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

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

Given the simple parameter set and absence of output schema, the description sufficiently explains what is returned (top tools, packs, total call volume, with format (pack, tool, count)) and relevant context like caching. No additional details are needed for an AI agent to use this tool correctly.

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

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

Schema coverage is 100% and parameter description is already present in the schema. The description adds extra meaning by explaining the semantics of window length (shorter for hot, longer for steady-state), which aids selection. This exceeds the baseline 3 for high schema coverage.

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

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

The description clearly states it returns trending tools, packs, and call volume within a configurable time window. It distinguishes itself by focusing on real-time popularity data, unlike siblings such as 'discover_tools' which may have broader scope. The specific verb 'returns' and resource listing make the purpose unambiguous.

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

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

Three explicit use cases are provided for when to use this tool: discovering hot data sources, confirming canonical tools, and aligning with agent trends. Window parameter guidance (shorter for hot, longer for steady) adds context. While it lacks explicit 'when not to use' statements, the use cases effectively guide an AI agent.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive hints. Description goes beyond by detailing internal logic (monotonicity, partition checks, Jaccard similarity, placeholder filtering, fill check) and warns when not to trade (realizable edge ≤ 0). No contradictions.

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

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

Description is long and includes technical details that could be summarized. Front-loads core purpose but then dives into algorithm specifics. While well-structured with clear mode sections, it could be more concise for easier consumption.

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

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

Despite no output schema, description thoroughly explains response structure (opportunities array with fields, partition_check, fill check). Covers modes, internal checks, and trade recommendations. Missing error handling details but overall very complete for a complex tool.

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

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

Schema description coverage is 100%, providing a baseline of 3. Description adds significant extra meaning: for event, explains slug/URL format and child market checks; for topic, explains seed question and cross-event scanning. Enhances 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies two modes (event and topic) and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode over topic for specific markets and directs custom sizing to polymarket_fill_risk, providing clear alternative guidance.

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

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

The description discloses extensive behavioral traits beyond annotations: caching at KV level keyed on knobs, response segments (by_segment), diagnostics to explain empty segments, and edge calculation details. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false.

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

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

The description is very long and dense, covering many technical details. It is well-structured with sections like segments and knobs, but some repetition could be trimmed. It earns its place but is not 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 parameter complexity (9 params, no output schema), the description is thorough: it explains response structure by_segment, caching, diagnostics, and edge formulas. It is complete enough for an agent to understand inputs, outputs, and behavior.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds significant context beyond the schema, e.g., 'Tradeable-edge filter', 'skips opportunities too small to bet sensibly', and explains slippage_polymarket fees. While schema already covers basics, the description enriches 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 states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on single-leg edges and tradeable 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 it's for 'what should I bet on today' and provides guidance on when to use it vs alternatives (e.g., Fed bets are included but excluded from ranking). Gives detailed knob descriptions like min_liquidity and max_spread_pp to filter non-realizable edges.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive actions. The description goes far beyond by detailing the snapshot-based data source, the compute method (daily closes of edge_pp_net), the decay metric (decay_pp_per_day based on absolute value), and the handling of expired opportunities. It also explains data gaps ('snapshots are written when polymarket_edges runs on a cache-miss') and the TTL constraint. This is exemplary behavioral transparency.

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

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

The description is well-structured, starting with the core question and then systematically listing response fields. It is comprehensive but somewhat lengthy; while every sentence provides value, some could be tightened. The front-loading of the key insight is effective, and the use of uppercase key terms (RESPONSE, LIMITS) aids scanning.

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

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

Without an output schema, the description fully defines the response structure, including the three arrays (tracked, expired, snapshot_dates) with their subfields and meanings. It also covers edge cases: expired opportunities, missing snapshot dates, and the TTL constraint. This provides complete context for an agent to understand expected 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 description coverage is 100%, so the schema already documents both parameters. The description adds valuable context: 'days' is described as 'lookback' with default 14 and max 30 (schema says clamp 2-30), and 'window' as 'snapshot family' with default '1wk'. This clarifies the functional role of each parameter beyond the schema's basic type and constraints, providing trade 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 explicitly states the tool's purpose: providing 'edge persistence and decay telemetry' and answering 'how long has this edge existed and is it shrinking?' It details the specific outputs (tracked, expired, snapshot_dates) and contrasts with the sibling tool polymarket_edges by focusing on time-series analysis. This is a specific verb+resource combination that clearly distinguishes the tool.

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

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

The description conveys when to use the tool: when understanding edge persistence and decay is critical for trade decisions (e.g., a fresh wide edge vs. a 3-week-old wide edge). It implicitly advises caution by noting 'LIMITS' (60-day TTL, daily closes). However, it does not explicitly state when not to use it or give direct alternatives, though the sibling list provides context. This is clear usage guidance with minor room for improvement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms read-only nature and adds useful behavioral context about the implications of partial fills (unhedged directional 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?

Description is relatively long but well-structured with clear sections for single-market and basket modes. Uses front-loaded summary and imperative tone. Some verbosity in listing return fields, but justified by complexity of the tool. Eliminating redundant words could improve conciseness.

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 thoroughly explains all returned fields for both modes, covers edge cases (thin legs, forced directional risk), and provides sufficient context for an agent to understand the tool's behavior and output without needing an example.

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 have 100% schema coverage, but description adds substantial meaning: explains the dual interpretation of size_usd (spend vs target proceeds) between single-market and basket modes, the default side auto-detection for basket mode, and details the returned fields, all beyond the schema's property 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?

Clearly states it is a realizable-vs-theoretical edge check against live order-book depth. Distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges, specifying when to use this tool before acting on their signals.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains risks of partial basket fills converting arb into directional positions. Lacks explicit when-not-to-use statements but offers strong contextual cues.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: compatibility_warning conditions (bet shape mismatches, semantic mismatch), temporal_alignment checks, and skipped_cross counters. It honestly warns that most pre-mapped topics return warnings and are not tradeable.

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 core concept, mode explanations, response details, and safety fields. However, it is somewhat verbose with technical jargon and could be slightly more concise without losing essential information.

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

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

Given the tool's complexity (two modes, safety fields, cross-venue matching), the description is comprehensive. It explains not only how to use the tool but also how to interpret the response and warnings. Without an output schema, the description effectively covers return values.

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 all three parameters. The description adds value by explaining the two modes (topic vs explicit tickers), listing available topic values, and clarifying that explicit tickers override the mapped side. This goes beyond the schema's 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 clearly states it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers), making the purpose specific and distinct from sibling tools.

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

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

The description provides clear context on when to use (to compare prices across venues) and includes explicit caveats about pre-mapped topics often being non-tradeable due to compatibility warnings. However, it does not directly reference alternative sibling tools for users wanting intra-venue arbitrage or other analyses.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds scoping info (anonymous IP, key hash, account ID) and pairing with remember/forget, which is valuable context beyond annotations.

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

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

Three sentences, each providing essential information: core function, usage context, and scoping/pairing. 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?

Covers both usage scenarios (with/without key), scoping, and related tools. Complete for a simple retrieval tool with no output schema.

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

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

Adds meaning beyond schema: explains that omitting key lists all keys, and the key is for retrieving a specific value. Schema coverage is 100% and description enhances it.

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

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

States clearly that it retrieves a value saved via remember or lists all keys when omitted. Distinguishes from siblings like remember and forget.

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

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

Explains when to use (look up context stored earlier) and how to use (omit key for listing). Could be more explicit about when not to use, but pairing with remember/forget provides clear guidance.

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

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

The description discloses that mark_read changes read status, which contradicts the readOnlyHint annotation (true) that implies no side effects. This is a clear contradiction, so score is 1.

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, front-loaded, and contains no fluff. Every sentence adds useful information about functionality, filtering, and usage.

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

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

The description covers most aspects: return fields, filtering options, mark_read, and alternative access. However, it omits explanation of limit and unread_only parameters, leaving minor 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 description adds value beyond the schema by giving examples (e.g., type 'sec_8k') and explaining mark_read behavior. However, not all parameters (limit, unread_only) are mentioned, though schema coverage is 100%.

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: 'Pull fired events from your subscription feed.' It uses a specific verb ('pull') and resource ('fired events'), and distinguishes from siblings like list_subscriptions by focusing on recent alerts rather than subscription metadata.

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: polling suitability, alternative access via URL, and the effect of mark_read. However, it does not explicitly compare to sibling tools or specify when not to use this tool, 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: it fans out to multiple sources with fallback behavior (GDELT to GNews on rate limit), notes USPTO API sunset, and describes the return format with citations. This adds significant behavioral insight beyond annotations.

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

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

The description is concise yet highly informative, front-loading purpose with clear examples. Every sentence adds value, and the structure flows logically from purpose to details to alternative tool guidance.

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

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

Given 3 required parameters with full schema coverage, no output schema, the description thoroughly explains the return format (changes[] grouped, total_changes, citation URIs), sources, fallback behavior, and alternative tool. It is complete for the tool's complexity.

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

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

Schema coverage is 100%. The description adds meaning: explains `type` is only 'company', `since` accepts ISO date or relative shorthand with examples, and `value` can be ticker or CIK. This provides extra clarity beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose with multiple examples ('What's new with X', 'latest on Y') and specifies it provides a change feed for a company over a time window in one parallel call, distinguishing it from sibling tools like entity_profile.

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

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

The description gives clear guidance on when to use this tool (for change feed) and explicitly recommends using entity_profile instead for static profile. It also provides context for typical monitoring with recommended `since` values, though it doesn't explicitly state when not to use it.

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

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

Annotations provide idempotentHint=true, and description adds scope ('scoped by your identifier') and retention policy ('persistent memory' vs '24 hours for anonymous sessions'), which goes beyond annotations 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?

Four concise sentences, front-loaded with the main purpose, each sentence adds meaningful context with no superfluous 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 key-value storage tool with no output schema, the description covers scoping, persistence, and usage pattern, 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?

Input schema has 100% coverage with clear descriptions for key and value; description does not add additional parameter semantics beyond what schema provides. 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 starts with a clear action ('Save data the agent will need to reuse later') and specifies the resource (key-value pair). It distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

The description explicitly states when to use ('when you discover something worth carrying forward') and provides guidance on alternatives: 'Pair with recall to retrieve later, forget to delete.'

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=true, idempotentHint=true, and openWorldHint=true, but the description adds valuable context: each call internally cascades through several lookup endpoints, replacing 2-3 manual lookups. This explains potential variability (openWorldHint) and performance implications, going beyond what annotations convey.

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

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

The description is concise and well-structured. It starts with example queries to set context, then states the core purpose, followed by supported types with detailed returns. Every sentence adds value, and the paragraph length is appropriate for the complexity of the tool.

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

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

Given the tool has no output schema, the description does a good job explaining return values for both entity types (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation URI for drug). It also mentions the cascading behavior and that it replaces multiple lookups. However, it could be more precise about the exact JSON structure of the response (e.g., field names) to aid an agent in parsing.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds meaningful context: for 'type' it elaborates on the two options and their return fields; for 'value' it explains that company input accepts ticker, CIK, or name with auto-disambiguation. This extra detail helps an agent understand the flexibility beyond the schema's basic enum and string 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 resolves names to official identifiers, listing specific entity types (company, drug) and what is returned. It uses examples like 'What's the ticker for…' to illustrate purpose. However, it does not explicitly differentiate from sibling tools like entity_profile or compare_entities, which might do similar lookups but with different scope.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use. It does not mention when not to use it or suggest alternatives among the sibling tools, such as entity_profile for deeper details or compare_entities for comparisons.

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

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

The description adds significant behavioral context beyond the annotations: it explains the mechanism (probes each entity with ai_visibility_check, ranks by score), specifies the return fields (score, confidence, signal density), and notes the role of the first entity as the 'subject'. This fully discloses the tool's behavior. No contradictions with annotations (readOnlyHint, etc.).

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

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

Three concise sentences: first states the core action, second explains the mechanism, third gives a practical use case. No redundant or tangential information. Every sentence earns its place.

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

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

Despite lacking an output schema, the description specifies the return format (ranked list with score, confidence, signal density). All four parameters are documented in the schema, and the description provides enough context for an agent to decide when and how to invoke 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%, so baseline is 3. The description adds value by explaining that entities are probed and ranked, that the first entity is the 'subject', and that models have defaults (workers-ai) or require an API key (Anthropic). This extra context helps the agent use parameters correctly.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison). It provides a concrete use-case example ('does Claude know about us as well as our competitors?').

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

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

The description states when to use ('competitive AI-marketing audits') and gives an example prompt. However, it does not explicitly mention when not to use it or contrast it with alternatives such as ai_visibility_check for single-entity checks, leaving implicit differentiation.

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

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

Annotations provide safety guarantees (readOnly, idempotent, non-destructive). Description adds substantial behavioral detail: fans out across two sources, partial failures degrade gracefully, bundlephobia first measurement latency (5-30s), sources_failed reporting. 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?

Description is a single, information-dense paragraph that covers all necessary aspects without unnecessary fluff. Slightly dense due to technical details but still 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?

Given tool complexity (composite of two APIs), full schema coverage, and detailed annotations, the description fully explains what it does, how it behaves, and what it returns (summary block, advisory details, links, alternative versions). Output schema absent but return fields are described.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds value by noting scoped packages accepted for 'package' and clarifies version defaults to latest. Baseline 3, extra nuance pushes to 4.

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

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

The description states a specific composite check for npm package evaluation, covering license, advisories, bundle size, etc. It clearly distinguishes from siblings by being a one-call composite for this use case and explicitly scopes to NPM.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and notes alternatives for other ecosystems (PyPI, Maven, etc. using deps.dev directly). Provides clear context and exclusions.

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

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

Annotations already indicate readOnlyHint and no destructive behavior. The description adds rich behavioral context: truncation at 200K chars with flag, embedding model (BGE-base-en), cosine similarity, 500-char windows, and offset inclusion 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 mostly concise with two sentences. The second sentence is dense but well-structured, containing multiple pieces of information. Some minor redundancy could be trimmed (e.g., 'every passage carries an offset' is repeated). Still efficient overall.

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

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

Given no output schema, the description explains return values (top-N passages, offsets, similarity scores) and operational details (embedding model, window size, char cap with truncation). It is fully self-contained for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds little new meaning beyond what the schema provides for each parameter. Examples of queries are helpful but not essential. The truncation cap is already in the schema's text description.

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

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

The description uses a specific verb+resource ('Semantic search INSIDE a fetched record') and provides concrete examples of usage (SEC 10-K body, article, tool result). It clearly distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also mentions the alternative and how it pairs with ask_pipeworx_grounded, providing clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return structure (names, descriptions, IDs) but no additional behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action and result. No wasted words, efficient for an agent to parse.

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 search scope, return content, and linkage to sibling tool. Lacks mention of pagination or response format details, but adequate given no output schema.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds no new meaning beyond the schema, so baseline 3 applies.

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

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

Clearly specifies the action (search), resource (Seattle open-data catalogue), and returns (dataset names, descriptions, resource IDs). Distinguishes from sibling tools like seattle_query by stating the output is for use with that tool.

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

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

Clearly indicates when to use (keyword search for datasets) and that results feed into seattle_query. Does not explicitly state when not to use or 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 declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds that it is a raw query with optional API key, which aligns with annotations. No contradiction, but minimal extra behavioral detail beyond what annotations provide.

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

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

Two sentences: first delivers core purpose, second links to related tools. No wasted words, front-loaded, and easy to parse.

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 does not explain return format or error handling. It adequately conveys it's a raw SoQL query but lacks output details. Adequate for a simple API tool, but not fully complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description only summarizes the parameter set as 'SoQL where/select/group/order/limit/offset', which adds little meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool runs raw SoQL queries against Seattle open-data resources by Socrata ID, specifying the data source and query capabilities. It distinguishes from sibling tools seattle_datasets and seattle_recent, which are for finding resource IDs.

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 this tool (to run raw SoQL queries) and directs to siblings for finding resource IDs. It lacks explicit when-not-to-use guidance but provides clear context for appropriate usage.

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

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

Annotations already indicate read-only, idempotent, open world. Description adds that results are newest-first and lists the available datasets, enhancing context without contradicting annotations.

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

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

Three sentences, front-loaded with purpose, followed by usage guidance and parameter notes. 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?

Sufficiently describes what it returns (latest rows, newest-first) and parameter use. Output structure is not detailed but acceptable for a simple retrieval 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%. The description adds value by explaining the dataset parameter options, the SoQL where clause, and the default limit, beyond the schema descriptions.

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

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

The description clearly states that the tool returns recent records from specific Seattle datasets by friendly name. It lists the datasets and distinguishes from seattle_query.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives examples. Also directs to use seattle_query for anything else, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). Description adds critical context: returns subscription ID, requires OAuth, webhook signing secret provided once, and auto-disable after 10 consecutive failing runs. No contradiction.

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

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

Description is relatively long but well-structured, front-loaded with purpose and requirements, then types and delivery details. Every sentence adds value, though it could be slightly more concise by grouping common constraints.

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, many type enum values), the description covers purpose, requirements, parameter semantics, return value, delivery options with constraints, and error handling (webhook auto-disable). Output schema is absent but description mentions return of subscription ID, which is sufficient.

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

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

Schema coverage is 100%, but description adds substantial value by providing detailed examples and constraints for each parameter, e.g., type-specific params (sec_8k with items codes, polymarket_edge with topic, fred_series with series_id), delivery channel details (feed always on, email/sms/webhook with specific behaviors).

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. The verb 'Create' and resource 'subscription' are specific, and the tool's purpose is distinct from siblings like list_subscriptions or 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 requirement for a Pipeworx OAuth account (anonymous/BYO cannot persist), lists supported subscription types with examples, and describes delivery channel options with constraints (e.g., SMS must be verified, 10/day cap). No alternative tool for creation exists, so guidelines are comprehensive.

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, so the safety profile is clear. The description adds behavioral context: it returns example questions with tool + argument shape, and is an onboarding entry point, 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 moderately long but well-structured: it starts with the purpose, lists return contents, and ends with usage guidance. It is informative without being verbose, though a slight trim could improve conciseness.

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 return format (category-bucketed example questions with tool + argument shape). It covers the single parameter and the overall purpose completely for an onboarding 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% (the only param 'topic' is described). The description adds value by listing specific focus areas (finance, pharma, etc.) and clarifying that omitting the parameter returns a cross-category spread.

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

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

The description clearly states it is the onboarding entry point for a new agent, detailing that it returns category-bucketed example questions from the live catalog. It distinguishes itself from sibling tools by focusing on onboarding and not executing queries.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on when to omit or pass the 'topic' argument.

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 behavioral traits beyond annotations: ownership enforcement (authorization) and row deactivation (not deletion), consistent with destructiveHint=false. It also connects to 'recent_alerts' for historical events. No contradiction with annotations.

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

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

Two sentences, front-loaded with the action, no unnecessary words. Every sentence contributes meaning.

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

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

For a single-parameter tool with no output schema, the description covers the effect (deactivation), ownership, and relationship to a sibling tool. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds value by specifying that the 'id' is the subscription uuid 'returned by subscribe,' clarifying its origin. The ownership constraint is also relevant to parameter usage.

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

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

The description states 'Cancel a subscription by id,' which clearly identifies the action (cancel) and resource (subscription). It also distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by explaining that the row is deactivated, not deleted, preserving historical events for 'recent_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?

Ownership is explicitly enforced ('you can only cancel your own subscriptions'), providing a strict usage constraint. It also notes that historical events remain accessible via 'recent_alerts,' implying when not to use this tool. However, it does not explicitly state when to use this tool versus alternatives like 'list_subscriptions' or 'subscribe.'

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns a verdict (with five categories), uses SEC EDGAR + XBRL, and provides percent delta and citations. It does not contradict annotations. While it adds good context, it could mention the lack of mutability or side effects, but annotations already cover safety.

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 clearly structured: triggers, usage, scope, return format, efficiency benefit. It is slightly verbose but every sentence adds value. Could be trimmed slightly without losing 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 the tool has one parameter and no output schema, the description is remarkably complete. It explains the input, the data source (SEC EDGAR + XBRL), the return format (verdict types, structured form, actual value, citation, delta), and the efficiency gain (replaces 4-6 calls). Nothing essential is missing.

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

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

Schema coverage is 100% with a clear description for the single 'claim' parameter. The description adds further meaning by providing examples ('Apple's FY2024 revenue was $400 billion') and clarifying that it is natural-language. This enhances the schema's definition nicely.

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

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

The description clearly states the tool's purpose: 'Natural-language claim verification against authoritative sources.' It uses specific verbs like 'validate,' 'verify,' 'confirm or refute,' and identifies the resource as factual claims. It distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls, providing strong differentiation.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also specifies scope with 'v1 supports company-financial claims,' but does not include explicit when-not-to-use or alternative tools, making it slightly less than perfect.

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