Pub Dev

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds cost behavior (free default vs. BYO key for Anthropic) and return structure, 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?

Three sentences, front-loaded with main action, no redundant words. Efficiently covers purpose, usage, and return format.

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

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

With no output schema, description adequately details return structure (per-model object with fields, combined view). Explains when to use and parameter roles. No gaps for a 4-parameter tool with 100% schema coverage.

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. Description adds minimal extra meaning beyond schema (default model, API key usage). Does not significantly deepen parameter understanding.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource ('LLMs for visibility'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on probing multiple models for brand 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 states default model and how to add Anthropic with API key. Mentions use cases (AI-marketing audits, pre-launch checks, competitive monitoring) but does not contrast with alternatives like 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 read-only, idempotent, and open-world behavior. The description adds valuable context: it routes to 5,439 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and is a fast default entry point. This goes well beyond the annotations, disclosing key behavioral traits 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 longer than ideal but front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and structured logically: purpose, usage triggers, examples, and alternative tools. Each sentence contributes useful guidance, though some redundancy exists (e.g., repeating 'START HERE'), preventing a perfect score.

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 meta-tool of this complexity, the description is exceptionally complete. It covers the tool's inner workings (routing, argument filling), return format (structured answer with citations), speed, tier availability, and relationships to sibling tools. No output schema exists, but the description gives a clear expectation of what the agent will receive.

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

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

Schema coverage is 100% for the six parameters (all aliases for 'question'), so the description need not add much. It provides example questions and clarifies that the input is a natural language request, but the schema already documents aliases and semantics. This meets the baseline but adds little 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: answering factual questions by routing to a vast array of verified sources and returning structured answers with citations. It uses specific verbs like 'ask' and 'routes', and explicitly distinguishes from siblings such as ask_pipeworx_grounded and deep_research, making its unique role unmistakable.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, including 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names specific alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad questions) and gives examples, making usage expectations crystal 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?

Details the live experimental nature, notes the current inactive candidate, clarifies it is a full working router with no fallback, and explains the comparison process—context far beyond the annotations' safe read-only hints.

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

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

Four sentences packed with relevant beta context; slightly verbose but all sentences serve a purpose, effective front-loading of the beta status.

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 the beta identity, current state, usage, and relation to the stable tool. No output schema is present, but it references the same response shape as ask_pipeworx, which is sufficient given the sibling 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 provides 100% coverage with all parameters described and aliases listed. The description adds no additional parameter detail, so the baseline of 3 is appropriate.

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

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

Clearly identifies the tool as a beta variant of ask_pipeworx, explaining it is an identical universal router with 'candidate routing improvements' and explicitly distinguishing it from the stable sibling and other siblings like ask_pipeworx_grounded.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison against the stable router for deciding merges, giving clear when-to-use context.

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

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

Annotations already provide readOnly and idempotent hints, but the description adds substantial behavioral context: it returns a structured object with evidence (verbatim quote) and confidence, and explicitly lists refusal reasons (not_in_source, no_tool_match, etc.). It discloses the extra LLM call overhead and the strict extraction policy. No contradiction with annotations.

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

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

The description is long but well-structured, front-loading the core purpose, then the return/refusal shape, then usage guidance and cost. Every sentence adds value, though it could be slightly more condensed. It maintains readability despite the density of information.

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

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

Despite having no output schema, the description fully explains the return value structure and refusal behavior. It covers the routing mechanism, the constraint of using only tool results, and the cost trade-off. For a tool this complex, the description is thorough enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, with all parameters being aliases for the same natural language question. The description adds no new parameter semantics beyond what the schema already documents. Baseline of 3 is appropriate since the schema fully covers the parameters.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads' that routes through the same infrastructure as ask_pipeworx but extracts answers only from the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded evidence and explicit refusal, with a specific resource (tool result) and action (extract answer).

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?

Usage is explicitly stated: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also provides an alternative: 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost, giving clear when-to-use vs. when-not-to-use guidance.

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

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

The description provides extensive behavioral details beyond the annotations: it explains confidence thresholds (low-confidence short-circuit, closed markets, wide spreads), resolution-rule risk (cancellation rules), and dynamic fan-out behavior. It also clarifies safety mechanisms (suppressed analysis for phantom matches). No contradictions with annotations found.

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 overly verbose, with multiple sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) that could be consolidated. Repetition occurs (e.g., low-confidence handling mentioned twice). While structured, it lacks conciseness, making it harder for an agent to parse quickly.

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

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

Given the absence of an output schema, the description fully covers return shapes (market, analysis, evidence, parent_event, news), edge cases (closed markets, low confidence, wide spreads), and error handling (429 retries, fallback). It also provides enough examples and classifiers for the agent to understand the tool's capabilities.

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 context: it explains the default for 'depth', provides multiple examples for 'market', and details the effect of 'include_raw' on response size. This goes beyond the schema's basic descriptions, earning a 4.

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

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

The description immediately states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It clearly distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on comprehensive data pulling and analysis.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of when it's appropriate, but does not directly name alternative tools for scenarios where it should not be used. Nevertheless, the guidance is clear and actionable.

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

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

Beyond annotations (read-only, idempotent, non-destructive), description adds: makes ONE parallel call, returns sorted by primary metric, provides citation URIs, explains data sources and fields for each type, and mentions handling of off-calendar fiscal years. No contradictions with annotations.

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

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

The description is moderately long but each part is valuable: trigger phrases upfront, key usage instruction, then data details. Could be slightly more structured (e.g., bullet points) but is well-organized and front-loaded.

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

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

No output schema, but description explains return format (paired data + citation URIs), covers both entity types with specific metrics, mentions edge case (off-calendar fiscal years), and describes sorting. Provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds meaning by explaining what data each type returns (e.g., revenue, net income for company) and concrete examples for values. This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with explicit trigger phrases. It distinguishes from siblings by explicitly preferring over sequential single-entity lookups, and sibling list includes entity_profile which is a single lookup.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Provides specific user query examples that trigger this tool, and specifies limits on entity count and type.

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 richly discloses behavior beyond annotations: account and paid-plan requirements, return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), explicit gaps[] for unanswered facets, contradictions[] scan, hop field, semantic excerpting, and latency expectations. It also states the tool 'never invented' data. 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?

Although longer than typical, every sentence earns its place: it front-loads the account requirement, then explains purpose, alternatives, depth behaviors, output format, and latency. The structure is logical and dense with no fluff or repetition.

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

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

Given there is no output schema, the description fully explains return values (findings packet, gaps[], contradictions[], hop, citation_uri) and covers latency, auth, and alternatives. For a complex multi-tool research tool, this is comprehensive.

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 context beyond the schema by tying 'thorough' depth to a paid plan and reinforcing that 'question' can be broad and multi-part. While the schema already documents depth values and falculties, the account-payment linkage is extra meaningful semantics.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in one call, with decomposition into facets and parallel routing. It also distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and live news, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly names alternatives: 'For a single lookup use ask_pipeworx' and for breaking news 'prefer ask_pipeworx'. It also notes the account requirement and fallback option, giving clear selection 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 indicate readonly, idempotent, non-destructive. The description adds that results include full schemas with examples and are ready to call directly, which provides behavioral context beyond annotations.

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

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

The description is well-structured and front-loaded with purpose, but includes a long list of domains that could be condensed. Most sentences earn their 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 (1 required param, 100% schema coverage), the description fully explains expected behavior and return value (top-N tools with schemas), making it easy for an agent to use.

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

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

Schema coverage is 100% with parameter descriptions. The description adds no new parameter details beyond what the schema already provides, and thus adds minimal extra value.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.). It distinguishes from siblings by noting '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 states when to use ('Use when you need to browse, search...') and advises calling it FIRST. However, it does not explicitly state when not to use it, such as when you already know the specific 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=true and destructiveHint=false. Description adds behavioral details such as 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' and notes soft-fail for patents and fallback for news. No contradictions, but could mention rate limits or performance characteristics.

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

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

The description is relatively long but every sentence adds value, including example queries and detailed return structure. It front-loads the most important usage patterns.

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?

Considering the tool's complexity (multiple data sources, optional fields, fallbacks), the description covers most aspects. No output schema, but return fields are listed. Could mention pagination or limits on returned items, but overall complete.

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

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

Schema coverage is 100%, but description adds meaning: explains that type is only 'company' and value can be ticker or zero-padded CIK, and that names are not supported. This clarifies usage 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: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific examples of queries and explicitly differentiates from sibling tools like resolve_entity.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use it: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description adds no new behavioral context beyond confirming deletion. No contradiction.

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

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

Two sentences, front-loaded purpose and usage. No filler.

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

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

Simple tool with 1 param, no output schema. Description and annotations together are sufficient for an agent to select and invoke.

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

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

Schema coverage is 100% with the key parameter described. Description adds no further parameter meaning beyond 'by key'.

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 states 'Delete a previously stored memory by key' – specific verb and resource. Siblings include remember and recall, making deletion distinct.

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

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

Explicitly states when to use: stale context, task done, clearing sensitive data. Mentions pairing with remember/recall. No explicit exclusions but context is clear.

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

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

Adds context beyond annotations: fetches page, extracts title/description/key links, emits standard markdown, output ready for site-root/llms.txt. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Concise, well-structured: main action first, then process details, then use cases. Every sentence adds value, no redundancy.

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

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

Given simple tool with 2 params, no output schema, and rich annotations, the description fully covers purpose, behavior, output format, and common use cases. No gaps.

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

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

Schema coverage is 100%, so description adds little beyond what schema already provides. It notes default and max for max_links, which are already in schema description. Implicitly clarifies that url is the target to fetch.

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

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

Description clearly states it generates an llms.txt file for a URL, with examples of use cases (client indexing, own project, competitor audit). Distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on generating the standard file format.

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

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

Explicitly lists when to use (getting a client's site indexed, drafting for own project, auditing competitor). Does not provide explicit when-not-to-use or alternatives, but the specific function makes usage clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details (returns specific fields, active by default) without contradicting annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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

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

Given the simplicity (1 optional param, no output schema), the description fully covers purpose, usage, and return structure.

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 100%, so baseline 3. Description does not add meaning beyond schema for the parameter; it only states implicit 'active' default.

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

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

The description clearly states it lists the caller's active subscriptions, and specifies the returned fields, which distinguishes it from sibling tools like subscribe/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 advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No explicit when-not, but context is clear.

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

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

The description goes beyond the sparse annotations (all false) by disclosing rate limits (5 per identifier per day), that it is free and doesn't count against quota, that the team reads digests daily, and content guidelines (don't paste end-user prompt, reference Pipeworx tools). These are important behavioral traits that the annotations do not cover.

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?

Every sentence serves a purpose: stating the action, defining categories, drawing boundaries, explaining the result, and setting expectations. The description is dense with useful information and contains no fluff or repetitive content.

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

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

For a feedback tool with 3 parameters and no output schema, the description covers all necessary context: what to report, how to frame it, limitations, and consequences. It is self-contained and answers likely user questions without needing additional sources.

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

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

Schema has 100% coverage of parameters, so baseline is 3, but the description adds meaningful guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and clarifies which tool names are relevant. This adds value to parameter usage.

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

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

The description clearly states the tool's purpose with a specific verb ('Tell') and resource ('the Pipeworx team'), followed by concrete examples of what qualifies (broken, missing, praise). It also explicitly differentiates from other tools by scoping feedback to Pipeworx connection tools only.

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

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

Provides explicit when-to-use guidance by mapping feedback categories (bug, feature/data_gap, praise) and when-not-to-use with a clear exclusion for non-Pipeworx servers. It even directs users to file with the appropriate server, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). These details go beyond annotations and help the agent understand side effects.

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 with clear structure: core output, use cases, then data provenance. Every sentence adds value. No redundant or vague phrasing.

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

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

For a simple tool (1 param, no output schema), the description covers purpose, use cases, parameter semantics, data origin, caching, and privacy. Nothing missing given the complexity.

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

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

Schema covers 100% with enum description. Description adds functional meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the right window.

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 ('Returns') and resource ('top tools, top packs, and total call volume over a recent window'). Use cases explicitly listed, distinguishing it from siblings that are mostly query/entity tools.

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

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

Three specific use cases provided, plus guidance on window selection (short vs long windows). Does not explicitly say when not to use, but context is sufficient.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context: algorithmic details (Jaccard similarity, partition filter, fill check), response structure, and concrete conditions for acting on signals. No contradiction exists between annotations and description.

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

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

The description is front-loaded with the core purpose, then structured into clear sections for each mode, followed by important filters and fill check. Every sentence adds value for such a complex tool; no unnecessary verbosity.

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

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

Despite lacking an output schema, the description thoroughly explains the response: opportunities array fields, partition_check object, and fill check details. It also covers edge cases like placeholder filtering and similarity thresholds, making the tool fully explainable to 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?

Schema coverage is 100% with descriptions for both parameters. The description adds substantial extra context: examples of valid event slugs, explanation that topic searches related events, and behavior of each mode. This exceeds the baseline of 3 for high coverage, meriting a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: trending scan, event-specific, and cross-event topic scan. The verb 'find' and resource 'arbitrage opportunities' are specific, and the detail differentiates 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 usage guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also advises when not to trade via the fill check and points to an alternative tool: 'For custom sizing use polymarket_fill_risk'.

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

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

Description fully discloses behavior: three response segments, caching (1h), diagnostics, and detailed edge calculations. Annotations already confirm readOnlyHint=true, and description reinforces that the tool reads and analyzes, no mutation. No contradictions.

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

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

Description is thorough and well-structured with clear sections (segments, knobs, response structure), but it is lengthy. Every sentence adds value, but conciseness is slightly sacrificed for completeness.

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

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

Given no output schema, the description fully explains the response structure (by_segment, diagnostics, per-opportunity fields) and all filters/knobs. It provides enough context for an agent to understand what the tool returns and how to use it effectively.

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, but the description adds significant value with usage tips (e.g., 'Bump for very thin partitions'), clarifies tradeable-edge knobs, and explains how knobs interact like min_partition_leg_kelly vs min_kelly.

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 verb 'scan' and resource 'Polymarket markets', and specifies the unique purpose of finding opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools by detailing specific model families and segments.

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

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

Description provides clear context for use ('what should I bet on today') and implies discovery without paging. However, it does not explicitly exclude alternatives or mention when not to use this tool over siblings like polymarket_arbitrage or 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?

The description provides extensive behavioral context beyond annotations: it details the output structure (tracked, expired, snapshot_dates), explains limits (60-day TTL, daily closes), and clarifies that decay is computed from daily closes. Annotations already indicate read-only, idempotent, and non-destructive 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 well-structured and front-loaded with the key question. It covers args, response format, and limits in a logical order. While somewhat dense, every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

The description is comprehensive given the lack of an output schema. It fully explains the response structure (tracked, expired, snapshot_dates) and important caveats (TTL, decay calculation). For a tool with moderate complexity, this is complete and self-contained.

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

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

Schema coverage is 100%, and the description largely repeats schema info for days and window. It adds minimal extra context (e.g., 'clamp 2-30' for days), but overall does not significantly enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's purpose: to provide edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends.

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 when to use the tool (when edge persistence info is needed) but does not explicitly mention alternatives or when not to use it. Given the sibling context, it is clear enough for an agent to decide.

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

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

Annotations indicate read-only and idempotent behavior; description adds critical context: walks the order-book ladder, returns fill metrics, and warns that partial basket fills convert arbitrage into unhedged directional positions—the dominant loss mode. 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 long but well-structured with explicit single-market and basket sections. Every sentence provides essential information. Slightly verbose but justified by the tool's complexity.

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

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

Despite no output schema, the description thoroughly enumerates return fields for both modes, including verdicts, profit, and risk indicators. With 4 parameters and no nested objects, the description is fully adequate.

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

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

Schema coverage is 100%, but description enhances each parameter with mode-specific meanings, defaults, and constraints (e.g., side defaults differ by mode, size_usd interpretation). Adds substantial 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 it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinctly explains single-market and basket modes. It differentiates itself from siblings by advising use before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500.

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 specifies when to use (before arbitrage/edge signals above ~$500) and prerequisites (requires 'market' or 'event'). Does not explicitly state when not to use, but context makes it clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the caveat about structural mismatches making spreads meaningless. 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 long but each sentence adds unique value. Front-loaded with purpose, then modes, response, safety. Could be slightly more concise, but appropriate for the tool's complexity.

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

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

Given complexity (3-param, no output schema), the description covers purpose, dual modes, return structure, safety warnings, and temporal alignment. Agents can understand when to use and how to 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% with descriptions for all 3 parameters. Description enriches them by explaining topic list, explicit override behavior, and response fields (leg prices, spread, safety fields). Adds substantial meaning beyond schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on two venues and explicitly mentioning structural mismatches.

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

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

It explains two modes (topic shortcuts and explicit tickers) with clear examples. Warns that most pre-mapped topics currently return compatibility_warning, guiding the agent to not expect actionable spreads. Lacks explicit 'when not to use' but overall strong.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping ('scoped to your identifier') and the relationship with other tools. 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 three sentences long, front-loaded with the primary purpose, and each sentence adds necessary context without redundancy. Highly efficient.

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

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

Given that there is no output schema, the description adequately explains the return behavior (value or list). It covers usage, scoping, pairing, and provides examples. For a simple read tool with comprehensive annotations, it is fully complete.

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

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

Schema coverage is 100% with a single optional 'key' parameter. The description adds meaning by stating that omitting the key lists all saved keys, and provides examples of what keys are used for (target ticker, address, research notes).

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: 'Retrieve a value previously saved via remember, or list all saved keys.' It specifies the verb (retrieve/list) and resource (stored memory values), and distinguishes from sibling tools like remember and forget.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds value by explaining the mark_read flag's effect on subsequent calls and the returned fields, providing behavioral detail beyond annotations.

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

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

Three sentences, front-loaded with the main purpose. Each sentence adds value: purpose, return fields/filtering, behavioral note, and alternative access. Could be slightly tighter but 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?

With no output schema, the description explains return structure (source, citation_uri, payload). Combined with annotations covering idempotency and safety, and mention of polling/alternate URL, it provides sufficient context for a simple read tool.

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

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

Schema covers 100% of parameters with descriptions. The description reiterates filtering by type and since, but adds meaningful context for mark_read (flagging events as read to affect next call). This goes beyond repeated info.

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 'Pull[s] fired events from your subscription feed' and specifies return fields (source, citation_uri, payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on events, not subscription metadata.

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

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

Explicitly mentions filtering by type and since, and notes that polling works fine. Also provides an alternative endpoint for scripts/dashboards, giving context on when to use the tool vs. direct HTTP access. Could be improved by stating when not to use it.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable behavioral details: parallel calls, GDELT→GNews fallback, USPTO soft-fail, return format with citations. No contradictions.

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

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

Description is information-dense yet well-structured: example queries first, then source logic, parameter details, return format, alternative tool. Every sentence adds value with no redundancy.

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

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

Given no output schema and multi-source complexity, the description fully covers behavior (fallback, soft-fail), parameter options, return structure, and sibling tool differentiation. Compensates for lack of output schema.

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

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

Schema coverage is 100% with descriptions for all parameters. Description reinforces parameter formats (e.g., 'since' examples) but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool provides a change feed for a company in a given time window, listing specific sources (SEC, GDELT/GNews, USPTO) and example queries. It distinguishes from sibling tool entity_profile, which offers static data.

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

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

Explicit advice: 'Use entity_profile instead when you want the static profile...' provides clear guidance on when not to use. Also implies usage for recent changes/news/filings.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 four sentences, each adding essential information. It front-loads the main purpose and efficiently covers usage, scope, and pairing with siblings. 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?

The tool is simple (two required params, no output schema). The description explains persistence behavior and pairing with recall/forget, which is sufficient. A small improvement could mention that the tool likely returns nothing or a confirmation, but the omission is minor.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description provides example key names and clarifies value as 'any text,' but these largely repeat the schema's own descriptions. Thus, the description adds minimal semantic 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: 'Save data the agent will need to reuse later.' It specifies the action (save), the resource (data as key-value pairs), and distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning them.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. Description adds that calls cascade through multiple endpoints, replacing manual lookups, providing useful context beyond annotations.

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

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

Description is well-structured with clear sections for supported types and usage context. Slightly verbose but front-loaded with key purpose. No wasted sentences.

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

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

Given high schema coverage and informative annotations, the description is complete: covers input types, output structure (ticker, CIK, etc.), and internal behavior. No output schema, but description adequately explains return values.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples (e.g., 'AAPL', 'ozempic') and clarifies acceptable input forms for each type, adding meaning beyond schema.

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

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

Description uses specific verbs ('resolve', 'look up') and clearly states the tool maps names to canonical IDs. It distinguishes from sibling tools by being the go-to ID resolution tool, listing examples for 'company' and 'drug'.

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 FIRST whenever you have a name but need an ID.' Provides context for when to use, though does not explicitly list alternatives. Still clear and helpful.

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 explains internal behavior (probes each entity with ai_visibility_check), output structure (ranked list with score, confidence, signal density), and does not contradict annotations (readOnlyHint, idempotent, etc.).

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

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

Two sentences, front-loaded with key action, no fluff. Every sentence adds value.

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

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

Despite lacking an output schema, the description explains the return format sufficiently. All necessary context (parameters, use case, internal call) is covered.

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 includes detailed descriptions for all parameters. The description adds minimal extra meaning beyond restating the schema's first-entity-as-subject convention, so baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, and ranks results. It differentiates from sibling 'ai_visibility_check' which is a single-entity probe.

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

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

Description gives explicit use case ('competitive AI-marketing audits') and example question. It mentions the underlying tool but does not discuss when not to use or compare with other siblings like 'compare_entities'.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details: bundlephobia first measurement can take 5-30s, and sources_failed lists failures. 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 dense and front-loaded with purpose, but slightly verbose. Every sentence adds value, though it could be tightened 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's complexity (multiple sources, partial failures, return summary), the description covers key aspects: return structure, fallback behavior, and timing. No output schema exists, but the description compensates.

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%, already describing both parameters. The description adds that version defaults to latest and scoped packages are accepted, but these are minor additions 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 as a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, and tree-shake support. It distinguishes itself from the fallback deps.dev:version tool 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?

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small"'. Also notes NPM-only in v1, and mentions graceful partial failure handling.

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 discloses the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character cap (200K chars with truncation+flag), and output details (offsets, scores). No contradiction with annotations.

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

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

The description is well-structured, starting with the core purpose, then usage guidance, then technical details. It is moderately long but every sentence adds value. Minor redundancy could be trimmed, but overall it is concise and front-loaded.

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

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

For a tool with no output schema and moderate complexity, the description covers input, output (passages with offsets/scores), limits (200K chars), and technical details (embeddings, chunking). It also mentions a sibling pairing, making it a complete reference for the 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?

Schema coverage is 100% with descriptions, but the description adds value by giving concrete examples for the query parameter and explaining how to use the text parameter (e.g., SEC 10-K body, article). This helps the agent understand the intended use beyond schema types.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, returning top-N passages with offsets and scores. It distinguishes itself from siblings by mentioning its pairing with ask_pipeworx_grounded and the use case for large records.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative and pairing suggestion: 'Pairs with ask_pipeworx_grounded.' This gives clear guidance on how to choose this tool among siblings.

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

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

The description adds valuable behavioral context beyond annotations: OAuth requirement, delivery channel specifics, SMS cap, webhook signing secret one-time return, and auto-disable condition. Annotations indicate idempotentHint=true and readOnlyHint=false, which are consistent.

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

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

The description is front-loaded with the main purpose and is well-structured, but it is somewhat lengthy. It could be slightly trimmed while retaining all essential information.

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

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

For a tool with no output schema, the description covers return value, requirements, type-specific parameters, delivery options, and limits. It sufficiently prepares the agent for invocation, though some minor details (like the exact format of the returned ID) are omitted.

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

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

All parameters are fully described in the schema (100% coverage). The description further enriches by providing type-specific parameter examples for each subscription type, such as 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}', adding meaning beyond the schema.

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

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

The description clearly states the verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like 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?

The description explicitly states requirements (Pipeworx OAuth account, not anonymous/BYO) and provides examples for each subscription type. It implies when to use (to create a subscription) but does not explicitly mention alternative tools for listing or unsubscribing.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it is an onboarding entry point, returns examples with exact tool+argument shape drawn from live catalog, and explains topic filtering. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with key phrases and organized with lists. It could be slightly more concise, but every sentence contributes 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?

Despite lacking an output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shape). It covers purpose, usage, parameter behavior, and context, making it complete for the tool's role as an onboarding guide.

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

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

Schema description coverage is 100% with a basic description for the `topic` parameter. The tool description adds meaningful detail: lists example topic values (finance, pharma, etc.) and explains behavior when omitted (full spread) or provided (focus). This adds semantic 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 explicitly states the tool returns category-bucketed example questions for onboarding and discovery. It distinguishes itself from siblings by specifying it should be used first when the agent doesn't know what Pipeworx can do, and mentions meta-tools like ask_pipeworx.

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

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

The description gives clear when-to-use instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes calling with no arguments for full spread or with a topic to focus.

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 important details beyond annotations: ownership enforcement, row deactivation (not deletion), and availability of historical events via recent_alerts. No contradiction with annotations.

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

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

Two sentences, front-loaded with the key action, 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 simple tool with one parameter and no output schema, description fully explains behavior and outcome.

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

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

Schema has 100% coverage with description for the single parameter. Description does not add new meaning beyond the schema.

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

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

Description clearly states the action ('Cancel a subscription by id'), the resource ('subscription'), and distinguishes from siblings 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?

Describes when to use (cancel subscription) and ownership enforcement. Lacks explicit 'when not to use' or alternative tools, but context with siblings 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: dual pipeline routing (SEC EDGAR+XBRL for financial, grounded pipeline for others), exact percentage math, return fields (verdict, value with citation, reasoning), and parameter overrides. 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 detailed and well-structured: examples first, then usage, then behavior, then returns. It is slightly long but each sentence adds value. Could be slightly more concise, but still effective.

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

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

Given the complexity of the tool (two pipelines, tolerance parameter, multiple verdicts) and no output schema, the description covers all necessary aspects: what it does, when to use, how it works, what it returns. The return format is explicitly listed, compensating for lack of output schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the role of tolerance_pct (overrides implied tolerance, default cap 5%) and the claim format, but the schema already provides adequate information.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries and distinguishes itself by explaining that it replaces multiple sequential calls, differentiating it from sibling tools.

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

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

Explicit usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies two distinct pipelines (financial vs. other claims) and explains how tolerance_pct overrides default behavior, providing clear guidance on when and how to use it.

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