Buzzword Density

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

Annotations already declare readOnlyHint and idempotentHint as true, so the safety profile is clear. The description adds context about external API calls, default model (free), BYO key for Anthropic, and return format (score, confidence, signals, raw_response). This is sufficient beyond annotations.

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

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

The description is concise (two paragraphs) with front-loaded core purpose. Every sentence adds value, no repetition or fluff. Structure is logical: function, then technical details, then use cases.

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 the description explicitly mentions the return format (per-model {score, confidence, signals, raw_response} + combined view). All input parameters are explained. It covers the main aspects adequately for a moderate-complexity tool.

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

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

Schema coverage is 100%, so each parameter has a description. The description text adds value by explaining the _apiKey flow, default model choice, and context disambiguation, which goes beyond the schema's parameter descriptions.

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

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

The description clearly states it probes LLMs for knowledge and scores visibility (0-100) per model. It specifies the verb 'probe' and resource 'LLMs for business/brand/product/topic', and distinguishes from siblings like ask_pipeworx and scan_competitor_ai_presence through unique output and use cases.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use optional parameters (e.g., _apiKey for Anthropic). However, it does not explicitly contrast with sibling tools or state when not to use, leaving some ambiguity.

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

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

Annotations already declare read-only, open-world, and idempotent hints, but the description adds valuable context: routing across 5,529 tools, verified sources, filling arguments, stable citation URIs, one fast call, and live news coverage. 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 and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). It is somewhat long with many examples, but each section contributes useful context and alternatives, and the flow is logical.

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

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

The description covers purpose, usage, alternatives, scope, and return style (structured answer with citation URIs). It lacks a detailed return schema, but no output schema is provided, and the description is sufficient for agent selection and 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?

The input schema already covers the 'question' parameter and all aliases with 100% coverage. The description adds examples but no additional parameter-level semantics beyond what the schema provides, 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?

The description uses specific verbs like 'routes' and 'returns' and identifies the resource ('5,529 tools across 1,455 verified sources'). It clearly distinguishes itself from sibling tools such as ask_pipeworx_grounded and deep_research, making the purpose immediately clear.

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 over web search and alternatives, including 'START HERE for most questions' and 'Step up only when needed' with named tools. It provides concrete trigger phrases and examples, making selection criteria 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?

The description reveals significant behavioral context beyond annotations: it's an experimental edge with candidate routing improvements enabled live, that results are compared against the stable router, and that it 'falls back to nothing' but is a fully working router. It even mentions the retirement date of the last candidate, adding trustworthy transparency. 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 and moderately detailed, front-loading the core beta router identity. Each sentence contributes useful context (functionality, current state, usage, reassurance), though it could be slightly trimmed 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?

For a tool with only one required parameter, no output schema, and rich annotations, the description is highly complete. It explains the beta nature, current equivalence to ask_pipeworx, how to use it, and that it's a full working router. The mention of 'same response shape' covers return behavior despite lacking an output schema.

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

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

Schema description coverage is 100%, with all six parameters fully documented (question and five aliases). The description adds no extra parameter semantics, but this is acceptable since the schema carries the burden. Baseline of 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing the experimental routing improvements, making its purpose and relationship to siblings 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?

Usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, so matches ask_pipeworx exactly). However, it does not explicitly warn against using it in production or name an alternative for stable use, though this is implied.

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 the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: it returns a structured result with refusal reasons, may explicitly refuse with five possible reasons, and costs an extra LLM call. This goes far beyond what annotations convey and sets accurate expectations for failure modes.

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

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

The description is dense but well-structured, front-loading the core purpose in the first phrase, then explaining mechanism, return shape, use cases, and cost trade-off in just four sentences. Every sentence adds unique information and there is no filler or repetition of schema/annotation 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?

With no output schema, the description compensates by fully specifying the success and refusal response structures, including field names and refusal reason enums. It also covers the routing mechanism, use cases, and cost comparison, making it fully self-contained for an agent to decide invocation 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% with all parameters documented as aliases for 'question,' so the baseline is 3. The description adds context that the question is in natural language and will be routed to tools, but it does not add syntax, format, or example-level detail beyond the schema. It meets the baseline but does not exceed it.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb+resource+scope that immediately identifies the tool's unique value. It further distinguishes from siblings by explicitly comparing to ask_pipeworx and describing the grounded extraction mechanism, making it clear this is the evidence-cited variant.

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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides an explicit exclusion: 'prefer ask_pipeworx for casual lookups,' and names the alternative directly, giving clear decision criteria.

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 discloses behavioral traits: resolution process, classifier fan-out, response shapes, safety mechanisms (low_confidence_match, market_closed_or_inactive), wide spread handling, resolution-rule risk. Annotations already indicate read-only and idempotent, and the description adds significant context beyond annotations without contradiction.

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

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

The description is very long and detailed, covering multiple aspects with examples and caveats. It is front-loaded with the main purpose, but the length reduces conciseness. While all information is relevant, some redundancy could be trimmed. Still, it is well-structured with clear sections.

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

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

Given the tool's complexity (multiple classifiers, fan-out, response shapes, safety modes, no output schema), the description is remarkably complete. It covers input formats, behavioral edge cases (closed markets, wide spreads, resolution rules), and explicit guidance on inspecting match confidence and response fields.

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

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

Schema coverage is 100%, but the description adds substantial value: examples for market parameter, clarification of depth (quick vs thorough), explanation of include_raw (summarized vs full payloads), and typical use guideline for include_raw. This goes well beyond the schema's property descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edge_tracker or polymarket_edges, which have similar domain focus.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It advises inspecting market_match_confidence before trusting analysis and explains safety behaviors. However, it does not explicitly state when to use alternatives or 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 indicate read-only, idempotent, open-world, non-destructive. Description adds details on return values (count, score, severity, flagged terms) and optional roast, enhancing transparency 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?

Single sentence with all key elements: action, dictionaries, output, optional feature. No redundant 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 output schema presence, description covers tool purpose, parameters, and return information sufficiently for a simple analysis 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%. Description adds meaning by listing output metrics and explaining roast parameter effect, surpassing baseline of 3.

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

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

Description clearly states the tool analyzes text for overused industry jargon using specific dictionaries, and lists return metrics. Distinct from sibling tools which are unrelated.

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 implies use for analyzing buzzwords in text, with optional roast. No explicit when-not-to-use, but sibling tools are different domains, so 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 a safe read operation (readOnlyHint, openWorldHint, idempotentHint). The description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting, and citation URIs, which enrich 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 paragraph that is information-dense but well-organized, starting with trigger phrases and purpose, then entity details. It is concise yet comprehensive, though could be slightly improved by splitting into shorter 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 2 parameters and no output schema, the description fully covers what the tool does: data retrieved (financial metrics for companies, adverse event counts for drugs), sorting, citation URIs, and efficiency benefits. No gaps remain.

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

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

Schema has 100% coverage with two parameters. The description adds meaning by explaining that for 'company' type values should be tickers/CIKs, and for 'drug' type values should be drug names, with concrete examples. This goes beyond the schema's enum and array descriptions.

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

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

The description clearly states that the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one call, and distinguishes itself from sequential single-pack lookups by providing trigger phrases like 'compare X and Y'. It also specifies the data retrieved for each entity type.

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 recommends preferring this tool over sequential single-pack lookups when comparing entities, and differentiates between 'company' and 'drug' types. It lacks explicit exclusions but provides 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?

Adds substantial context beyond annotations: account requirements, paid tier for thorough depth, facet decomposition and parallel routing, output packet structure (evidence, confidence, source, gaps[]), and latency ranges 15-90s. Describes never-invented gaps and citation fetchability, which annotations do not convey.

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

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

The description is a long single paragraph but information-dense with every sentence contributing. It front-loads the account requirement and core capabilities, and the length is justified by the tool's complexity; however, bullet points would improve scannability.

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 appropriately details the return packet (verbatim evidence + confidence + source + fetched_at + citation, gaps[], hop, contradictions[]). It also explains when not to use the tool and mentions latency, making it complete for complex two-parameter 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 input schema already documents both parameters with 100% coverage. The description adds useful meaning: it explains the depth parameter's hop behavior ('standard' re-angles unanswered gaps; 'thorough' chases leads) and latency implications, going beyond enum names.

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 opens with 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call', clearly stating the verb and resource. It distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and positioning against ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx' with reasons. Also covers signed-in vs not-signed-in alternatives, and depth-level selection for iterative research.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results include full schemas and curated examples ready to call directly, enhancing transparency about the output format and readiness for invocation.

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

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

The description is efficient: first sentence establishes purpose, then lists use cases, then explains output behavior. No redundant sentences; all information is essential and well-organized.

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 value: top-N tools with names, descriptions, and full input schemas. For a discovery tool, 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%, so baseline is 3. The description adds value by providing example queries and explaining that aliases (task, q, search, description) are accepted, plus indicates the limit parameter. This goes beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and provides a comprehensive list of domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific tasks.

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

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

Explicitly says 'Call this FIRST when you have many tools available' and gives examples of when to use (browse, search, look up). Lacks explicit exclusion of alternatives but implies use for discovery rather than direct answers.

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

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

The description adds substantial behavioral context beyond annotations. It discloses the parallel call nature, specific data returned (SEC EDGAR, XBRL, USPTO, news, GLEIF), failure modes for patents ('soft-fails until reactivated'), and the structure of responses. This complements the readOnlyHint, idempotentHint, and destructiveHint 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 example queries, then stating purpose, then detailing outputs and constraints. It is fairly concise given the complexity, but could be slightly tighter by removing redundant phrasing like 'company' repeated.

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 does a good job detailing return types (cik, filings, fundamentals, patents, news, LEI) and caveats. It covers key aspects but slightly lacks depth on exactly how each field is returned (e.g., the specific number of filings is mentioned as 'up to 5' but ordering of fundamentals is mentioned).

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

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

The description expands on parameter meanings beyond the schema: it explains that 'value' can be a ticker or zero-padded CIK, and clarifies that names are not supported. Since schema coverage is 100% and the schema already includes descriptions, the description adds valuable but not essential 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 tool's purpose: generating a full cross-source profile of a US public company in one parallel call. It uses specific verbs like 'returns' and 'fans out', and distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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 guidelines, instructing to prefer this tool over chaining individual lookups for holistic views. It also specifies input constraints ('Pass ticker "AAPL" or zero-padded CIK') and directs users to 'use resolve_entity first if you only have a name', offering a clear alternative.

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

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

Annotations already include destructiveHint=true and idempotentHint=true, so the destructive nature is clear. Description adds 'clear sensitive data' context but does not elaborate on idempotency or consequences of deleting non-existent key. Minimal extra 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?

Two sentences: first states purpose, second gives usage guidelines. No redundancy, efficient 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?

Simple tool with one parameter and clear annotations. Description covers purpose and usage. No output schema but delete operations typically don't need detailed return info. Could include error handling details but not essential.

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 description for the single parameter 'key'. Description does not add additional meaning beyond 'Memory key to delete' already in schema. Baseline 3.

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

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

Description uses specific verb 'Delete' and resource 'memory by key', clearly stating the action. It distinguishes from siblings 'remember' and 'recall' by specifying deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Mentions pairing with related tools. Does not explicitly say when not to use, but guidance is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions; all behavioral aspects are transparent.

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

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

Single, well-structured paragraph that front-loads the core action and format, then lists use cases. Every sentence adds value; 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?

Despite lacking an output schema, the description clearly states the output is a 'single text blob ready to drop at site-root/llms.txt', which is sufficient for a simple read operation. It covers purpose, usage, and output format adequately.

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

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

Schema coverage is 100%, so description adds little beyond schema. The description reinforces the purpose of 'url' (full URL to summarize) and mentions default/max for 'max_links', which is helpful but not a significant addition.

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 generates a production-ready llms.txt file for any URL, explaining the action (fetches, extracts, emits) and the format. It distinguishes itself from the many sibling tools by focusing on a specific, well-defined use case for AI crawler indexing.

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

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

Explicitly lists three practical use cases: getting a client's site indexed, drafting for own project, and auditing competitors. While it doesn't explicitly state when not to use, the provided scenarios give clear guidance.

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

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

Annotations already mark it read-only/idempotent; description adds that it defaults to active subscriptions and specifies the return fields, enhancing transparency.

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

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

Two sentences: first covers purpose and output, second covers usage. No extraneous words, information 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?

Complete for a simple list tool: documents return fields, parameter behavior, and usage context. No output schema needed given the list of fields.

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

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

Schema covers 100% of the single parameter with description; tool description only reinforces schema content without adding new semantic 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?

Explicitly states the tool lists active subscriptions and enumerates the returned fields (id, type, etc.), clearly distinct from subscribe/unsubscribe siblings.

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?

Directly advises using this tool to review monitoring before adding more subscriptions or to find an id to cancel, providing 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 only state readOnlyHint:false and destructiveHint:false, but the description adds crucial behavioral details: returns a claim_token when filed without an account, supports later retrieval with status/changes, rate limit of 5/day, free, and no quota impact. It also instructs to describe issues without pasting end-user prompts. 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 every sentence earns its place: the first line is a clear purpose, followed by usage triggers, exclusions, token behavior, rate limit, and quota note. No redundancy or filler. Front-loaded and well-organized 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?

Despite no output schema, the description fully explains return behavior (claim_token on filing; status/changes on later call). It covers prerequisites (no account needed, but token), limits, and context about what to include. Given a 4-param tool with nested object and no output schema, this description is complete enough for an agent to invoke correctly.

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

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

Schema covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by mapping enum values to real scenarios (bug, feature, data_gap, praise) and by giving extra guidance on the message param ('don't paste the end-user's prompt') and how to use claim_token effectively. This elevates it above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by specifying it is for reporting issues about Pipeworx tools only, not other MCP servers.

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?

Extensive when-to-use guidance is given for each feedback type (bug, feature/data_gap, praise). It explicitly says when NOT to use ('if the tool came from a different MCP server... file it with that server instead'), plus provides the alternative. This fully covers usage vs 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. Description adds value by disclosing data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h). 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?

Around 120 words, well-structured with bullet points. Front-loaded with main functionality. Minimal waste, though could be slightly shorter. Still very 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?

Despite no output schema, description adequately documents return values (top tools, top packs, total call volume). Covers caching, privacy, and parameter semantics. Complete for the tool's complexity and annotations.

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

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

Schema coverage is 100% with full description for the single parameter 'window'. The tool description adds no new info beyond what's already in the schema parameter description, 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?

The description clearly states it returns top tools, top packs, and total call volume over a recent window, using a specific verb ('returns') and resource. It distinguishes itself from siblings like 'discover_tools' by focusing on trending usage rather than available 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 explicit use cases are provided (discovering hot data sources, confirming popular tools, aligning use cases). The description explains window trade-offs (short for hot, long for steady-state). No explicit exclusions or alternatives, but guidance is clear.

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

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

Annotations declare the tool readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: scanning top markets, partition-sum checks with deviation thresholds, semantic anchor for cross-event pairs, placeholder filtering, fill check against live CLOB depth, and warnings not to trade if realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is a single paragraph but well-structured: starts with core purpose, then details each mode, then explains deeper logic (semantic anchor, partition filter, fill check). Front-loaded with the most important info. Slightly verbose but every sentence adds value; could be broken into sections for better readability.

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

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

Given the tool's complexity (two modes, multiple checks, fill validation) and the absence of an output schema, the description covers all necessary aspects: it explains the logic of monotonicity violations and partition-sum checks, describes the response structure (opportunities[].gap_pp, suggested_trade, reasoning, partition_check, fill_check details), and references sibling tools for additional usage. Highly complete.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds substantial meaning: it explains that event mode walks child markets for date-axis/threshold-axis ordering and partition check, and topic mode searches related events across the platform. It provides examples of acceptable inputs (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'). This greatly 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities), and method. Distinguishes three invocation modes (no args, event, topic) and their outcomes, setting it apart from sibling tools like polymarket_edges or 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?

The description gives explicit guidance on when to use each mode: 'Call with NO args for a trending scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode 'for a specific market' and points to polymarket_fill_risk for custom sizing. It lacks explicit 'when not to use' statements but provides clear context and alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: caching (1h KV), model family details, edge calculation, diagnostic fields, and tradeable-edge knobs. 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 clear sections (model families, tradeable-edge knobs, response top-level) and front-loaded purpose. Every sentence adds value, though some technical detail could be condensed.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics) and provides enough detail for an agent to understand all capabilities and limitations. Covers caching, edge calculation, filter knobs, and output fields.

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

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

Schema description coverage is 100% with all 9 parameters documented. The description adds value by explaining parameter interplay and rationale (e.g., slippage_pp discussion of thin depth, min_partition_leg_kelly behavior). Baseline 3 but elevated due to added insight.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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: 'Built for "what should I bet on today"' and explains tradeable-edge knobs with guidance on when to apply them (e.g., 'Set to 2 to require tight books'). However, it does not explicitly state when not to use this tool versus siblings.

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

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

Annotations indicate readOnly=true, idempotent, non-destructive. The description adds critical details: history bounded by 60-day TTL, decay from daily closes (not intraday), and snapshot-on-cache-miss behavior. 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, front-loading purpose, then detailing response fields, and ending with limits. Every sentence adds value, though some technical details could be slightly more concise 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?

Even without an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) including field semantics. It covers limitations (TTL, intraday) and provides necessary context for using 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 each parameter. The description reiterates days (default 14, max 30) and window (default '1wk') but adds usage context like 'clamp 2-30' and snapshot families. This adds marginal 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 it provides 'edge persistence and decay telemetry' answering the key question of edge duration and shrinking. It uses specific verbs like 'track' (implied) and clearly distinguishes from sibling tools like polymarket_edges (raw data) and polymarket_arbitrage.

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

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

The description gives a concrete use case: distinguishing fresh vs old wide edges. It implies when to use it but does not explicitly state when not to or mention alternatives. Context 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 already indicate the tool is read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about thin books and forced directional risk. This goes well 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?

The description is somewhat lengthy but well-structured with clear sections (SINGLE-MARKET, BASKET). It front-loads the essential purpose and requirements. Every sentence provides necessary detail; however, minor condensation could be achieved without loss of clarity. Still, it is appropriately informative.

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

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

For a complex tool with two modes, 4 parameters, and no output schema, the description covers all critical aspects: input requirements, default behavior, return fields (including top_of_book, VWAP, slippage, verdict, capture_ratio, profit_usd, thin_legs, forced_directional_risk), and risk explanations. It is comprehensive for the agent to understand and use the tool 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 description coverage is 100%, so baseline is 3. The description adds value by explaining defaults (size_usd=1000, side default behavior in basket mode), clarifying how size_usd is interpreted differently for buys vs sells and single-market vs basket, and describing the auto-behavior for side in basket mode. This semantic enrichment justifies a 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes, and its purpose is reinforced by context signals (e.g., using before arbitrage signals). The verb and resource are specific and unique among sibling tools.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills lead to directional risk), and states requirements (one of `market` or `event`).

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, openWorldHint, idempotentHint), the description extensively details behavioral traits: two operating modes, response structure (leg prices, spreads, safety fields), and how compatibility warnings arise from mismatched bet shapes or unrelated events. No contradictions with annotations.

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

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

The description is well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS) and bullet points. However, it is relatively verbose; some sentences could be condensed without losing clarity. Nonetheless, the structure aids readability.

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

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

Given no output schema, the description explains the response in sufficient detail (leg prices, spreads, safety fields, temporal alignment). It covers edge cases and what counters mean. Slightly more precision on exact return format could improve, but it's adequately complete.

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

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

Schema coverage is 100% with all three parameters described. The description adds examples and behavior (topic lists shortcuts, explicit fields override topic mapping). This adds meaning beyond the raw schema, justifying a score above 3.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on across-venue comparison and offers two modes (topic shortcuts and explicit tickers).

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 check price spreads between two venues for equivalent outcomes) and warns about common pitfalls (most pre-mapped topics yield compatibility warnings). It does not explicitly list when not to use it or alternatives, 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, destructiveHint=false, and idempotentHint=true. The description adds context beyond annotations: it is scoped to an identifier (anonymous IP, BYO key hash, account ID) and explains the listing behavior when key is omitted. 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 and well-structured: first sentence defines core behavior, second explains usage, third covers scoping, fourth suggests pairings. Each sentence adds value, 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 simplicity (one optional param, no output schema, good annotations), the description is complete. It explains what the tool does, when to use it, scoping, and pairing with sibling tools. All necessary context for an agent to select and use the tool is provided.

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

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

Schema coverage is 100% with one optional string parameter already described in the schema as 'Memory key to retrieve (omit to list all keys)'. The description adds usage examples and context about pairing but doesn't add new semantic information 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 retrieves a value saved via remember or lists all saved keys. It uses specific verbs ('Retrieve', 'list') and resource ('value previously saved', 'saved keys'). It distinguishes from sibling tools (remember, forget) by explicitly 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?

The description explains when to use the tool: 'look up context the agent stored earlier'. It provides examples (target ticker, address, research notes) and mentions scoping and pairing with remember/forget. However, it doesn't explicitly state when not to use it or name alternatives beyond the 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?

The description describes mark_read:true as flagging events read, which is a write operation. However, the annotation sets readOnlyHint=true, indicating no modifications. This contradiction means the description undermines the annotation. Score 1 required per rules.

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: purpose first, then return fields, filter options, mark_read behavior, and an alternative access note. It is slightly lengthy but concise for the amount of information. 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 five optional parameters and no output schema, the description covers return fields, parameter combinations, and usage context. It lacks details on ordering or pagination, but limit is mentioned. The contradiction slightly reduces completeness, but overall it is fairly thorough.

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

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

The input schema covers 100% of parameters, and the description adds meaningful context: explains filter options (e.g., type 'sec_8k', since ISO timestamp), limit range, mark_read side effects, and unread_only. This goes beyond the schema's bare descriptions.

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

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

The description clearly states it 'Pull fired events from your subscription feed', specifying the resource and action. It lists return fields and filtering options. However, it does not explicitly distinguish itself from sibling tools, leaving room for ambiguity.

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

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

The description explains when to use the tool (for recent alerts, polling) and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). It covers parameters like filter and mark_read but lacks explicit guidance on when not to use it or comparisons to specific 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 discloses extensive behavioral details beyond annotations: fans out to multiple data sources (SEC, GDELT/GNews, USPTO), explains the GDELT→GNews fallback, mentions USPTO soft-fail, and describes the return structure. 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 concise (5 sentences) and front-loaded with query examples. It could benefit from slight structuring (e.g., bullet points) but remains highly readable and informative.

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 specifies the return format (grouped changes, total count, citation URIs), covers all sources, fallback behavior, and the parallel call nature. It leaves no important gap.

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

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

Schema coverage is 100%, and the description adds meaningful context for each parameter: type limits to 'company', since explains ISO and relative formats with examples, value specifies ticker or CIK. This goes well 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 provides a change feed for a company over a recent time window, using specific examples that directly map to user queries. It 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 guidance on when to use this tool (temporal updates) and directs users to entity_profile for static profiles. It lacks explicit exclusion cases but covers typical usage 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?

Annotations indicate idempotent, non-destructive write. Description adds key details: key-value scoped by identifier, persistence for authenticated vs anonymous (24-hour retention). No contradictions.

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

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

Four sentences, front-loaded with purpose, no redundant words. Efficient 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?

For a simple key-value write tool with no output schema, the description covers purpose, usage, persistence, and how it integrates with siblings. Sufficient for agent decision-making.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by providing examples of keys (subject_property, target_ticker) and values (findings, addresses), enhancing context 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 saves data for reuse, uses the verb 'save' and resource 'data', and distinguishes from siblings recall and forget by explicitly naming 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?

Provides clear when-to-use guidance with examples ('discover something worth carrying forward'), and mentions pairing with recall and forget, though no explicit when-not-to-use.

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

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

The description goes well beyond the read-only/idempotent annotations by explaining that identifiers are labelled with their source, unresolved identifiers are reported under `unresolved`, and LEI/FIGI enrichment degrades gracefully if external services are unavailable. It also reveals internal cascading through multiple lookup endpoints, providing useful behavioral context.

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

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

The description is longer than average, but every sentence contributes unique information: examples, usage priority, supported types, source labelling, graceful degradation, and the value proposition of replacing manual lookups. It is well-structured and front-loaded with the most relevant usage guidance, earning a high score despite its length.

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

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

With no output schema, the description is responsible for explaining return values, and it does so thoroughly: mentioning source labels, the `unresolved` field, and the specific outputs for drug lookups (RxCUI, ingredient, brand, citation). It also covers both entity types, failure behavior, and when to use the tool, making it self-contained 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?

The input schema already provides 100% coverage, describing both parameters with clear enums and value formats. The description adds marginal value by reinforcing that `value` accepts ticker, CIK, or name for company, and brand or generic for drug, but this mostly duplicates the schema rather than adding new meaning.

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

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

The description starts with concrete example queries and clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID', which differentiates it from sibling tools that may analyze or compare entities rather than resolve 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 says 'Use FIRST whenever you have a name but need an ID' and provides multiple query examples, making the primary use case clear. It does not explicitly state when not to use the tool or name alternatives, but the priority instruction and common-sense context are strong enough to guide correct selection.

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

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

Annotations already provide readOnly, idempotent, and openWorld hints. The description adds value by disclosing the internal process (probes with ai_visibility_check), ranking by score, and output structure (ranked list with score, confidence, signal density). No contradictions.

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

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

The description is three sentences, with the first sentence front-loading the core action and resource. Every sentence adds value, no fluff or redundancy.

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

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

Given the lack of an output schema, the description explains the output format (ranked list with score, confidence, signal density). It also explains the process. Minor omission: it does not mention default model behavior or the need for an API key, but schema covers that.

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

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

Schema coverage is 100% and the schema already describes all parameters adequately. The description adds minimal extra semantic value, only noting that the first entity is treated as the 'subject'. Baseline of 3 is justified.

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, using specific verb 'Compare' and resource 'AI visibility'. It distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' by detailing the internal probing and ranking process.

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 frames the tool as useful for competitive AI-marketing audits and provides a concrete motivating question. It implies when to use (multiple entities comparison) but does not explicitly state when not to use or alternatives, which is a minor 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?

The description adds behavioral traits beyond annotations, such as partial failure handling with timeout details (bundlephobia can take 5-30s), graceful degradation with sources_failed, and the fact that it fans out across multiple sources. 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 not overly verbose; it packs useful information into a few sentences. It is front-loaded with the core purpose and organized logically. A minor reduction in length could improve conciseness, but the structure 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, lack of output schema, and 100% schema coverage, the description provides a complete picture: explains return values (summary block, per-advisory detail, links, alternative versions), handles failure scenarios, and defines ecosystem boundaries. No gaps remain.

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

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

The input schema covers both parameters with descriptions, achieving 100% coverage. The description adds value by clarifying that scoped packages are accepted and that the version defaults to the latest when omitted, enhancing clarity beyond the schema.

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

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

The description states a specific verb+resource ('scan dependency') and clearly defines it as a composite check for npm packages, covering safety, size, and popularity. It distinguishes from sibling tools by specifying ecosystem scope and the underlying external sources (deps.dev, bundlephobia).

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 is provided: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me.' It also explicitly excludes other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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, destructiveHint=false, already indicating safety. The description adds substantial context: output includes character offsets and similarity scores, embedding model (BGE-base-en), windowing (500-char overlapping windows), and a 200K char cap with truncation flagging. 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 but logically organized: action, usage, output, pairing, technical details. Every sentence adds value, though it could be slightly more concise. Front-loaded with the key action.

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

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

Given the tool complexity (3 params, no output schema, good annotations), the description is highly complete. It explains input, output format (passages with offsets and scores), usage context, technical constraints (200K char cap, truncation flagging), and pairing with a sibling tool. No gaps for an AI agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates some schema info (text max 200K chars, query example) but does not add new parameter-specific semantics beyond what the schema already provides. The overall description helps conceptual understanding but not parameter nuances.

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 'Semantic search INSIDE a fetched record,' specifying the verb (search) and resource (fetched record). It distinguishes from siblings by emphasizing it operates on already-fetched text and mentions pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages with offsets). It also provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context such as the account requirement, delivery channel behaviors (webhook auto-disable after 10 failures), and per-type parameter hints. 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 fairly long but well-structured with clear paragraphs for types and delivery channels. It front-loads the primary purpose. Minor redundancy in delivery descriptions 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 seven sibling tools, no output schema, and complex nested objects, the description covers all key aspects: account requirement, type options, delivery channels, constraints. It lacks error handling or rate limit details but is sufficiently complete for subscription creation.

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. However, the description significantly expands parameter meaning with type-specific examples (sec_8k items codes, polymarket_edge topic, fred_series series_id) and delivery constraints (phone verification, webhook HMAC signing). This exceeds the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and types.

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 specifies that a Pipeworx OAuth account is required and that anonymous/BYO cannot persist subscriptions. It details delivery channel constraints (phone verification, 10/day SMS cap) but does not explicitly state when to not use this tool versus alternatives like recent_alerts.

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 detail about output structure (category-bucketed questions with exact tool + argument shape) and how calling with or without argument changes the result. 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 detailed but well-structured, starting with example queries that trigger the tool, then describing behavior and usage. Could be slightly more concise, but earns its length.

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

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

For a simple discovery tool with no output schema, the description explains return shape and purpose completely. Covers triggers, output structure, and usage scenarios.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by listing example focus areas (finance, pharma, etc.) and explaining the behavior when omitted vs. specified, going beyond 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 returns category-bucketed example questions for a newly connected agent, acting as the onboarding entry point. It specifies the verb 'suggest_questions' and distinguishes it from siblings like 'ask_pipeworx' and 'discover_tools'.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the optional topic parameter vs. calling with no arguments. Provides clear context for usage.

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

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

The description reveals that the row is deactivated (not deleted) and historical events remain, adding value beyond annotations. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Three concise sentences with no wasted words, front-loaded with the purpose. Every sentence adds necessary information.

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

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

For a simple tool with one parameter and no output schema, the description covers mutation behavior, ownership, and side effects sufficiently.

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 that the id is returned by subscribe, providing helpful context beyond the schema's 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 'Cancel a subscription by id', using specific verb+resource. It 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?

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), providing clear context for when to use. No alternative tool is named, but the guidance 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses two execution routes, the full verdict set, and crucially explains that could_not_verify means the check did not happen and carries verification_error, warning it must not be treated as evidence. It also clarifies the meaning of unsupported. This is rich, actionable behavioral disclosure with no contradiction to 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 front-loaded with trigger examples and core purpose, then flows into pipeline details, verdicts, and a critical caveat. The example list is slightly redundant and the ending 'Replaces 4–6 sequential calls' is more promotional than necessary, yet overall the structure is logical and every section serves a purpose.

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

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

With no output schema, the description must convey return values and error semantics, and it does thoroughly: verdict vocabulary, actual value with citation, reasoning, plus the two failure modes (could_not_verify and unsupported). For a tool of this complexity, the description is complete enough for an agent to invoke and interpret results 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 detailed descriptions for both claim and tolerance_pct. The description adds context about exact percent-delta math and tolerance being implied by wording, but it does not directly elaborate parameter semantics beyond what the schema already 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 defines the tool as natural-language claim verification against authoritative sources, with specific example query forms. It distinguishes itself from sibling tools by laying out two concrete pipelines (SEC EDGAR/XBRL for company-financial claims and a grounded pipeline for everything else) and by noting it replaces 4–6 sequential calls. This gives a specific verb+resource and clear scope that separates it from generic ask/research tools.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a direct trigger condition. It also segments claim types to clarify which internal path applies. However, it does not explicitly name sibling tools as alternatives or provide exclusions, so it falls short of a 5.

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