Digitalnz

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds beyond that by disclosing the free default model, billing implications for Anthropic (BYO key), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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, each earning its place: purpose+output, model options+key, return+use cases. Front-loaded with core action and outcome. No redundancy or vague language.

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 4 parameters, no output schema, and annotations covering safety, the description adequately explains return shape, default model, and optional cost-bearing Anthropic probing. Lacks error handling or rate limit details, but for a small probe 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% with descriptions for all 4 parameters. The description adds value by explaining the default model for 'models', the purpose of '_apiKey' as a pass-through to Anthropic, and 'context' as a disambiguation aid. This elevates beyond the schema alone.

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

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

The description clearly states the verb 'probe' and resource 'LLMs' for a business/brand/product/topic, with a specific output score (0-100). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on multi-model probing and 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?

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Mentions default model and optional Anthropic with BYO key, giving context for when to include _apiKey. Does not explicitly state when not to use or alternatives, but the context is sufficient for typical 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: routes to verified sources, returns structured answers with pipeworx:// citation URIs, works on every tier in one fast call. 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 comprehensive but slightly verbose. However, every sentence adds value, and the most critical instruction ('PREFER OVER WEB SEARCH') is front-loaded. Minor redundancy could be trimmed (e.g., the final 'For... ask_pipeworx already routes...' bit is implied).

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

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

Despite no output schema, the description fully explains return type (structured answer with citations), scope (4,774 tools), and boundaries (when to step up to siblings). Given the tool's complexity and rich annotations, this is complete and actionable.

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

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

Schema coverage is 100% with all six parameters documented (including aliases). The description adds context about the types of questions but does not significantly enhance parameter understanding beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to 4,774 tools across 1,242 sources and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and provides numerous concrete examples of supported queries (SEC filings, FDA data, etc.).

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

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

Explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with clear alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad questions). Lists specific question types that work well.

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

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

Description adds significant behavioral context beyond annotations: it explains the extra LLM call cost, mentions the extraction process, details return object fields (answer, evidence, confidence, source, fetched_at, refusal_reason), and lists possible refusal_reason values. No contradiction with annotations.

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

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

Description is detailed but slightly lengthy (7 sentences). It is front-loaded with the core purpose and usage, then provides extra details. Could be trimmed slightly (e.g., removal of 'Same routing...' redundancy), but overall well-structured and each sentence earns its place.

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

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

Given no output schema, the description explicitly defines return fields and refusal reasons. It covers the tool's behavior, cost trade-off, and parameter usage comprehensively. No gaps are present for a read-only, hallucination-resistant tool.

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

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

Schema coverage is 100% with each parameter described in the schema. The description does not add new meaning beyond 'Your question in natural language' and noting aliases, which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from the sibling 'ask_pipeworx' by emphasizing extraction from tool results only. The verb 'extracts' and resource 'answer' are specific and unambiguous.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'Prefer ask_pipeworx for casual lookups', providing clear when and when-not to use this tool, with specific contexts like financial verdicts, legal claims, medical lookups.

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 extensively explains behavioral traits beyond annotations: low-confidence resolution short-circuits, closed/dead market handling, wide-spread market warnings, resolution-rule risk parsing, news fallback mechanisms, and parent_event extraction. Annotations already indicate read-only, idempotent, non-destructive, and open-world nature; the description adds rich operational 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 verbose but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). The first sentence provides the core purpose, and subsequent sections are logically organized. Some redundancy exists (e.g., repeating classifiers), but overall it is efficient for an 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 no output schema, the description thoroughly covers all return values and edge cases: result.market with bid/ask/spread/liquidity/price changes, result.analysis with model probabilities and warnings, result.evidence keyed by source, resolver contract with confidence scores and alternatives, parent_event extraction, news fallback, safety short-circuits, and resolution-rule risk. It is exceptionally complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by providing examples ('market_input' slug, URL, question text), explaining the 'depth' enum (quick vs thorough), and detailing 'include_raw' for controlling response size. This enriches 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the exact resource (Polymarket bet via market slug, URL, or question text) and action (research). This distinctively separates it from sibling tools like deep_research (general) or search (web search).

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

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

The description provides explicit use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It details classifiers and fan-out patterns, guiding when to use. However, it does not explicitly state when not to use it (e.g., for non-Polymarket data), but the specificity makes that clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds useful behavioral context: pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted results, and replaces 8-15 sequential lookups. No contradictions.

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

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

The description is well-structured and front-loaded with the key phrase 'side-by-side comparison'. It includes example queries to aid understanding. While slightly verbose, every sentence adds value and there is no redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format: 'paired data + pipeworx:// citation URIs per entity' and that results are sorted by primary metric. It also covers edge cases like off-calendar fiscal years, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema. For the 'type' parameter, it explains what each enum value returns. For 'values', it provides examples and clarifies the required format (tickers/CIKs for companies, names for drugs).

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 performs side-by-side comparisons of 2-5 companies or drugs in one call, with specific metrics for each type. It distinguishes itself from sibling tools like entity_profile by emphasizing that it should be preferred over sequential single-pack lookups.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups' and explains when to use each type (company or drug). It does not explicitly state when not to use it, but the constraints are in the schema.

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

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

The description discloses behavioral traits beyond annotations: expects 15-60 seconds, returns findings with gaps[], never invents information, decomposes questions into facets, and requires an account. Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds meaningful context without contradiction.

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

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

The description is well-structured and front-loaded with the most critical information (account requirement and alternative). Every sentence adds value, covering purpose, behavior, usage, limitations, and expectations. No redundancy or fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers account prerequisites, alternative tools, use cases, return format, time expectations, and limitations. It fully prepares the agent for correct invocation.

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

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

Schema coverage is 100%, but the description adds critical semantics: for 'depth', it explains quick=3, standard=5, thorough=8 facets and notes paid plan requirement. For 'question', it clarifies that broad/multi-part is fine and decomposition is the point, which is not in the schema description.

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

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

The description clearly states the tool's purpose: grounded multi-source research across Pipeworx's structured data sources. It provides specific examples ('compare X and Y's regulatory + financial exposure') and explicitly distinguishes from siblings like ask_pipeworx, which is 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?

The description includes explicit when-to-use and when-not-to-use guidelines. It advises using ask_pipeworx for single lookups and for breaking/colloquial news, and notes that users not signed in should use ask_pipeworx. Example use cases are provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds details about return format: 'top-N most relevant tools with names, descriptions, and full input schemas' and that each result is directly callable. 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 concise yet packed with value: purpose, usage context, examples, return behavior, and priority. Every sentence earns its place, and the key point is front-loaded.

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

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

Despite no output schema, the description fully explains the return structure. It covers the workflow (call first to discover), parameter usage (query), and limit. Minor omission: no mention of error handling or if limit defaults to 20, but overall complete for a discovery tool.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description reinforces the purpose of the query parameter with examples but does not add significant detail beyond the schema. Baseline 3 applies.

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

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

The description clearly states 'Find tools by describing the data or task' and provides numerous examples. It distinguishes from sibling tools like 'search' by explicitly saying 'Call this FIRST when you have many tools available and want to see the option set'.

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 it (browse, search, discover tools) and when to call it first. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds details: fans out across multiple sources, soft-fails for patents, returns up to 5 filings with URIs, and explains sorting of fundamentals. 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 somewhat lengthy but well-organized and front-loaded with example patterns. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains all return values: CIK, company_name, recent_filings (with URIs), fundamentals (with specific fields), patents (with sunset note), news, and LEI. Covers complexity and limitations.

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

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

Schema coverage is 100%. The description adds meaning: for 'type', it explains that only 'company' is supported and other types are coming soon; for 'value', it clarifies ticker or zero-padded CIK and that names are not supported. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the verb 'profile' and the resource 'entity', and distinguishes from siblings like 'compare_entities' and 'resolve_entity'.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also warns that names are not supported and recommends using 'resolve_entity' first if only a name is available.

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

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

Description adds no behavioral context beyond annotations; destructiveHint and idempotentHint already cover safety. No extra disclosure on side effects or requirements.

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

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

Two sentences, no wasted words. Front-loaded with action, then usage context.

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?

Sufficient for a simple 1-param destructive tool. No output schema needed; description covers purpose and usage. Could mention return behavior but not critical.

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 the lone parameter fully (100%). Description repeats 'by key' but adds no extra details like format or constraints.

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

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

Clear verb+resource: 'Delete a previously stored memory by key.' Distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicit use cases provided: stale context, task done, clear sensitive data. Lacks when-not-to-use but adequate for simple 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, idempotentHint, and no destruction. The description adds behavioral details: fetches the page, extracts title/description/links, emits markdown. It does not contradict annotations (no write or destructive actions described). A 5 would require additional context like error handling or rate limits.

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

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

The description is two clear sentences plus a list of use cases. It is front-loaded with the core action. Slightly verbose with 'production-ready' and the list, but no wasted words. Could be more compact without losing clarity.

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

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

Given the tool has only 2 parameters and no output schema, the description adequately explains the process (fetch, extract, emit), output format (standard llms.txt markdown), and where to use the result (site-root/llms.txt). It does not detail the exact structure of the output text, but 'standard llms.txt format' is sufficient for most agents.

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 (url, max_links) are already documented in the schema. The description adds no extra meaning beyond the schema, e.g., no format hints or edge cases for the url 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 uses specific verbs ('Generate', 'fetches', 'extracts', 'emits') and identifies the resource ('llms.txt file for any URL'). It clearly distinguishes from siblings by specifying the output format and use cases, unlike related tools like 'ai_visibility_check' which check presence rather than generate files.

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 (client sites, own projects, auditing competitors) which guide when to use. However, it lacks explicit instructions on when not to use or mention of alternative sibling tools, which would elevate it to 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 read-only, idempotent, non-destructive behavior. Description adds value by listing exact return fields (id, type, params, etc.) and mentioning optional parameter behavior, enhancing transparency beyond annotations.

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

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

Two efficient sentences; first sentence states purpose and return fields, second provides usage guidance. No wasted words.

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

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

Given simple tool with one optional parameter, no output schema, and clear annotations, the description fully covers return format and usage context needed for correct invocation.

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

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

Schema covers 100% of parameters with descriptions. Description does not add any extra meaning for the include_inactive parameter beyond the schema, so baseline 3 applies.

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

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

Clear verb-resource combination: 'List the caller's active subscriptions.' Also specifies return fields and usage context, differentiating it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides context for decision-making, though lacks explicit '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?

Discloses rate limit of 5 per identifier per day, that it's free and doesn't count against quota, and that team reads digests daily. Adds value beyond annotations.

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

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

Concise, front-loaded with purpose, well-structured with clear sections. 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?

For a feedback tool with 3 parameters, description covers all essential info: when to use, what to include, constraints, and audience. No output schema needed.

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

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

Schema coverage is 100%, and description adds context for each parameter: type enum explained, message length and specificity, context object optional. Provides practical guidance.

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

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

Description clearly states the tool is for sending feedback about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools by being a feedback mechanism.

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

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

Explicitly tells when to use each feedback type (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limit and that it's free.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: self-aggregating, derived from CF analytics, no PII, caching delays. No contradictions.

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

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

The description is well-structured with bullet points, front-loaded with the core purpose. Every sentence adds distinct value (purpose, use cases, technical notes). No wasted words.

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

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

Given only 1 optional parameter and comprehensive annotations, the description covers usage, caching, aggregation, and privacy. It is complete for an agent to decide when and how to invoke this tool.

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

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

The schema already describes the 'window' parameter with enum and description (100% coverage). The description adds meaningful elaboration: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds decision guidance beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. It uses specific verbs like 'returns' and identifies the resource (call volume data). It distinguishes from siblings like 'discover_tools' by explicitly mentioning trending analytics.

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 three specific use cases (discovering hot data sources, confirming canonical tool, seeing alignment with needs). It also mentions caching behavior (5min-1h) which guides expectations. No explicit when-not-to-use, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral details: the algorithms used, semantic anchor (Jaccard similarity), partition filter, and fill check against live CLOB depth. It clearly explains when a signal should not be acted upon.

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 well-structured with a clear overview, followed by mode-specific sections and response details. Every sentence adds value; however, the length could be slightly reduced by being more terse 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?

Given the tool's complexity (2 parameters, no output schema, algorithmic details), the description is exceptionally complete. It covers logic, edge cases (placeholder filter, similarity), response format, and references to other tools. No gaps remain for an agent to deploy 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 covers both parameters with descriptions, but the description adds significant context, including example slugs and that full URLs are accepted for event. It also explains the difference between event and topic modes beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities using monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) with specific guidance on when to use each, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit instructions are given for each mode: no arguments for trending_scan, event slug for single-event, and topic for cross-event scanning. It also advises against trading when the fill check shows realizable_edge_pp ≤ 0 and directs to use polymarket_fill_risk for custom sizing.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral detail: 1h KV caching, Fed bets handled separately, partition arbs return kelly_fraction_half=0, diagnostics expose why segments are empty. 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?

Front-loaded with purpose, then structured by segments and response fields. Every sentence adds value, but the description is somewhat long with deep technical details. Could be slightly tighter, but appropriate for 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?

No output schema, but description fully explains response structure: by_segment, fed_candidates, _diagnostics. Also details per-opportunity fields (edge_pp_net, kelly_fraction, etc.) and diagnostic checks. Compensates well for missing schema given 9 parameters and complex 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?

Schema coverage is 100% with descriptions. Description adds extra semantics: explains min_kelly does not filter partition arbs, details category_filter enum values, and describes relationship between min_liquidity/max_spread_pp as tradeable-edge filters. Adds value beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today' agents. It distinguishes from siblings like polymarket_arbitrage (arbitrage focus) by emphasizing model-driven disagreement.

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

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

Provides clear context like the three segments (model_driven, structural_arbitrage, concentrated_longshot) and tradeable-edge knobs. Also explains Fed bets exclusion. However, lacks explicit when-not-to-use guidance or direct comparison to sibling tools like polymarket_edge_tracker.

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 include readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: daily snapshots, 60-day TTL, decay computed from daily closes, and data gaps explained. 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 information-dense and front-loaded with the core question. However, it is somewhat verbose, particularly in detailing the response format. Every sentence adds value, but it could be slightly more streamlined.

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

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

Given no output schema, the description thoroughly explains the return format (tracked[], expired[], snapshot_dates[]) and their fields. It also covers limits (60-day TTL, daily closes). This is complete for a tool with 2 optional parameters.

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

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

Input schema covers 100% of parameters with descriptions. The description adds useful defaults and clarification (days default 14, max 30; window default '1wk'), and explains the response structure, which goes beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series, answering 'how long has this edge existed and is it shrinking?'

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

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

The description provides clear context for when to use this tool (to assess edge age and decay versus current edge data). It implies when not to use it (for current edges, use polymarket_edges), but does not explicitly name alternatives, slightly lowering the score from 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, but the description adds substantial behavioral context: it details the ladder walking process, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and critical warnings about unhedged directional risk from partial fills. This goes beyond the annotations to fully inform agent behavior.

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

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

The description is thorough but somewhat verbose, containing detailed explanations that could be slightly condensed without losing clarity. However, the structure with sections (SINGLE-MARKET, BASKET) and clear formatting aids readability. It earns its length given complexity, but some redundancy could be trimmed.

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

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

Given the four parameters and no output schema, the description is complete: it covers both modes, all input semantics, output fields (top_of_book, vwap_fill_price, etc.), edge cases (thin legs, partial fills), and risk warnings. The explanation of 'forced_directional_risk' and 'max_clean_notional_usd' ensures agents understand all outcomes.

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

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

With 100% schema coverage, the description adds significant meaning beyond the schema. It explains the dual meaning of 'side' in single-market vs basket mode, interprets 'size_usd' as spend vs target proceeds vs settlement notional, and provides examples. This enriches agent understanding of parameter usage.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two distinct modes (single-market and basket) with specific verbs like 'check', 'walks the ladder', and 'returns'. This effectively differentiates it from sibling tools like 'polymarket_arbitrage' and '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?

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against improper use with 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position,' providing clear usage context.

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

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

The description extensively explains behavioral traits beyond annotations: two modes, compatibility_warning conditions, temporal_alignment, skipped_cross_type counters, and the note that real spreads are rarer than the shortcut list suggests. Annotations already indicate readOnlyHint, idempotentHint, etc., and the description complements them fully 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 packed with useful information and well-structured—purpose, modes, response, safety fields. While a bit long, every sentence earns its place. It could be slightly more concise, but the complexity justifies the length.

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

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

Given the tool's complexity (two modes, cross-venue comparison, safety fields) and no output schema, the description thoroughly covers expected behavior, response structure, edge cases, and warnings. The agent can fully understand how to invoke the tool and interpret results.

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

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

Despite 100% schema coverage, the description adds significant value: it lists all 10 topic shortcuts, explains that explicit parameters override topic-mapped sides, and provides example values. This goes beyond what the schema's property descriptions offer.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This specific verb+resource pair clearly states what the tool computes. It distinguishes itself from siblings (like polymarket_arbitrage) by being cross-venue rather than single-venue.

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

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

The description clearly outlines two usage modes (topic shortcuts vs explicit tickers) with examples. It warns that most pre-mapped topics are not tradeable, helping the agent set expectations. However, it does not explicitly contrast with 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 mark it as readOnly, idempotent, and non-destructive. The description adds scope (by identifier) and operational pairing context, without contradicting annotations. It does not detail return format but adds meaningful 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?

Three sentences, front-loaded with the primary action, no extraneous words. Every sentence adds value.

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

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

Given low complexity (1 optional param, no output schema, clear annotations), the description fully covers purpose, usage, and relationships with sibling tools. No gaps identified.

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

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

Schema coverage is 100%, and the description reiterates the key's role (omit to list). It adds concrete examples (ticker, address, notes) that clarify typical usage, going beyond the schema's minimal description.

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

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

The description clearly states it retrieves values saved via 'remember' or lists all keys when omitted. It explicitly distinguishes from sibling tools 'remember' and 'forget', covering the specific verb and 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?

The description explains when to use the tool (to look up stored context) and how to use it (omit key for listing). It mentions pairing with 'remember' and 'forget' but lacks explicit 'when not to use' or alternatives, though the context is clear.

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

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

Description claims mark_read parameter modifies state ('flag returned events read so the next call only shows newer ones'), contradicting annotations that declare readOnlyHint=true. This is a serious inconsistency. Also lacks disclosure on authentication or rate limits.

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

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

Three sentences, front-loaded with purpose, then parameters, then alternative access. No filler. Each 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?

Covers output structure (source, citation_uri, payload) and key parameters. No output schema, so description fills gap. However, the annotation contradiction undermines completeness, and missing details on pagination or error handling. Adequate but flawed.

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

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

Schema coverage is 100%, baseline 3. Description adds significant meaning: explains type filter with example 'sec_8k', clarifies since as ISO timestamp, details mark_read behavior (flags read for subsequent calls), and unread_only logic. Exceeds 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?

Clear verb 'Pull' and resource 'fired events from your subscription feed' with specifics ('most recent alerts', 'source, citation_uri, raw event payload'). Distinct from siblings like list_subscriptions (which lists subscriptions themselves).

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?

States 'Polls work fine' and provides alternative via direct URL for scripts/dashboards. Implicitly suggests when to use (polling) vs when not (direct URL integration). No explicit exclusion of siblings but sufficient context.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral details: it fans out to three sources, has a fallback from GDELT to GNews, and notes that USPTO is soft-failing due to API sunset. 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 front-loaded with example queries and is moderately concise. While slightly long, every sentence provides useful information 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 three required parameters, no output schema, but the description explains the output structure (changes grouped by source, total_changes count, citation URIs) and references alternatives. It is comprehensive for a complex multi-source tool.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: explains that type only supports 'company', details since parameter formats (ISO dates, relative shorthand) with examples, and clarifies that value can be ticker or CIK.

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

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

The description clearly states the tool's purpose: providing a change feed for a company from multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It includes example queries like 'What's new with X' and explicitly distinguishes from the sibling tool entity_profile.

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

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

The description provides clear usage context, including when to use this tool vs entity_profile. It explains the fan-out to multiple sources and fallback behavior, but does not explicitly state when not to use it (e.g., for non-companies).

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, openWorldHint, and destructiveHint=false. The description adds minimal extra behavioral context beyond specifying it fetches full details for one item, which is consistent with the annotations.

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

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

The description is a single concise sentence that is front-loaded with the verb and resource. 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?

Given the tool's simplicity (2 params, no output schema, no nested objects), the description adequately explains what the tool does and how to use it. However, it does not describe the return format beyond 'full details', which could be slightly vague but sufficient for selection.

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

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

Input schema coverage is 100% with descriptions for both parameters. The description does not add additional meaning beyond the schema, such as format examples for 'id' or usage notes for '_apiKey'.

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 'Fetch', the resource 'full details for one DigitalNZ item', and the identifier method 'by id'. It distinguishes from sibling search tools by specifying 'by id' rather than query-based search.

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 a DigitalNZ record id is available, but does not explicitly mention when not to use it or suggest alternatives like 'search' for query-based retrieval.

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

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

Description adds context beyond annotations: key-value scoping by identifier, persistence differences based on auth status. Annotations already indicate write operation and non-destructiveness, 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?

Front-loaded with purpose, then usage guidance, then technical details. Concise but covers all important aspects 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?

For a tool with 2 required params, no output schema, and annotations present, the description is complete: purpose, when to use, pairing with siblings, persistence behavior, and parameter examples.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds examples of key patterns (subject_property, target_ticker) and value content, surpassing baseline.

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

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

Description clearly states 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, etc.). Distinguishes from siblings recall and forget by mentioning pairing.

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

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

Explicitly says 'when you discover something worth carrying forward' and mentions authentication-based persistence. While no explicit when-not, the purpose is well-defined and paired with sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral insight beyond annotations by noting that 'Each call cascades through several lookup endpoints internally' and details the output including citation URIs. This provides useful context without contradiction.

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

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

The description is well-structured, starting with example queries and usage instruction, then detailing supported types. It is slightly long but every sentence adds value. The front-loaded usage guidance ('Use FIRST...') is effective.

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

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

Given the tool's complexity (two entity types with internal cascading lookups), the description covers the main points: what each type returns (ticker, CIK, RxCUI, etc.) and includes citation URIs. No output schema exists, but the description adequately explains return values. Minor gap: no mention of error handling or edge cases, but overall complete for an AI agent.

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% description coverage for both parameters. The description adds value by elaborating on each parameter: for 'type' it lists supported values, for 'value' it gives examples (e.g., 'AAPL', '0000320193', 'ozempic'). This adds context beyond the schema's minimal descriptions.

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

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

Description clearly states the tool resolves a name to an official identifier with specific verb+resource. It provides example queries ('What's the ticker for...') and distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' This effectively differentiates it from other tools that may also deal with entities but require identifiers.

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

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

The description explicitly tells when to use the tool ('Use FIRST whenever you have a name but need an ID') and explains what it returns for each type. It indicates that using resolve_entity replaces 2-3 manual lookups, providing clear context. While it doesn't explicitly list when not to use it or name alternatives, the guidance is sufficient for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral context: it calls ai_visibility_check internally, returns a ranked list with score/confidence/signal density. It mentions optional API key for Anthropic models. This adds value beyond annotations, though details about rate limits or potential side effects are omitted.

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

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

Three sentences, front-loaded with the core action, no wasted words. Each sentence adds value: purpose, functionality example, and return structure.

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 explains return structure (ranked list with score, confidence, signal density) despite no output schema. It covers the tool's functionality for competitive audits. A slight gap: it doesn't mention what happens if entities exceed 8 or are invalid, but overall sufficient for expected use.

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

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

Schema description coverage is 100%, but the description adds critical meaning: entities[0] is the 'subject', rest are competitors; context disambiguates common names; models are supported with clear conditions. This significantly aids correct parameter usage beyond the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or name alternatives. With many sibling tools, explicit exclusion would improve, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral traits: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This significantly aids agent understanding.

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

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

The description is a single dense paragraph that packs a lot of information. While front-loaded with the key purpose, it could be more structured (e.g., bullet points for the composite checks). It is not overly long, but slightly verbose.

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

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

Given the complexity (composite check with multiple sources, partial failures, timeout), the description covers all aspects: returns a summary block with specific fields, per-advisory detail, links, and alternatives. Without an output schema, it provides sufficient completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context: for 'package', it mentions scoped packages like '@types/node' are accepted; for 'version', it gives an example and notes default behavior. This provides added value beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb 'scan', resource 'npm package dependency', and the composite nature, distinguishing it from sibling tools like 'deps.dev:version' for other ecosystems.

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''. It also provides scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context about the return format (ids, titles, creators, dates, links) and mentions passing an id to the 'record' tool, which is helpful for understanding behavior beyond annotations.

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

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

The description is a single, front-loaded sentence with no extraneous words. Every piece of information earns its place.

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

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

Given the tool's simplicity, annotations cover safety and idempotency, schema covers parameters, and description covers return fields. No output schema exists, but the description lists key fields, which is sufficient.

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

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

The input schema has 100% description coverage, so parameters are well-documented. The description adds extra meaning by noting that results include ids that can be used with the 'record' tool, enriching the semantics of the 'query' parameter's return context.

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

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

The description clearly states the action ('Search'), the resource ('DigitalNZ collection'), and the return fields. However, it does not differentiate this tool from sibling tools like 'search_within' or 'deep_research', so it loses a point for lack of sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only states what it does, not under what circumstances or prerequisites. This is a gap.

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 significant context beyond annotations: uses BGE-base-en embeddings with cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. Annotations already mark it as read-only, idempotent, and non-destructive; description complements with technical details and mentions return format (character offsets, similarity scores).

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 paragraph of ~5 sentences, front-loaded with primary action. Every sentence adds distinct value: action, use case, pairing, technical details. No wasted words.

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

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

Given no output schema, description fully explains what is returned (top-N passages with character offsets and similarity scores). Covers embedding model, windowing, character cap, and truncation behavior. Sufficient for an agent to understand how to use and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances understanding by providing usage examples for text ('e.g. a SEC 10-K body, an article') and query ('e.g. 'supply-chain risk''). Adds context on how to use parameters 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?

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings like search (likely across records) and ask_pipeworx_grounded (grounding). Provides concrete examples of text sources and queries.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' This gives clear when-to-use and alternative.

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

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

Discloses mutation behavior, return value, and constraints (10/day SMS cap, webhook auto-disable). Annotations complement but description 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?

Well-structured with front-loaded purpose, prerequisites, types, and channels. Each part is relevant, though slightly verbose; still efficient 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?

Covers purpose, usage, parameters, and return value. No output schema, but description provides adequate completeness for this tool's complexity.

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

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

Adds substantial meaning beyond the schema with specific examples for each type (e.g., sec_8k items, polymarket_edge topics) and detailed delivery channel behavior. Schema coverage is 100% but description enriches it.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, specifying the verb and resource. It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 prerequisites (requires Pipeworx OAuth account), supported types with examples, and delivery options. Lacks explicit when-not-to-use or alternatives among siblings, but gives clear context for appropriate usage.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. Description adds value by explaining that output is drawn from a live catalog of thousands of tools and includes the exact tool+argument shape for each example, which is 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?

Description is a single, well-structured paragraph that starts with common user queries, then explains output and usage. Every sentence adds value, and the length is appropriate for the information conveyed.

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

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

Given the tool's simplicity (single optional parameter, no output schema), the description fully covers its purpose, usage, and output. It explains the return structure (category-bucketed questions with tool calls) and when to call, leaving no gaps.

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

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

Schema already documents the optional 'topic' parameter with allowed values. Description adds meaningful guidance: 'Omit for a cross-category spread' and provides context on how it focuses the output, improving usability beyond the schema alone.

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

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

Description clearly states the tool is the onboarding entry point that returns category-bucketed example questions with exact tool calls. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying it should be used first to learn what Pipeworx can do.

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 this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear guidance on when to call with no arguments vs a topic, and implies it is for initial exploration.

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 ownership enforcement, deactivation vs deletion, and retention of historical events. Annotations already indicate non-destructive and idempotent, and description adds critical behavioral nuance 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?

Two sentences pack all essential information with no redundancy or fluff. Front-loaded with the main action and followed by crucial details.

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

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

Given the tool's simplicity (one param, no output schema), the description fully covers what the tool does, its constraints, and its effects. No missing information.

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

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

Schema coverage is 100% with a single 'id' parameter described as UUID from subscribe. The description adds value by linking the ID source and ownership requirement, going beyond schema.

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

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

Clearly states it cancels a subscription by ID, with ownership enforcement and deactivation behavior. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly says ownership is enforced (only your own subscriptions) and that it deactivates not deletes, with historical events still available via recent_alerts. Provides clear context and excludes misuse.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: it returns a verdict with five categories, extracted structured form, actual value with citation, percent delta, and notes v1 scope limitation. 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, starting with natural-language examples, then stating purpose, scope, and output details. Every sentence contributes meaningfully.

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

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

With no output schema, the description adequately explains return values (verdict types, structured form, actual value, citation, delta). It covers scope and efficiency improvement. Minor gap: no guidance on interpreting verdicts or handling ambiguous claims.

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 well-described 'claim' parameter. The description adds context by specifying supported claim types (company-financial, US public companies) and example formats, providing modest extra value beyond the schema.

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

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

The description clearly identifies the tool as a claim verifier with specific examples and distinguishes it from sibling tools by stating it replaces 4-6 sequential calls. The verb 'validate' and resource 'claim' are explicit.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and gives example queries. It lacks explicit when-not-to-use instructions but the scope (company-financial claims) is clearly defined.

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