Feeds

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

Annotations already cover safety (readOnly, idempotent, etc.), so the description adds value by disclosing the default model is free, that using Anthropic requires a BYO key with direct billing to the user, and that the response includes per-model fields. It also clarifies that _apiKey is passed straight through to api.anthropic.com. This goes beyond the annotations by explaining external calls and cost implications.

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

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

The description is three sentences, front-loaded with the primary purpose, then default/cost info, then return format and use cases. Each sentence earns its place with concrete, non-redundant information. No fluff or repetition of schema/annotations.

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

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

Given no output schema, the description does well by specifying the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' It covers purpose, model selection, key handling, and use cases. However, it does not explain what 'signals' are or how the score is calculated, leaving some ambiguity for a complex external API tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by specifying the default model (Workers AI Llama-3.3-70b), that it is free, and that the _apiKey is only for Anthropic calls with direct charges. This contextualizes the models and _apiKey parameters beyond their schema descriptions.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's function and output. It also mentions the combined view and use cases, which distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description explicitly states when the tool is useful: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for usage. However, it does not explicitly mention alternatives or when not to use it, so it does not fully meet the 'no exclusions/alternatives' bar.

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=false. The description adds valuable context about routing behavior, argument filling, citation URIs, "one fast call", and works on every tier—all consistent with the annotations. 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?

Although long, the description is front-loaded and information-dense. It opens with the key directive "PREFER OVER WEB SEARCH", lists covered domains, gives usage triggers, examples, and alternatives, with each sentence contributing distinct value. No fluff.

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

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

Given there is no output schema, the description fully covers the tool's purpose, scope, usage conditions, alternatives, return format (structured answer with pipeworx:// citations), and performance characteristics. It is a complete self-contained guide for an agent.

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

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

The schema has 100% coverage with all 6 parameters (question plus aliases) fully described. The description adds no new parameter-level details beyond noting that the tool "fills arguments," which is sufficient given complete schema documentation. Baseline 3 is appropriate.

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

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

The description clearly states that ask_pipeworx routes questions to one of 5,462 tools across 1,419 verified sources, fills arguments, and returns structured answers with stable citation URIs. It also distinguishes itself from siblings by positioning as the default entry point and referencing ask_pipeworx_grounded and deep_research for specific 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?

Explicitly instructs to prefer this tool over web search for factual/authoritative questions, provides trigger phrases ("what is", "look up", "find", etc.), and gives clear escalation paths to ask_pipeworx_grounded for grounded answers and deep_research for multi-part broad questions. Includes concrete examples across domains.

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

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds valuable context beyond that: it's a beta with candidate routing improvements, currently no active candidate so it matches ask_pipeworx exactly, and it is a full working router. This explains the experimental nature and current state, going well beyond structured annotations.

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

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

The description is four sentences, each carrying essential information: beta status, identical router features, current state (no active candidate), usage guidance, and reassurance it's fully functional. It is front-loaded and free of 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?

The description is complete for an agent familiar with ask_pipeworx, referencing the same tools, arguments, and response shape. However, it does not explicitly describe the response format, instead relying on the reference to ask_pipeworx. For a complex router with no output schema, this is a minor gap, but the description covers the critical usage and behavioral context.

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

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

All 6 parameters are documented in the schema with descriptions, and all are aliases for the 'question' field. The description mentions 'same arguments' as ask_pipeworx but adds no additional parameter semantics beyond the schema. With schema description coverage at 100%, the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router over 5,462 tools with identical arguments and response shape. It distinguishes itself from siblings by framing this as the experimental edge, and the name and context make the 'ask' verb implicit. This is specific enough for an agent to know what the tool does.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains results are compared against the stable router to decide merges, and clarifies it is a full working router, not a fallback. This provides clear guidance without confusion.

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, idempotent, non-destructive. The description adds significant context: it costs an extra LLM call, it returns a structured result with evidence and refusal reasons, and it explicitly refuses when the data doesn't directly answer. It also clarifies the grounded extraction behavior, which is 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 dense but every sentence earns its place: purpose, mechanism, output format, refusal reasons, use cases, and cost comparison. It's front-loaded with the core value proposition and maintains clarity 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 fully specifies the return shape and refusal contract. It covers safety, cost, use cases, and differentiates from the main sibling. This is a complete and self-sufficient description.

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%: all six parameters are documented as aliases for the question string. The description doesn't add parameter-specific detail beyond what the schema provides, and the baseline for high coverage applies. No additional semantics needed.

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

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

The description opens with a clear purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the mechanism (routes through tools, fetches data, extracts answer from tool result) and explicitly distinguishes from the sibling ask_pipeworx by noting the same routing but an extra LLM call. This gives a specific verb+resource+scope with sibling differentiation.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also provides an exclusion: 'prefer ask_pipeworx for casual lookups' and mentions the cost tradeoff. This is textbook when/when-not guidance.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds extensive behavioral detail: parallel fan-out, resolver contract with market_match_confidence, parent_event extraction, news fallback fields, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread warnings, and cancellation-rule risk. This far exceeds what annotations convey.

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

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

The description is long but every section carries unique, actionable information (resolver contract, safety, cancellation risk). It is well-structured with clear headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It loses a point because the length may be overwhelming for quick scanning, though it remains efficient given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values and does so comprehensively: result.market fields, analysis fields with edge warning, evidence keying, resolver fields, parent_event, news fallback metadata, and status codes. It also covers edge cases like closed markets and cancellation rules, making the tool's behavior fully predictable.

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

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

The schema covers 100% of parameters, but the description enriches meaning substantially: it explains accepted forms for 'market' (slug, URL, question text), depth defaults and behavior ('quick = 2-3 evidence sources, thorough = full fan-out'), and include_raw's response-size tradeoff. It also gives concrete examples that clarify expected inputs.

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+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings by focusing on Polymarket bet resolution and fan-out, and provides explicit use cases ('should I bet on X', 'what does the data say about Y').

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

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

The description gives clear usage context: 'Use for "should I bet on X"...' and details fan-out scenarios. It does not explicitly name alternative tools or state when not to use it, but the guidance is strong enough to infer appropriate invocation. A slight gap is the absence of explicit exclusions compared to sibling tools like polymarket_edges.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it pulls LATEST 10-K data, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with pipeworx:// citation URIs. This goes beyond the annotations and helps set expectations.

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

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

The description is front-loaded with trigger examples and structured with clear sections for type-specific behavior. Every sentence adds value: usage guidance, data sources, edge-case handling, sorting, and output format. Despite its length, there is no redundancy or filler.

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

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

Given there is no output schema, the description compensates by explaining the return value (paired data + citation URIs) and sorting behavior. It covers both entity types (company and drug) with specific data sources, and addresses edge cases like off-calendar fiscal years. The tool is fully specified for its purpose.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: for type='company' it details the exact financial metrics (revenue, net income, cash, long-term debt) and for type='drug' it details FAERS counts, FDA approvals, and trial counts. It also gives concrete examples for values (e.g., tickers, drug names), enhancing 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 performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific examples of triggering phrases. It clearly distinguishes itself from sequential single-pack lookups, which is a different behavior than 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?

It provides clear when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists common comparison phrases. It also differentiates behavior by type (company vs drug) and explicitly says it replaces 8–15 sequential lookups, implying 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?

The description discloses far more than annotations: auth requirement (free tier vs paid thorough), exact output schema (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), depth-level behavioral differences, timing (15-60s, up to ~90s), and semantic excerpting behavior. It also explicitly states 'never invented,' covering a key trust concern. Annotations already provide readOnly/openWorld/idempotent/destructive hints, and the description adds complementary operational detail 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 long (~350 words) but every clause carries operational info: auth, fallback, mechanism, output packet, usage boundaries, depth iterations, citation guarantees, and latency. No filler or repetition (the only near-repeat is 'NOT open-web' being stated once). It's dense and front-loaded with the most critical constraints, though it could be tightened slightly by moving some detail into the schema.

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 fully specifies return values and edge cases: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, explicit gaps[], contradictions[], hop field, and conditional citation_uri presence. It also covers prerequisites (account), alternatives (ask_pipeworx), and performance expectations. For a complex multi-hop research tool, this is exceptionally complete.

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

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

Schema description coverage is 100%, with both `question` and `depth` fully documented (including facet counts and paid requirement for thorough). The description adds little beyond the schema—it reinforces depth behavior and auth constraints but doesn't introduce new parameter-level semantics. Per baseline, a 3 is appropriate when schema fully covers parameters.

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

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

The description opens with a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in a single call, and explicitly contrasts with siblings: 'For a single lookup use ask_pipeworx' and 'prefer ask_pipeworx' for news. It also states 'this is NOT open-web search,' distinguishing from generic search tools. The specificity of decomposition and routing to 5,462 tools leaves no ambiguity about the tool's unique role.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and when-not-to: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also provides a fallback: 'If you are not signed in, use ask_pipeworx instead.' These are direct, actionable alternatives, not vague hints.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, and full input schemas, "ready to call directly, no second schema lookup needed." This goes beyond the annotations by explaining the output format and immediate usability, without contradicting any hints.

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

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

The description is four sentences, each serving a purpose: state purpose, list domains, explain output, and give strategic guidance. It is slightly verbose with the long domain list, but that list is informative. No fluff, though the length could be trimmed without losing value.

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

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

Given the tool's simplicity (1 required parameter, no output schema), the description is comprehensive: it covers what it does, when to use it, what it returns (top-N tools with schemas), and how to use it (call first). The absence of an output schema is compensated by describing the result contents and direct callability.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a bit of context by mentioning "top-N" which aligns with the 'limit' parameter, but it does not provide any parameter-specific details beyond what the schema already contains. The schema already explains the query parameter with examples and aliases.

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

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

The description clearly states the tool's function: "Find tools by describing the data or task." It uses specific verbs (browse, search, look up, discover) and a clear resource (tools), distinguishing it from sibling tools that perform specific tasks like research or analysis. The list of domains (SEC filings, financials, FDA drugs, etc.) further clarifies scope.

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

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

Explicitly states when to use: "Use when you need to browse, search, look up, or discover what tools exist" and "Call this FIRST when you have many tools available and want to see the option set (not just one answer)." This provides clear context and implies not to use when you already know the specific tool or need a single answer, effectively differentiating from 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 readOnly and non-destructive behavior; the description adds meaningful context not in annotations: fan-out across sources, soft-fail for patents API sunset, and the one-call parallel nature. It does not contradict annotations.

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

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

The description is fairly long but every sentence carries useful information: examples, sources, output fields, failure modes, and input constraints. It is front-loaded with usage examples and ends with important exclusions. Slightly dense but justified.

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 multi-source aggregator with no output schema, the description thoroughly covers return data (filings, fundamentals, patents, news, LEI), source names, and fallback behavior. It gives the agent enough to set expectations and handle limitations.

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

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

Schema coverage is 100% and both parameters are well-documented in the schema (type enum, value format). The description repeats some of this but adds the zero-padding example and the resolve_entity fallback. However, it does not significantly extend beyond the schema's existing semantics.

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

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

The description clearly states the tool's purpose: generating a full cross-source profile of a US public company. It uses specific verb phrases like "tell me about" and "brief me on" and lists concrete outputs (cik, filings, fundamentals, patents, news, LEI), making it distinct from sibling tools like resolve_entity or compare_entities.

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 instructs when to prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and when not to use it (names not supported, use resolve_entity first). This provides clear decision guidance relative to 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 already convey destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds useful context about clearing sensitive data, but does not disclose any additional behavioral traits such as what happens when the key doesn't exist or whether deletion is permanent. With annotations covering the core behavior, a score of 3 is appropriate.

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

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

The description is three sentences, front-loaded with the primary action and resource, then usage guidance. Every sentence is informative and there is 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?

For a simple one-parameter tool with no output schema and comprehensive annotations, the description fully covers purpose, usage scenarios, and pairing with related tools. Nothing essential is missing.

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

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

The schema describes the key parameter as 'Memory key to delete' with 100% coverage. The tool description adds no extra meaning beyond 'by key,' so the schema carries the semantic weight. Baseline 3 is applicable given high schema coverage.

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

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

The description clearly states the action (Delete), the resource (previously stored memory), and the method (by key). It distinguishes itself from sibling tools like remember and recall by specifying deletion, making the purpose unambiguous.

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

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

The description provides explicit when-to-use scenarios: context is stale, task is done, or clearing sensitive data. It also advises pairing with remember and recall, offering actionable guidance on how this tool fits into a workflow, which is more than sufficient for such a simple tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral detail: fetches the page, extracts title/description/key links, and emits markdown. This goes beyond annotations to explain the internal process, though it doesn't mention network limitations or error handling.

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

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

Two sentences, front-loaded with the core purpose. The first sentence gives the action, target, and output format; the second lists concrete use cases. No filler.

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

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

The tool is simple (2 params, no output schema), and the description fully explains the output ('single text blob ready to drop at site-root/llms.txt') and the process. It covers what an agent needs to know to invoke and interpret results, making it 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?

The input schema describes both parameters with 100% coverage, so the baseline is 3. The description adds minimal parameter-specific information beyond the schema, only indirectly referencing 'key links' which maps to max_links. No contradictions.

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

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

States exactly what it does: generate a llms.txt file from a URL, specifying the output format and steps. The description clearly distinguishes it from sibling tools, which are mostly research/betting tools. The verb 'generate' and resource 'llms.txt' are specific.

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 use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), which tell the agent when to use it. It doesn't mention when-not-to-use or alternative tools, but given the unique functionality among siblings, this is acceptable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that this lists the caller's own subscriptions and that only active ones are returned by default, which is a behavioral nuance not captured in annotations. It also enumerates the returned 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?

Three succinct sentences cover the action, the output fields, and the intended usage. Each sentence contributes meaningful information with no redundancy or filler.

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

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

For a read-only list operation with one optional parameter and no output schema, the description adequately covers the scope, the returned data fields, and the use case. It is sufficiently complete for an agent to understand what the tool does and how to invoke it.

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 fully describes the single parameter include_inactive with 100% coverage. The description adds no extra parameter information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List the caller's active subscriptions') with a specific verb and resource, and further clarifies the scope ('active') and the returned fields. This distinguishes the tool from sibling subscribe/unsubscribe operations by focusing on the list/read activity.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It tells the user when to invoke the tool, though it does not name alternative tools or explicitly state when not to use it.

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

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

Annotations provide no hints (all false), so the description carries the full transparency burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), cost implications ('Free; doesn't count against your tool-call quota'), human review cadence ('team reads digests daily'), impact on roadmap, and content constraints (don't paste end-user prompts). This goes well beyond basic expectations and gives the agent practical knowledge about side effects.

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

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

The description is about 150 words and packs a lot of essential context. It is front-loaded with the core purpose and then covers usage, exclusions, and constraints. While not ultra-brief, every sentence adds value—there is no fluff or repetition. It is well-structured for quick parsing.

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

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

The tool has only 3 params, one nested object, and no output schema. The description covers all operational aspects: what to report, when to use it, what not to do, rate limits, quota, and feedback processing. Nothing critical is missing for an agent to invoke this tool correctly and set expectations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining how to fill the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by tying the type parameter to real-world scenarios. It doesn't document each parameter individually, but the schema already does that thoroughly, so this is 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 clear, specific verb phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' immediately identifying the tool as a feedback channel. It explicitly enumerates the types of feedback (bug, feature, praise), distinguishing it from sibling tools like ask_pipeworx or discover_tools, which serve different purposes.

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 with concrete scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion—other MCP servers—and directs users to file with that server instead, plus a tie-breaker ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it is 'Self-aggregating signal derived from CF analytics-engine, no PII, just (pack, tool, count)' and mentions caching (5min-1h). This goes beyond the annotations and informs the agent about data freshness and privacy.

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 main purpose. The 'Useful for' list and the data source note are concise and relevant, though the description is slightly longer than strictly necessary. Each sentence earns its place, so it is appropriately sized.

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 optional parameter and no output schema, the description is complete. It explains what is returned (top tools, top packs, total call volume), the time windows, use cases, and data source/caching behavior. No important aspect is missing.

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

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

The input schema has 100% coverage for the single 'window' parameter, including its enum values and behavior ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description does not add extra parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and lists specific outputs (top tools, top packs, total call volume). This is a specific verb+resource+scope that distinguishes it from sibling tools like discover_tools or recent_alerts.

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

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

The description provides a 'Useful for' list with three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment). This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name 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=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these: it explains the partition filter behavior (dropping placeholder slugs, returning null for >20% placeholder fraction), the fill check with realizable vs theoretical edge, and critical trading guidance ('realizable_edge_pp ≤ 0... do not trade it'). It also mentions skipped_low_similarity to surface rejected pairs. This is rich behavioral disclosure with no contradiction.

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

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

The description is lengthy but highly structured, with explicit sections like SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK. It front-loads the most important information (call with no args for trending scan) and uses bold labels for critical caveats. While not terse, every sentence adds value for a complex tool with two modes and safety checks. It could be condensed slightly, but the structure makes it scannable.

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?

There is no output schema, so the description fully carries the burden of explaining return values. It lists the response structure (opportunities[], partition_check fields), describes the fill check behavior, and explains the significance of values like 'sum_yes_prices' and 'gap_from_1'. Given the tool's complexity (two modes, edge cases, trading signals), the description is complete enough for an agent to know what to expect.

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

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

Although schema coverage is 100% with descriptions for both event and topic, the tool description adds significant meaning beyond the schema. It explains what an event slug looks like ('fed-decision-may-2026'), how topic is used as a seed question for cross-event scanning, and clarifies the semantics of the two modes. The schema only says 'Single-event mode' and 'Cross-event mode,' but the description elaborates on the partition check, comparator, and output behavior tied to these parameters.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's niche from siblings like polymarket_edges (which likely focuses on straightforward edge detection) and polymarket_fill_risk (which handles execution risk). It names distinct modes (trending_scan, event, topic) with concrete examples, leaving no ambiguity about what the tool does.

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 usage guidance: '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 explains when to use each mode, provides examples of event slugs and seed questions, and even directs users to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This exceeds what is expected and helps an agent choose correctly.

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?

Despite having strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds substantial behavioral context: 1h KV-level caching, response top-level structure with diagnostics so callers can see why segments are empty, including caveats about the Fed signal unreliability and a 24h-move warning when the edge may already be priced in. This goes far beyond the annotations and does not contradict them.

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

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

The description is a single, dense paragraph with extensive jargon and detail (model formulas, per-sport alpha values, gate thresholds). While every sentence carries information, the lack of any segmentation, bullets, or a brief summary makes it difficult to parse. It is over-specified and not appropriately sized for agent consumption.

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

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

With no output schema, the description fully compensates by detailing the response structure (by_segment, fed_candidates, _diagnostics), explaining why segments might be empty, and describing the output fields (edge_pp_net, kelly_fraction, liquidity, spread_pp). Given the tool's complexity (9 parameters, three model families), this description is exceptionally complete and gives an agent everything needed to understand what it will receive.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The tool description adds extra semantic value by explaining the interplay between knobs (e.g., why min_partition_leg_kelly exists because min_kelly doesn't filter partitions, and how slippage/subtracts from raw edge). This clarifies parameter intent beyond the schema's individual 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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further differentiates itself from siblings by enumerating three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and stating its intended use case ('what should I bet on today'). This goes beyond a generic statement and clearly identifies the tool's unique value.

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 an implicit use case ('Built for "what should I bet on today"') and explains why Fed bets are excluded from ranking, but it does not explicitly say when to use this tool versus sibling tools like polymarket_arbitrage, polymarket_edge_tracker, or polymarket_fill_risk. There is no mention of alternatives or exclusion criteria for tool selection, leaving the agent to infer the appropriate 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?

Beyond the readOnlyHint and other annotations, the description discloses critical behavioral traits: history is bounded by a 60-day TTL, snapshots are written on cache-miss so gaps mean no scan, decay is computed from daily closes of edge_pp_net, and the sign convention (negative = SELL YES). This provides deep insight that annotations alone don't 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 long but well-structured: purpose, args, response, and limits are clearly separated. The key idea is front-loaded, and every sentence adds value, explaining response semantics and data caveats. 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?

With no output schema, the description fully explains return values: tracked[], expired[], and snapshot_dates[] with all subfields, plus limits and parameter behavior. It covers the tool's behavior comprehensively, making it complete for an agent to use correctly.

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

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

The schema fully documents both parameters (100% coverage), so the baseline is 3. The description adds context by calling window a 'snapshot family' and explicitly linking days to lookback with a max of 30, reinforcing the tool's data model and confirming defaults from 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: it tracks edge persistence and decay from daily polymarket_edges snapshots. It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series rather than current edge values.

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

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

The description provides clear context for when to use this tool: when assessing whether an edge is fresh or stale/decaying, with the analogy about fresh vs 3-week-old edges. It doesn't explicitly name alternative tools or exclusions, but the 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 cover read-only/idempotent/non-destructive, but the description adds substantial operational detail: walks the ladder, returns top_of_book/vwap/slippage/shares_filled, and warns about partial basket fills causing unhedged directional positions. This goes far beyond the annotations.

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

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

Though lengthy, the description is structured with SINGLE-MARKET/BASKET sections and front-loaded with the core purpose. Every sentence conveys necessary operational or risk information; no filler.

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

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

No output schema, yet the description enumerates exact return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, thin_legs, etc.). It covers prerequisites, defaults, risks, and integration points with sibling tools.

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

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

Schema coverage is 100%, but description adds mode-specific interpretations: side defaults, size_usd semantics (max spend vs target proceeds vs settlement notional), and the clamp range. It clarifies the distinction between market and event parameters 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth' – a specific verb (check) plus resource (CLOB order-book depth). It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on fill-risk validation versus theoretical edge.

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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also clarifies the two modes (market/event) and when each applies.

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

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

The description richly details behavioral traits beyond the readOnly/idempotent annotations: it discloses compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the mathematical meaningfulness of spreads given misalignment. This fully informs the agent of edge cases and output caveats.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose, and every sentence adds essential detail for a complex tool. Slightly verbose, but each word contributes, earning it a strong score.

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

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

Given the absence of an output schema, the description compensates by thoroughly explaining the response structure: leg-by-leg prices, matched spreads in percentage points, compatibility warnings, temporal alignment, and skip counters. It also includes interpretation guidance, making the tool's behavior fully predictable.

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?

While the schema provides a 100% coverage of parameter names and basic descriptions, the tool description adds critical semantics about the two modes, how explicit tickers override topic-mapped events, and the meaning of custom pairings. This goes far beyond schema details, making the parameter usage clear.

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 opening sentence, 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' uses a specific verb+resource construction that precisely defines the tool's function. It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison of equivalent outcomes.

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 two usage modes (topic shortcuts vs. explicit tickers) and provides explicit when-to-use/when-not-to-use guidance: spreads are only meaningful when bet shapes are equivalent and temporally aligned, and it warns that pre-mapped topics are not necessarily tradeable. However, it does not explicitly mention alternative sibling tools, only contextualizing this tool's uniqueness.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable context beyond annotations: scoping to 'anonymous IP, BYO key hash, or account ID', the behavior when key is omitted (list all), and the relationship to remember/forget. No contradictions.

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

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

Three concise sentences, front-loaded with the core action, followed by use-case examples and scoping. Every sentence earns its place with no redundancy.

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

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

For a simple memory tool with one optional parameter and strong annotations, the description fully covers purpose, usage context, scope, and sibling relationships. It is complete enough for an agent to select and invoke correctly.

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

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

The schema covers 100% of parameter details (one optional 'key' with description). The description reiterates the omit-to-list behavior but adds no additional parameter-specific meaning beyond the schema's own 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 opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings by explicitly pairing with remember (save) and forget (delete), and contrasts with other tools by focusing on stored context rather than derivation.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It names alternatives (remember, forget) and the scoping identifier, making it clear when this tool should be selected over others.

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 contradicts the annotations. The annotations declare readOnlyHint=true, implying no state changes, but the description explicitly says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a mutation of persisted feed state. This is a serious inconsistency, so the score is 1.

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

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

The description is well-structured with the primary purpose front-loaded. It packs useful details (returned fields, filtering, mark_read effect, polling suitability, and an external feed URL) without excessive verbosity. Only minor redundancy exists (e.g., 'since (ISO timestamp)' echoes the schema), but overall it 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?

Given 5 parameters, no output schema, and annotations, the description covers the essential aspects: return content, filtering, read-tracking behavior, and an alternative access endpoint. It doesn't explicitly describe the limit parameter or unread_only, but these are adequately documented in the schema, so the description is functionally complete for an agent. The annotation contradiction is a separate issue.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, particularly for mark_read, explaining that after marking read, subsequent calls only show newer events. It also reinforces the since parameter with an ISO timestamp example. This extra behavioral detail 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's function: 'Pull fired events from your subscription feed. Returns the most recent alerts...' This is a specific verb+resource combination that distinguishes it from siblings like recent_changes and list_subscriptions. It also describes the return content (source, citation_uri, raw payload) and filtering options.

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

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

The description provides clear context for when to use the tool (polling alerts, filtering by type/since, marking read) and even mentions an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly exclude other tools or compare with sibling tools, 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.

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

Beyond the read-only/idempotent/honest annotations, the description discloses important behavioral details: it fans out to SEC EDGAR, uses a GDELT→GNews fallback with specific failure triggers, notes the USPTO PatentsView API sunset causing soft-fail, and describes the exact return structure (changes[], total_changes, pipeworx:// URIs). No contradiction with annotations exists.

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

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

The description is dense but front-loaded with the most important context (purpose and source fan-out) before details on parameter formats and return shape. It is longer than necessary, but every sentence carries meaningful information, including fallback behavior and sibling differentiation.

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

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

For a tool with no output schema, the description covers the key contextual needs: input formats, data sources, fallback logic, failure modes, return shape, and the relationship to entity_profile. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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

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

Input schema already documents all three parameters with 100% coverage. The description adds practical guidance: `since` accepts ISO or relative shorthand, '30d' or '1m' is recommended for typical monitoring, and `value` can be a ticker or zero-padded CIK. This exceeds the baseline by providing usage examples and format clarifications.

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 concrete natural-language queries then states the core purpose: a change feed for a company over a window. It explicitly identifies the resource (company changes) and the verb (list/return), and distinguishes itself from the sibling tool entity_profile by noting when to use that instead.

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

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

The description gives clear usage context via example queries ('What's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This satisfies both when-to-use and when-not-to-use guidance.

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

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

Adds valuable context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This clarifies behavior that annotations (readOnlyHint, idempotentHint, destructiveHint) do not cover, such as session-dependent retention.

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

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

Three sentences deliver all essential info: purpose, usage context, scoping, retention, and sibling relationships. It is front-loaded with the action and resource, with no filler 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?

For a simple two-parameter write tool with no output schema, the description covers everything needed: what to store, when to use it, how long it persists, and how to retrieve/delete. 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 description coverage is 100%, so the schema already documents both key and value with examples. The description reinforces the key-value pattern but does not add new parameter-level details; 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes this tool from siblings by naming reciprocal tools (recall, forget) and giving concrete examples (ticker, address, preference), making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' and lists examples. It also differentiates from alternatives by saying 'Pair with recall to retrieve later, forget to delete,' which tells the agent exactly how it fits into the workflow.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: internal cascading through multiple endpoints, auto-disambiguation, and specific citation URI formats for each entity type. 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: it opens with realistic user queries, states the core purpose, gives usage guidance, and then details supported types. Every sentence adds value, and the length is justified by the tool's complexity.

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

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

Despite having no output schema, the description fully explains what each type returns (ticker, CIK, RxCUI, etc.) and includes citation URIs. It covers both supported entity types, input variations, and the tool's ability to replace multiple manual lookups. No significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter semantics by providing examples for 'value' (e.g., 'AAPL', '0000320193', 'ozempic'), explaining auto-disambiguation, and detailing the output structure for each type. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier required by other tools. It provides concrete examples of user queries and distinguishes this tool from siblings by emphasizing that it supplies the IDs other tools need as input.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It also notes that using resolve_entity replaces 2-3 manual lookups, giving clear when-to-use context. Supported types and input variants are listed, making it easy to choose this tool over 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?

The description goes beyond the annotations by disclosing that it probes each entity via ai_visibility_check, ranks results by score, and returns a ranked list with score, confidence, and signal density. This adds meaningful behavioral context beyond the read-only/idempotent hints and does not contradict the annotations.

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

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

The description is four sentences, front-loaded with the main action, includes a concrete example, and has no redundant filler. Every sentence earns its place, making it concise and well-structured.

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

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

Since there is no output schema, the description adequately explains the return value (ranked list with score, confidence, signal density). It also covers the tool's behavior, use case, and relationship to ai_visibility_check. The combination of schema and description gives an agent sufficient information to 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?

The input schema has 100% parameter coverage, so the baseline is 3. The description does not add any new parameter semantics beyond what the schema already provides—it only restates the entities concept in narrative form.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, with specific verbs and a defined resource. It distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison and explicitly mentions probing each entity with ai_visibility_check.

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 a clear use case for competitive AI-marketing audits with a concrete example question ('does Claude know about us as well as our competitors?'). It implies ai_visibility_check for single-entity checks but does not explicitly state when-not to use this tool versus alternatives, 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.

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

Annotations already declare readOnly and idempotent, and the description adds substantial behavioral context: the composite fan-out across deps.dev and bundlephobia, partial failure degradation, and a 5-30s latency for first measurement. This goes beyond the annotation hints, providing useful expectations for the agent.

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

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

The description is detailed but front-loaded with the main purpose and usage. Each sentence adds value (outputs, alternatives, failure behavior), though it is longer than strictly necessary. The structure is logical and easy to scan.

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 defines the return structure explicitly (summary block, per-advisory detail, links, alternative versions). It also covers constraints (NPM only), timing, and failure handling, making it fully self-contained for a complex tool.

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

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

Schema coverage is 100% with descriptions for both 'package' and 'version'. The description adds no new parameter semantics beyond the schema, only reiterating the npm ecosystem scope. With full schema coverage, the baseline of 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 the tool's function as a composite check for npm packages, with specific verbs ('fans out', 'returns') and scope ('should I add this npm package'). It distinguishes from sibling tools by focusing specifically on npm package evaluation via deps.dev and 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?

Provides explicit usage guidance ('Use whenever an agent asks...') and names alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This makes the decision to use this tool versus alternatives 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 mark it read-only and idempotent; the description adds non-obvious behavior: BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, 200K char cap with truncation flagging, and per-passage offsets for verification. 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?

Every sentence earns its place: purpose, input semantics, usage trigger, sibling relationship, and algorithm/limits. It is front-loaded with the core action and remains tight for the amount of behavioral detail conveyed.

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

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

With no output schema, the description fully covers return values (top-N passages, offsets, similarity scores), the truncation edge case, and the workflow with ask_pipeworx_grounded. This is sufficient for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mostly restates parameter meaning with examples (text as 'already pulled' record, query as natural-language ask), but does not materially extend what the schema already provides.

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

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

Description opens with 'Semantic search INSIDE a fetched record' — a specific verb, resource, and scope. It immediately distinguishes itself from sibling grounding tools by framing it as a search over already-fetched text, and the 'top-N passages with character offsets and similarity scores' clarifies the exact output.

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 states precisely when to use: 'Use when the record is too big to cram into the prompt.' It also names the related sibling 'ask_pipeworx_grounded' and explains the pairing workflow, giving the agent explicit context for choosing this tool over 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 provide read/write/destructive/idempotent hints. The description adds concrete behavioral traits beyond that: account requirements (anonymous/BYO cannot persist), the always-on feed channel, email/SMS constraints (phone verification, 10/day cap), and return value. This is rich, useful 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 front-loaded with the main purpose and condenses a lot of specifics into a few sentences. It is not overly verbose, though some redundancy exists with the schema's parameter details (e.g., the type examples are repeated). Overall it is well-structured and efficient.

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

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

Given the tool's complexity (nested delivery object, multiple types, optional channels), the description is thorough: it covers auth, supported types with examples, delivery options, return value, and SMS constraints. No output schema exists but the return value is stated. The description is complete enough for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value with examples like `items:["5.02"]` meaning officer change and topic 'fed' for polymarket_edge, and it also mentions the always-on feed channel not present in the schema. This goes beyond the schema's already detailed 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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the subscription id. This clearly distinguishes it from sibling tools like list_subscriptions or recent_alerts, and the supported type examples further disambiguate.

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

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

The description gives clear context for use: proactive monitoring of live data, requires a Pipeworx OAuth account, and includes specific subscription types. It does not explicitly mention alternatives or when not to use it, but the context is strong enough to guide 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 declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return content (category-bucketed example questions with exact tool+argument shapes) and the live catalog source, going beyond what annotations convey.

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

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

The description is front-loaded with natural-language queries ('What can I ask Pipeworx?') and structured logically, but it is somewhat lengthy. It packs many clauses into the first sentence, yet each clause contributes to understanding the tool's role.

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 optional parameter and no output schema, the description is complete: it explains the tool's purpose, output categories, usage with and without `topic`, and when to use it. All essential context is present.

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

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

The schema covers the `topic` parameter fully with its own description and enum list. The tool description echoes this by saying 'pass `topic` (e.g. "finance", "pharma", "betting")', adding only redundancy and no new semantic information, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it suggests questions to ask Pipeworx, returning category-bucketed example questions with tool+argument shapes. It explicitly positions itself as the onboarding entry point, distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It also explains how to call it: 'Call with no arguments for the full spread, or pass `topic` to focus.'

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

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

The description discloses that the operation is ownership-restricted and only deactivates rather than deletes the row, preserving history via recent_alerts. This adds value beyond the annotations' idempotentHint and destructiveHint, since it explains the actual mechanism and side effects.

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

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

Three sentences, all informative: purpose, restriction, and post-effect. No redundancy or filler.

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

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

For a single-parameter mutation with a clear idempotency hint, the description covers all essential aspects: what it does, who can use it, and what happens to data. It even points to the relevant sibling for historical views.

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

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

The schema already provides full coverage of the sole 'id' parameter, describing it as a subscription uuid returned by subscribe. The description's mention of 'by id' adds no additional semantic detail beyond what the schema states, so the baseline of 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 states the effective verb 'Cancel' with a specific resource 'subscription' and the method 'by id'. It clearly 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?

The description implicitly defines the usage context: cancel a subscription you own. It provides an exclusion—only your own—and points to recent_alerts as an alternative for viewing historical events after cancellation. However, it does not explicitly contrast with unsubscribing from other alert types or mention when not to use it.

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

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

Annotations already declare the tool as read-only, non-destructive, idempotent, and open-world. The description adds valuable behavioral context beyond annotations: source routing, evidence citation, verdict categories, and tolerance semantics. No contradictions exist, but it does not disclose any error conditions or rate limits, so it's a 4 rather than a 5.

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

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

The description is long but each sentence earns its place: natural-language trigger examples, routing logic, return value specification, and workflow replacement rationale. It is front-loaded with the core purpose and examples, but could be trimmed slightly for an AI agent reading speed, so a 4.

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

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

Despite having no output schema, the description fully explains the return contract: verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), the actual value with pipeworx:// citation, and reasoning. It covers both financial and non-financial claim paths, making it complete for the tool's complexity.

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

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

Input schema covers both parameters with 100% coverage, so baseline is 3. The description goes beyond by explaining that tolerance_pct overrides the wording-implied tolerance, caps the default at 5%, and suggests 1–2% for hallucination detection. This adds practical semantic meaning not present in the schema.

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

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

Specifies a clear verb+object ('validate claim') with a detailed description of natural-language fact-checking against authoritative sources. It distinguishes itself from sibling research/comparison tools by centering on verification and returning a verdict, so an agent knows exactly what this tool accomplishes.

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

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

Explicitly states when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and further refines with two routing paths: company-financial claims via SEC EDGAR/XBRL, all other claims via the grounded pipeline. It also notes the tool replaces 4–6 sequential calls, which is strong guidance for selection.

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