Postscript

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

Annotations already declare readOnlyHint, etc., so the bar is lowered. The description adds important behavioral context: Workers AI is free, Anthropic requires a BYO API key with direct payment. It does not discuss rate limits or latency, but the annotations 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 efficient and front-loaded: the first sentence states the core action and output, followed by model details, return format, and use cases. Every sentence contributes meaning 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 no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response plus combined view) and the input parameters. It covers cost implications for Anthropic and provides sufficient context for usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior and the role of _apiKey, exceeding the schema documentation for 'models' and '_apiKey' parameters.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and the optional Anthropic probe, distinguishing it from sibling tools like 'scan_competitor_ai_presence' by focusing on visibility scoring.

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

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

The description lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and implies when to use the tool. However, it does not explicitly compare with alternative sibling tools or state when not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds operational transparency by explaining that the tool routes questions to multiple sources and returns structured answers with citation URIs, complementing the 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?

The description is lengthy and contains some redundancy (e.g., listing multiple example questions). While it is front-loaded with key guidance, it could be 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 (many sources, multiple sibling tools), the description is thorough, covering when to use, what it does, and how it differs from alternatives. It provides sufficient context for the agent to understand the tool's role without an output schema.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter and its aliases adequately. The description adds no additional parameter-level information beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to a vast array of 4,552 tools across 1,160 verified sources, returning structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research with specific guidance.

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 advises to prefer this tool over web search for authoritative data, and provides examples of when to use it. It also delineates when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). Clear when/when-not guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses that it costs an extra LLM call, routes to the correct tool, and returns explicit refusal reasons ('not_in_source', 'no_tool_match', etc.) on failure. It also explains the extraction process uses only the tool result. No contradiction with annotations; adds significant behavioral context.

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

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

The description is thorough but somewhat verbose, with a dense single paragraph. It front-loads the main purpose and ends with a cost trade-off note. While every sentence is informative, it could be slightly more concise without losing meaning. Score 4 for efficiency.

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

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

The description covers the tool's routing behavior, extraction method, return format, refusal reasons, and cost implication. Given the tool's complexity (routing among 4,552 tools, extra LLM call) and absence of an output schema, the description is complete enough for an agent to understand when and how to use it correctly. Score 4 as it thoroughly addresses the main concerns.

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

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

Schema description coverage is 100%, and the description essentially repeats that the parameter accepts natural language and mentions aliases, which are already documented in the schema. The description adds no additional semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results. It differentiates from sibling 'ask_pipeworx' by specifying it is for situations where answers must be quoted or cited, and the agent must not invent facts. This provides a specific verb+resource+scope and distinguishes from its sibling.

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 an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'Prefer ask_pipeworx for casual lookups.' This gives both when-to-use and when-not-to-use guidance, including alternatives. Clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive hint. The description adds extensive behavioral details: low-confidence resolution handling, closed market status, wide-spread tradeability, cancellation rule parsing, and fallback mechanisms for news sources. This goes far beyond annotations, ensuring the agent understands all critical edge cases.

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

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

The description is detailed and uses clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) for structure. It front-loads the core purpose and usage. However, it is quite long and includes extensive examples and commentary. Every sentence is informative, but could be slightly trimmed for brevity without losing value.

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

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

Given the tool's complexity (multiple classifiers, data sources, error states), the description covers all necessary aspects: input/output, resolution confidence, parent event extraction, news fallbacks, safety mechanisms, and cancellation risks. No output schema exists, but the response shape is thoroughly explained, making it complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by clarifying default values (depth='thorough', include_raw=false) and explaining the trade-offs for 'include_raw' (response size vs. detail). It also expands on 'depth' by defining 'quick' as 2-3 sources. This enriches the schema, though some info is already present.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies accepted input types (slug, URL, question text) and what it returns (evidence packet + comparison). The purpose is specific and actionable, distinguishing it from sibling tools like polymarket_edges.

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

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

Explicit usage cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear context but lacks explicit when-not-to-use or alternatives, though the detailed fan-out examples imply coverage. Slight 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?

Beyond annotations (readOnly, non-destructive), the description adds details on data sources (SEC EDGAR for companies, FAERS for drugs), sorting by primary metric, and return of citation URIs. No contradictions.

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

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

The description is concise yet comprehensive, front-loading common query patterns and structuring information logically. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately covers return format (paired data + citation URIs), data sources, sorting behavior, and entity count. It is complete for an effective agent usage.

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

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

Schema coverage is 100%, and the description enriches parameters by explaining the data each type retrieves, providing examples (tickers for company, drug names), and constraints (2-5 items). This adds clear meaning beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 entities (companies or drugs) in one call. It uses specific verbs and resources, distinguishing it from single-entity lookups via 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?

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities. Provides example queries and specifies when to use (comparing 2-5 companies or drugs), effectively guiding the 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?

Discloses it is not open-web search, returns structured findings with gaps[] array, and never invents answers. Adds context on parallel execution and expected response time (15-60s). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description enhances with specificity.

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 comprehensive but slightly lengthy. Front-loaded with critical account and sign-in info. Every sentence adds value, though some could be more concise while retaining clarity.

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

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

For a complex research tool with no output schema, description thoroughly explains return format (findings packet with evidence, confidence, source, fetched_at, citation, and gaps). Covers expected behavior, limitations, and performance expectations.

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, so baseline is 3. Description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8) and that thorough requires paid plan. Also clarifies that question can be broad/multi-part.

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 performs grounded multi-source research across structured data, decomposing questions into facets and routing to tools in parallel. Distinguishes from sibling ask_pipeworx by specifying it is not for single lookups or breaking news.

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

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

Explicitly when to use: broad/multi-part questions over structured data. When not: use ask_pipeworx for single lookups or current news. Provides alternatives and notes account/tier requirements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating it returns top-N tools with full schemas and curated examples, ready to call, which aligns with the annotations and provides additional context.

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

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

The description is concise yet comprehensive, front-loading the purpose and usage, then detailing return value. No unnecessary sentences.

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

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

Given no output schema, the description adequately explains return contents (names, descriptions, schemas, examples). Could mention pagination or limit handling but overall complete for the tool's purpose.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds that 'query' accepts multiple aliases but does not add meaning beyond the schema for individual parameters. Baseline of 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, using specific verbs like 'browse, search, look up, discover'. It distinguishes from sibling tools by its meta-discovery role.

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

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

The description says 'Call this FIRST when you have many tools available' and lists scenarios (browse, search, etc.). It lacks explicit when-not-to-use guidance, but implies it's for exploration rather than direct answers.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavior: fans across multiple sources, patents soft-fail after May 2025, returns specific data fields with fallbacks. 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 and contains all necessary information, but it is a single paragraph with many details. Slightly less concise due to the amount of information packed in, but front-loaded with examples and clear.

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

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

Despite no output schema, the description explains what is returned (cik, filings with URIs, fundamentals sorted, patents with note, news fallback, LEI). Limitations are transparent. Complete for the tool's holistic profile purpose.

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

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

Schema covers both parameters with descriptions, but the description adds meaning: explains type enum (only 'company' currently), value must be ticker or zero-padded CIK, names not supported. This goes beyond the schema.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing sources and example queries like 'Tell me about X' or 'company profile for Microsoft'. It distinguishes from sibling tools such as resolve_entity by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', and notes that names are not supported, advising to use resolve_entity first. This provides direct guidance on when to use and alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description confirms deletion but adds no new behavioral context 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, front-loaded with purpose, every sentence adds value with no extraneous text.

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

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

Given the simplicity (1 required param, no output schema, clear annotations), the description covers purpose, usage context, and tool relationships fully.

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 describes the key parameter. The description merely repeats 'by key' without additional semantic 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 states a clear verb ('Delete') and resource ('previously stored memory by key'), and distinguishes from sibling tools (remember, recall) by specifying the action.

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

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

Explicitly lists when to use: context is stale, task done, or clearing sensitive data. Also pairs with related tools (remember, recall), providing clear 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral detail: fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

The description is two sentences plus a bullet list of use cases, all front-loaded. Every sentence adds value with no waste.

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

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

Given the low complexity (2 parameters, no nested objects, no output schema), the description explains the output format ('single text blob') and process. Annotations cover safety. The description is complete for the tool's domain.

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 documents both parameters. The description implies the effect of 'max_links' (maximum link entries) but does not add syntax or format details 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 states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. The sibling list includes no directly competing tool, so it is well-differentiated.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for your own project, or auditing a competitor. While it doesn't explicitly state when NOT to use, the context is clear and no sibling tool overlaps.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds the list of returned fields (id, type, params, etc.), which is useful but not a behavioral trait beyond what annotations imply. 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 two sentences, front-loaded with purpose, followed by usage guidance. No unnecessary words.

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

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

For a simple read-only list tool with one optional parameter, the description covers the returned fields (compensating for missing output schema) and provides usage context. It is sufficiently complete.

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

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

Schema coverage is 100% with a single parameter fully described in the schema. The description does not add additional semantic meaning beyond the schema.

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

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

The description states 'List the caller's active subscriptions.' It clearly indicates the verb (list) and the resource (subscriptions). Among sibling tools like subscribe and unsubscribe, it uniquely identifies itself as the listing 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 explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use contexts and implies alternatives (subscribe, unsubscribe).

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

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

The description adds behavioral context beyond the annotations: rate limit (5 per identifier per day), free usage (no quota impact), and team reading frequency. Annotations are all false, so no contradiction. This information is critical for the agent to understand side effects and constraints.

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 highly concise: three sentences that front-load the main purpose, followed by usage guidance and constraints. Every sentence adds unique information with no redundancy. It efficiently covers all needed aspects without 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?

Given no output schema, the description adequately covers the tool's behavior (submission, team review, limits). However, it does not mention return values (e.g., no confirmation message). For a feedback tool this is acceptable, but completeness could be improved by noting that nothing is returned explicitly.

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 advising to describe issues in terms of Pipeworx tools/packs and stating typical message length (1-2 sentences, 2000 chars max). This goes beyond the schema's type definitions and helps the agent craft appropriate feedback.

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: submitting feedback about bugs, missing features, data gaps, or praise. It uses a specific verb ('Tell') and distinguishes the feedback types explicitly. No sibling tool serves the same purpose, so differentiation is not needed.

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

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

The description provides explicit when-to-use guidance per feedback type (e.g., 'when a tool returns wrong/stale data (bug)') and what not to do ('don't paste the end-user's prompt'). It also mentions the team's daily review and roadmap impact, giving the agent clear context for appropriate invocation.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds useful details: data source (CF analytics-engine), no PII, aggregation method, and caching behavior (5min-1h). No contradictions with annotations.

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

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

The description is a single paragraph of about five sentences with no wasted words. Front-loaded with purpose, followed by bullet-point use cases and technical details. Every sentence provides value.

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

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

Despite no output schema, the description explains return types (top tools, top packs, total call volume) and data source. Caching behavior is stated. For a simple read-only tool, this is sufficiently complete. Minor gap: exact output format not specified, but acceptable.

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

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

Input schema has 100% coverage with detailed description of the 'window' enum. The tool description mentions the window in the opening sentence but adds no new parameter-level information beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window. It distinguishes from siblings like 'discover_tools' by focusing on trending data based on other AI agents' calls.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Provides guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). Missing only explicit when-not-to-use or 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial context: internal logic (monotonicity checks, partition-sum checks, semantic anchor, partition filter), response structure, and fill-check behavior (realizable_edge_pp ≤ 0 means do not trade). 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 relatively long and includes many details (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) but is well-structured with clear sections. It is front-loaded with the main purpose. Could be tightened by summarizing less critical details, but no waste.

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

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

For a complex tool with multiple modes, internal algorithms, and response details, the description covers the main scenarios, explains the response structure, and refers to another tool for custom sizing. It lacks an output schema but the text describes the response fields. Missing details on error handling or edge cases for the no-arg mode (e.g., what if no trending markets?), but still fairly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description elaborates on each parameter significantly: it explains what slugs/URLs are accepted for 'event', what seed questions work for 'topic', and how each mode operates. This adds meaning beyond the bare schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no-arg trending scan, per-event, per-topic) with specific examples, making the purpose unambiguous 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 explicitly explains when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It also explains why cross-event mode catches patterns single-event misses. However, it does not directly compare this tool to siblings like polymarket_edges or polymarket_fill_risk, leaving the agent to infer usage boundaries.

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

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

Annotations are all positive (readOnly, openWorld, idempotent, not destructive). The description goes beyond annotations by explaining caching (1h KV level), filtering logic, and detailed model families, providing full behavioral context.

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

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

The description is long but well-structured with sections for model families, tradeable-edge knobs, and response details. It earns its length by being informative, though slightly verbose with technical details that might clutter for a general AI agent.

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

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

Given complexity (9 parameters, multiple segments, diagnostics), the description is very complete. It explains why segments might be empty, caching, and response structure (by_segment, diagnostics), compensating for the lack of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining knobs like min_partition_leg_kelly's behavior for partitions, which goes beyond schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs (scan, return) and resource (Polymarket markets, edges), and distinguishes from siblings like polymarket_arbitrage.

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

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

The description explicitly says it's built for 'what should I bet on today' and explains tradeable-edge knobs. While it doesn't explicitly state when not to use it, the context from sibling names suggests alternatives exist, and the description provides good context for when to use.

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

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

Annotations indicate readOnly and idempotent, so the description adds value by disclosing that snapshots are written on cache-miss and gaps mean no scan that day. It also mentions TTL and that decay is from daily closes, not intraday.

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

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

The description is relatively long but efficiently structured: first explains the problem, then details the response fields, and ends with limitations. Every sentence adds value, though some length could be trimmed.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields. Limitations are also covered, making it complete for agent understanding.

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

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

The schema already fully describes both parameters with coverage at 100%. The description repeats key info (defaults, max) but adds no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: it provides edge persistence and decay telemetry, answering how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges which likely provides current edge data.

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

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

The description provides context for when to use the tool, contrasting a fresh wide edge with a 3-week-old one. It also explains limitations and response structure, but does not explicitly state when not to use it or list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds rich behavioral detail: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), lists return fields (slippage, shares_filled, etc.), and explains per-leg details and forced directional risk for baskets. This exceeds basic transparency expectations, though the annotations already cover safety traits.

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

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

The description is lengthy (10+ sentences) but well-structured: core purpose first, then mode details, then return fields, then usage guidance. It is front-loaded with the most important information. Every sentence adds value given the tool's complexity, though some truncation could be possible without losing meaning.

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

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

Without an output schema, the description carries full burden to explain return values. It does so thoroughly for both modes: lists all returned fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers edge cases like partial fills and thin legs. The description is complete for this 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% (all 4 parameters described in schema). The description adds further semantic context: explains how 'side' defaults differ between modes, clarifies that size_usd has default 1000 and clamp range, and notes that market or event is required (though schema shows no required). Overall, the description enhances understanding beyond the schema.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live order book depth. It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, telling the agent to use this tool before acting on those signals. This provides excellent purpose clarity and sibling 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 gives explicit guidance: use this before polymarket_arbitrage or polymarket_edges trades above ~$500. It explains why partial fills convert arb into directional risk and that theoretical overround on thin books is not capturable. This provides clear when-to-use and when-not-to-use context.

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

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

Disclosures beyond annotations: compatibility_warning conditions, temporal_alignment check, skipped_cross_type/subtype counters. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Packed with essential detail but slightly verbose. Front-loaded with key info; every sentence earns its place. Could be slightly more structured but still 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?

Despite no output schema, description fully specifies response fields (leg-by-leg prices, top_spreads_pp, safety fields). Complete for a complex tool with multiple modes and edge cases.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds context on interaction between parameters and examples. Though schema already covers meaning, description enhances overall understanding.

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

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

Clearly states it computes cross-venue spreads between Polymarket and Kalshi for the same resolving question. Distinguishes from sibling tools like polymarket_arbitrage which targets intra-venue arbitrage.

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

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

Explicitly describes two modes (topic shortcuts or explicit tickers) and provides safety fields to warn when spreads are not meaningful. Also notes that pre-mapped topics often return compatibility warnings, guiding agents to verify before trading.

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, fully covering the tool's safety profile. The description adds no additional behavioral traits (e.g., authentication details, rate limits) beyond the response content, which is expected given the annotation coverage. It does not contradict annotations.

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

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

The description is two sentences with no wasted words. It first states the core action, then lists the return fields in a parenthetical list. Every part contributes to understanding, making it highly efficient.

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

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

For a simple 'get by ID' tool with no output schema, the description adequately explains the return value (keyword text, status, configuration with welcome message and list assignment). It covers all necessary context for an agent to understand usage and expected output, given the tool's low complexity.

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

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

Both parameters (_apiKey and keyword_id) are fully described in the input schema with 100% coverage. The description does not add any additional meaning or usage details beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states 'Get a single SMS keyword by its ID' with a specific verb ('Get') and resource ('SMS keyword'), and distinguishes it from sibling list tools by emphasizing singular retrieval. It also specifies the returned fields (text, status, configuration), leaving no ambiguity about its purpose.

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

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

The description implicitly conveys when to use this tool: when you have a keyword ID and need details of a single keyword. It does not explicitly contrast with siblings like postscript_list_keywords, but the context of 'single' versus 'list' is clear enough. Lacks explicit 'when not to use' guidance, preventing a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the specific return fields (phone, email, etc.) but doesn't disclose any other behavioral traits like rate limits or auth needs beyond what the schema implies.

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

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

Single sentence, front-loaded with the action and resource. Every word is necessary. No fluff.

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

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

For a simple 2-parameter read tool with annotations, the description is adequate. It lists returned fields. Missing: mention of the _apiKey requirement (though schema says required) or any rate limits, but not critical for such a tool.

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

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

Schema description coverage is 100%, so both parameters (_apiKey, subscriber_id) are already described in the schema. The description only adds 'by Postscript subscriber ID' which is redundant. No additional semantics needed.

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 gets a single SMS subscriber by ID and lists the returned fields. It distinguishes from sibling tools like postscript_list_subscribers (list) and postscript_get_keyword (keyword focus).

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

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

The description implies usage when you have a specific subscriber ID and need details. It doesn't explicitly exclude other tools, but the context is clear given the 'get by ID' nature. No explicit when-not or 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying that only active keywords are listed and that the response includes keyword IDs, text, and subscription settings. 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 consists of two concise sentences. The first sentence states the action and scope, the second adds context and return details. No unnecessary words.

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

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

For a simple list tool with one parameter and no output schema, the description adequately covers what the tool does, what it returns, and the concept of keywords. It is complete for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100% for the single parameter _apiKey, which already includes a description. The tool description does not add any additional parameter information beyond what is in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'list', the resource 'active SMS keywords', and the scope 'for the shop'. It distinguishes from sibling tools like postscript_get_keyword and postscript_list_subscribers by specifying it lists keywords rather than a single keyword or subscribers.

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 does not explicitly state when to use this tool versus alternatives such as postscript_get_keyword. It provides context about keywords but lacks guidance on when not to use it or prerequisites.

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, so safety is clear. The description adds the pagination pattern and return structure (page_info, subscribers), which annotations do not cover. No contradiction exists.

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

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

Two sentences: first states purpose and capabilities, second explains pagination. No fluff, front-loaded, every sentence adds value.

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

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

For a read-only list tool with no output schema, the description fully covers behavior: supported filters, sorting, and pagination instruction. Combined with solid annotations, no critical gaps remain.

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

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

Schema coverage is 100%, so all 11 parameters are documented in the schema. The description mentions filtering categories (email, phone, created/updated timestamps) and sorting, adding high-level context but no new details per parameter. 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 specifies the action ('List SMS subscribers'), the resource ('Postscript (Shopify) shop'), and the scope (all subscribers with filtering). It distinguishes itself from siblings like postscript_get_subscriber (single) and postscript_list_keywords (keywords), leaving no ambiguity.

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 supported filters and sorting, and details pagination usage. It does not explicitly contrast with alternatives or state when not to use, but the pagination instructions are sufficient for correct invocation in most cases.

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

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

Adds scoping and dual-behavior (list vs retrieve) beyond annotations that already indicate safety; no contradictions.

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

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

Three sentences with front-loaded purpose, 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?

Complete for a simple tool with one optional parameter and no output schema; covers all needed aspects.

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

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

Schema covers 100% parameter documentation; description echoes the parameter behavior without adding syntax details, meeting baseline.

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

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

Description explicitly states retrieval of saved values or listing all keys, distinguishing from remember and forget siblings with clear verb+resource.

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 concrete use cases (ticker, address, notes) and pairing with remember/forget, but does not 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 already declare readOnly, openWorld, idempotent hints. The description adds behavioral context: mark_read affects future calls, feed is persisted, and the same data is available via a GET endpoint. No contradictions.

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

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

Single, well-structured paragraph with no wasted words. Front-loaded with the main purpose. Each sentence adds information.

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

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

No output schema, but description explains return fields and payload content. Covers parameters, usage, and alternative access method. For a simple read tool, this is complete enough.

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

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

Schema descriptions cover all 5 parameters (100% coverage). The description adds value by explaining the effect of mark_read and the meaning of the since filter, and enumerates returned fields, which is not in the schema.

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

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

The description clearly states the verb ('pull'), the resource ('fired events from your subscription feed'), and the key fields returned (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions or subscribe by focusing on alert events.

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 guidance on filtering (type, since) and mark_read behavior. It also mentions polling suitability and an alternative direct endpoint for scripts, though it doesn't explicitly state when to avoid using 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?

Annotations already mark read-only, idempotent, non-destructive. Description adds details: fans out to multiple sources with fallback (GDELT→GNews), soft-fail for USPTO, return format with grouped changes and citations. 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?

Concise yet packed with information. Front-loaded with query examples, then explains fan-out, fallback, return format, and when to use alternative. 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?

Comprehensive for a complex tool with multiple sources and fallbacks. Despite no output schema, description explains return structure. Notes API sunset and soft-failure.

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

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

Schema description coverage is 100%, but description adds meaning: 'type' only 'company', 'since' accepts relative shorthand like '7d', '30d', '3m', '1y', 'value' can be ticker or zero-padded CIK. Example usage provided.

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

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

The description clearly states the tool provides a change feed for a company with examples like "What's new with X", "latest on Y". It distinguishes itself from the sibling tool 'entity_profile' by contrasting static profile vs. change feed.

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 with query examples and directly states when to use the alternative 'entity_profile'. Includes exclusions and alternatives.

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

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

Annotations show idempotentHint=true and destructiveHint=false, consistent with description. Description adds valuable context about persistence (24 hours for anonymous, persistent for authenticated) and scoping by identifier, which goes beyond annotations.

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

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

Four sentences, each adding value. Front-loaded with purpose, then usage guidance, then behavioral details, then pairing with siblings. No unnecessary words.

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

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

For a simple write operation without output schema, description covers purpose, usage, persistence, and lifecycle pairing. Missing explicit mention of overwriting keys, but overall complete.

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

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

Schema coverage is 100% with parameter descriptions including examples. Description adds that it is a key-value pair but does not provide additional meaning beyond the schema. Acceptable baseline.

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

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

The description clearly states the tool saves data for reuse, specifies key-value pairs, and distinguishes from sibling tools recall and forget. It uses specific verb 'save' and resource 'data for later reuse'.

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

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

Explicitly says 'use when you discover something worth carrying forward' and mentions when not to use by pairing with recall and forget. Provides context on scoping and persistence for authentication states.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that each call cascades through several endpoints, revealing internal complexity. This goes beyond what annotations provide, giving the agent awareness of potential latency or multiple steps.

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 examples and purpose. Each sentence adds value: examples, use case, supported types, return details, and internal behavior. A bit lengthy but efficiently packaged; no redundancy.

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

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

No output schema, so description compensates by detailing return values for each type, including citation URIs. Covers both supported types comprehensively. Missing error handling details, but for a lookup tool this is acceptable.

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

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

Schema coverage is 100%, but description adds significant meaning: for 'value' it lists specific examples (ticker, CIK, name for company; brand/generic for drug) and for 'type' it clarifies the enum values. This enriches the schema's basic descriptions.

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

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

The description starts with clear examples like 'What's the ticker for...' and states it resolves names to canonical IDs. It explicitly distinguishes from siblings by noting its role as the first step when IDs are needed. The supported types are listed with specifics.

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 advises 'Use FIRST whenever you have a name but need an ID.' Also mentions it replaces multiple manual lookups, providing strong context for when to use. Does not explicitly specify when not to use, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, indicating safe, read-only, idempotent operation. The description adds valuable behavioral context: it probes each entity using 'ai_visibility_check', rankes results, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences with no wasted words: first sentence states the main function, second explains the process, third gives an example use case. It is efficiently structured and front-loaded with the core purpose.

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

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

Given 4 parameters (1 required), no output schema, and moderate complexity, the description fully covers inputs (entities 2-8, first is subject), process (probes, ranks), output structure (ranked list with score, confidence, signal density), and dependency on 'ai_visibility_check'. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining how parameters like '_apiKey' and 'models' affect probing (e.g., '_apiKey' needed only if 'anthropic' in models), and that 'context' disambiguates common names. This goes beyond the schema descriptions, earning 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 states exactly what the tool does: 'Compare AI visibility across multiple entities side-by-side' and specifies the process: probes each entity with 'ai_visibility_check', ranks by score, and surfaces most/least recognized. It distinguishes from sibling 'ai_visibility_check' (single-entity) by focusing on multiple entities and ranking.

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

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

The description gives a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implicitly guides when to use (comparing multiple entities) but does not explicitly exclude scenarios or mention alternatives like 'compare_entities'. The reference to 'ai_visibility_check' as the underlying mechanism provides context, but could be more explicit about when not to use.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds details about partial failures, bundlephobia's first measurement taking 5-30s, and graceful degradation with sources_failed listing. 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 detailed and front-loaded with purpose, but lists returned fields in a slightly lengthy manner. Still efficient and well-structured for the complexity.

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

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

With no output schema, the description thoroughly explains return values (summary block, advisory details, links, alternative versions) and behavior (graceful degradation, timeouts). Complete for an information-gathering tool.

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

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

Schema coverage is 100%, so parameters are already well-described. The description adds useful context (e.g., scoped packages accepted, default version behavior) but does not significantly expand 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 is a composite check for evaluating npm packages, using deps.dev and bundlephobia. It specifies the resource (npm package) and scope (NPM ecosystem), distinguishing it from siblings like scan_competitor_ai_presence.

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

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

The description explicitly says 'Use whenever an agent asks “is X safe / popular / small” or “what does adding lodash cost me”' and notes that other ecosystems should use deps.dev:version directly, 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?

The description adds significant behavioral context beyond the annotations: it explains embedding details ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), character cap ('200K chars'), and truncation behavior ('longer inputs are truncated and flagged'). There is no contradiction with annotations.

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

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

The description is a single paragraph with front-loaded purpose, followed by when-to-use, technical details, and alternatives. Every sentence is essential and no redundant information.

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

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

Despite lacking an output schema, the description explains return values ('top-N passages with character offsets and similarity scores') and constraints (200K cap). It covers all necessary context for correct invocation and interpretation.

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

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

Schema coverage is 100%, but the description adds value with examples for 'query' (e.g., 'supply-chain risk') and clarifies defaults for 'limit' (default 5) and informal note about max chars. This enriches the agent's understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It uses a specific verb ('search') and resource ('record'), and distinguishes from siblings by mentioning the alternative workflow with 'ask_pipeworx_grounded'.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also mentions pairing with 'ask_pipeworx_grounded' for grounding, providing clear usage context. However, it lacks explicit when-not scenarios.

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

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

Beyond annotations, the description discloses authentication requirements, persistence of subscriptions, rate limits (SMS cap), and webhook auto-disable after failures. It also notes that webhook signing secret is returned only once. This adds significant behavioral context.

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

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

The description is well-structured and front-loaded: it starts with the core purpose, then prerequisites, then types with examples, then delivery channels. Every sentence adds value without redundancy.

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

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

With 3 parameters fully covered, the description provides enough context for an agent to select and invoke the tool correctly. It mentions the return value (subscription id). A slight improvement could be to describe error scenarios or output format, but not necessary.

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 extensive meaning: it explains each type with examples, details delivery channels with constraints and special behavior (e.g., webhook HMAC signing, phone verification link). This goes far beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists specific types, distinguishing it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear context on when to use (proactive monitoring) and prerequisite: requires a Pipeworx OAuth account. It also mentions restrictions like phone verification and 10/day SMS cap, but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about returning live catalog examples and being an entry point. No contradictions, but could mention more about response size or limitations.

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 informative and front-loaded with example questions. Every sentence adds value, though it could be slightly more compact without losing clarity. Overall well-structured.

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

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

Given the single optional parameter, no output schema, and 100% schema coverage, the description sufficiently explains the return value (category-bucketed examples with tool shapes). Sibling tools context supports its unique role as 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% for the single optional parameter. The description adds meaningful usage guidance: examples of topic values ('finance', 'pharma', 'betting') and behavior when omitted ('call with no arguments for the full 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 the tool is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools by specifying 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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

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

Explicitly states when to use: 'when you do not yet know what Pipeworx can do for you', and how to focus with optional topic parameter. It also names alternative meta-tools (ask_pipeworx, entity_profile, compare_entities) to use after, providing clear guidance.

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

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

The description adds value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This clarifies the non-destructive nature despite readOnlyHint=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 two sentences, front-loading the action and providing essential behavioral context without any 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?

For a simple tool with no output schema, the description covers the main purpose, ownership constraint, and side effect. However, it does not mention error cases or response format, leaving a minor gap.

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 does not add new semantics for the 'id' parameter beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and resource 'subscription', and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by explicitly mentioning cancellation.

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 by stating ownership enforcement ('you can only cancel your own subscriptions'), but it does not explicitly mention when to avoid using the tool or suggest 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, and destructiveHint. The description adds behavioral context: it returns a verdict with confidence levels, extracted structured form, actual value with citation, and percent delta. It also explains the underlying data sources (SEC EDGAR + XBRL). 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 detailed but not excessively long. It starts with examples and clearly states the tool's capability and limitations. Every sentence adds value, though it could be slightly more concise. Overall well-structured.

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

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

With only one parameter and no output schema, the description fully explains the return structure (verdict, extracted form, actual value with citation, percent delta) and the scope (v1 company-financial claims). It is complete for the agent to understand the tool's purpose and output.

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

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

The only parameter 'claim' has 100% schema description coverage. The schema already provides a detailed description and example. The tool description adds a brief confirmation of the parameter's natural-language format but does not significantly extend the schema's explanation. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides examples of claim types (company-financial) and explains it consolidates multiple sequential calls, distinguishing it 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the scope (v1 supports company-financial claims), implicitly excluding other domains, but does not provide explicit alternatives or 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.