Statscan

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

Annotations already declare readOnly, openWorld, and idempotent hints, and the description adds valuable context beyond that: cost implications (free default vs. BYO Anthropic key with direct payment), auth requirements (passing `_apiKey`), and the per-model output structure. This is exactly the kind of behavioral disclosure the rubric credits.

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, each earning its place: the first states the core action and output, the second explains model defaults and key handling, and the third lists use cases. It is front-loaded with the main purpose and contains no redundancy or unnecessary detail.

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 specifies the return shape (per-model score, confidence, signals, raw_response plus combined view), explains optional parameters, and covers realistic use cases. It is complete for a tool of this complexity, leaving no major ambiguity.

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 description goes beyond by clarifying parameter behavior: 'workers-ai' is the free default, 'anthropic' requires `_apiKey`, which is 'passed straight through to api.anthropic.com.' This adds meaningful context to how the parameters interact, justifying 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 purpose: probing one or more LLMs for knowledge about a business/brand/product/topic and scoring visibility on a 0-100 scale. This specific verb+resource combination distinguishes it from sibling Q&A tools like ask_pipeworx or deep_research, which focus on different output types.

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

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

The description provides clear context for when to use the tool: 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model (free) versus optional Anthropic with a BYO key. However, it does not explicitly state when not to use it or name alternative 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description adds valuable behavioral context beyond annotations: the routing mechanism across 5,564 tools, the filling of arguments, stable citation URIs, and performance characteristics ('one fast call', 'works on every tier'). This enriches the agent's understanding of what happens internally.

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

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

The description is long but front-loaded with the critical 'PREFER OVER WEB SEARCH' and 'START HERE' directives, then covers the scope, behavior, usage triggers, examples, and alternatives in a logical order. While it is dense and could be slightly trimmed, every sentence contributes to decision-making, making it appropriately sized for such a broad default tool.

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, the description is remarkably complete: it covers the tool's role as a default entry point, the breadth of data sources, return format (structured answer with citation URIs), and when to escalate to sibling tools. The simple schema and strong annotations mean the description doesn't need to explain return values or safety further, so no critical context 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?

Schema description coverage is 100% (all six parameters are aliases for question). The description adds meaning by explaining what kinds of questions are appropriate ('what is', 'look up', 'find', 'get the latest', etc.) and provides concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'. This goes beyond the schema's bare 'Your question or request in natural language'.

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

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

The description explicitly states the tool's function: 'Routes the question to the right one of 5,564 tools across 1462 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings by framing itself as the default entry point and referencing ask_pipeworx_grounded and deep_research for specialized 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?

Provides explicit triggers: 'Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current"' and lists domains like SEC filings, FDA data, FRED/BLS stats, etc. It also gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers with verbatim evidence, and deep_research for broad/multi-part questions, plus handling of breaking news.

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 safe, read-only, idempotent behavior, so the description adds value by explaining that this is a full working router (not a stub) and that it may have live candidate routing improvements. This gives behavioral context beyond the annotations, though it doesn't detail response shape 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?

The description is concise (about four sentences) and front-loads the core purpose. Every sentence adds value: beta status, current equivalence to stable, usage recommendation, and confirmation it's a full router. 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?

For a single-question router, the description covers the essential context: what it is (beta), current state (matches stable), usage intent (newest routing), and that it's fully functional. The 'same response shape' reference addresses the lack of an output schema, and the param schema is complete. No critical 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 description coverage is 100%, with all six parameters (aliases) documented. The description does not add new parameter meaning beyond what the schema already provides—it simply reiterates the same arguments. The baseline of 3 is appropriate given the schema fully covers the parameters.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same tools and arguments. It distinguishes from siblings (ask_pipeworx, ask_pipeworx_grounded) by highlighting the beta status and candidate routing improvements, making the purpose specific and unambiguous.

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

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

Explicitly states to use exactly like ask_pipeworx when you want the newest routing, and mentions that results are compared to the stable router. It also clarifies that it currently matches ask_pipeworx exactly, giving clear context on when to choose this tool over its stable counterpart.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive. Description adds valuable behavioral detail beyond annotations: exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), explicit refusal reasons, one extra LLM call cost, and verbatim quote evidence. No contradiction with annotations.

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

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

The description is longer than typical but every sentence adds unique value: mode definition, mechanism, return format, refusal format, usage guidance, and cost/alternative tradeoff. It is front-loaded with the core purpose. Slightly dense but well-organized.

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

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

There is no output schema, so the description correctly covers return values in detail, including both success and refusal shapes with specific refusal_reason enums. It also covers cost implications, use cases, and alternative tools. For a complex tool with routing and grounded extraction, this is 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% — all six parameters are aliases for 'question' and are fully described in the schema. The description does not add parameter-specific semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes from the sibling tool ask_pipeworx by noting 'Same routing as ask_pipeworx' but with grounded extraction. The verb+resource is specific: it answers questions using only tool results.

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'. Also gives when-not-to-use and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds a wealth of behavioral detail: the resolver contract with match confidence scores, low-confidence short-circuit with status, closed-market status, wide-spread tradeability flags, cancellation-rule parsing, and fallback behavior for news sources. It even quantifies EV impact for 50/50 refunds. This goes far beyond the annotation baseline and provides actionable safety 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 very long, but it is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loads the core purpose. Every section provides unique information, yet the sheer length may tax an agent's context window. It is detailed rather than concise, but the structure helps navigation.

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?

This is a complex tool with no output schema, and the description compensates thoroughly. It explains the response shapes for market, analysis, evidence, parent_event, and news fields; enumerates classifiers; provides fan-out examples; and details edge cases like low-confidence matches, closed markets, wide spreads, and cancellation-rule risks. An agent can reliably infer behavior and decide when to 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?

The input schema already provides 100% coverage for all three parameters, including descriptions and examples. The description mentions the accepted forms of the 'market' parameter and the quick/thorough depth, but these are already in the schema. No additional parameter-level semantics are added, 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 starts with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the market input forms (slug, URL, or question) and enumerates concrete use cases ('should I bet on X', 'what does the data say about Y'), which distinguishes this from sibling tools like polymarket_edges or validate_claim.

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 when-to-use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking shortcuts and safety mechanisms. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full exclusionary guidance.

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

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

Beyond the annotations (read-only, idempotent), the description reveals data sources (SEC EDGAR/XBRL for companies; FAERS/FDA for drugs), special handling for off-calendar fiscal years, sorting by primary metric, and output format with citation URIs. It also claims efficiency (replaces 8–15 lookups), which is valuable behavioral context not visible in 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 clause adds new information – trigger phrases, entity count limits, data sources, sorting, output format, and efficiency gains. It is front-loaded with the most critical usage signal in the first sentence. Despite its length, it earns its place with high information density.

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 correctly includes return format (paired data + citation URIs). It covers edge cases (off-calendar fiscal years), data provenance, sorting behavior, and the full range of entity types. For a comparison tool with 2 parameters, this is comprehensive and leaves no critical 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?

The input schema has generic descriptions, but the description enriches them significantly: type='company' specifies metrics like latest 10-K revenue, net income, cash, long-term debt; type='drug' specifies adverse-event counts, FDA approvals, active trials. It also provides concrete examples for values (e.g., ['AAPL','MSFT']), adding meaning beyond schema definitions.

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 trigger phrases ("Compare X and Y", "X vs Y") and explicitly states it performs side-by-side comparison of 2–5 companies or drugs in one call. It names the resource (entities) and the action (compare), and distinguishes from siblings by asserting it should be preferred over sequential single-pack lookups.

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

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

It gives explicit when-to-use guidance: any comparison query between 2–5 entities, with example language. It also implies exclusions by stating "ALWAYS PREFER over sequential single-pack lookups", which effectively tells the agent not to use individual lookup tools for comparison tasks. This is clear and actionable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral context: required account and paid tier for 'thorough' depth, one-call parallel decomposition, return format with gaps[] and never-invented evidence, second-hop gap recovery, contradictions[] scan, fetchable citation URIs, semantic excerpting, and expected response times (15-90s). 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 long but densely informative, front-loaded with the account requirement and sibling distinction. Every sentence conveys useful info, but some details (e.g., repeated emphasis on 'never invented' and ask_pipeworx guidance) could be trimmed. Still, the verbosity is justified by the tool's complexity and the need to set expectations for latency and output structure.

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

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

Given there is no output schema, the description thoroughly covers return values (findings packet with evidence, confidence, source, fetched_at, citation), error/empty cases (gaps[]), and operational details (timeouts, auth, paid plan). It also covers limitations (breaking news not well served) and alternatives, making the tool self-contained and easy to invoke correctly.

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

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

The schema already describes both parameters well (100% coverage), but the description adds significant meaning: it explains depth values in behavioral terms (quick=3 facets, standard=default with gap recovery, thorough=6 with iterative hop and contradictions) and clarifies that 'question' can be broad and multi-part. This goes beyond the schema by linking parameters to execution behavior.

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 deep_research performs 'grounded multi-source research' across Pipeworx's 1462 structured data sources, decomposing questions into facets and routing them to 5,564 tools in parallel. It explicitly differentiates from siblings by noting 'this is NOT open-web search' and directing single lookups to 'ask_pipeworx', making its unique 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?

Usage guidance is exceptionally explicit: it recommends deep_research for 'broad/multi-part questions over structured data', provides concrete examples, and names alternatives with clear criteria — 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also covers account/authentication prerequisites and when to fall back to ask_pipeworx if not signed in.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds meaningful behavioral context beyond annotations: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains return format and one-call behavior, which is valuable for an 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 appropriately sized, front-loaded with the main purpose, then usage guidance, then return behavior and a final call-to-action. Each sentence adds distinct value with no redundancy or filler. The structure guides the reader from what → when → how.

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 discloses what the tool returns (names, descriptions, schemas, examples) and that results are directly callable. It covers usage contexts, domain coverage, and the 'call first' recommendation, making it complete for a tool of this simplicity.

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 all six parameters including aliases. The description mentions the query parameter as a 'natural language description' and implies the limit parameter via 'top-N', but adds little beyond the schema. This keeps the score at the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by framing it as a discovery/lookup tool rather than an analysis or research tool. The list of covered domains further reinforces its specific purpose.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It does not explicitly name alternatives or exclusions, but the guidance is clear and actionable, earning a 4 rather than 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 annotations, the description discloses the parallel fan-out across sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific output fields, the USPTO sunset soft-fail behavior, GDELT→GNews fallback, and the limit of 5 recent filings. This adds substantial behavioral context beyond annotations.

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

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

The description is long but highly information-dense and well-structured. It front-loads with example queries and the core purpose, then details outputs and input constraints. While not maximally concise, every sentence contributes meaningful value, making it appropriately sized for the tool's complexity.

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

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

Given the tool's multi-source nature and the absence of an output schema, the description thoroughly covers inputs, outputs, sources, edge cases (names unsupported, USPTO sunset), and fallback behavior. It provides nearly all context an agent needs to select and invoke the tool correctly, including resolution guidance for alternate inputs.

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, but the description adds valuable examples: ticker 'AAPL' or zero-padded CIK '0000320193', and reinforces the unsupported name input. It also clarifies the 'type' enum by stating only 'company' is supported today, with person/place coming soon, which goes slightly beyond the schema.

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

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

The description clearly identifies the tool's purpose: creating a full cross-source profile of a US public company in one parallel call. It provides numerous example queries, specifies the entity type (US public company), and distinguishes itself from siblings by explicitly stating it should be preferred over chaining single-pack lookups.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it, noting that names are not supported and directing users to resolve_entity first if only a name is available.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds behavioral context by explaining reasons for deletion (stale context, completed task, sensitive data) and confirms it targets agent-saved memory. No contradiction with annotations.

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

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

The description is two sentences: the first front-loads the primary action, the second provides usage guidance. Every word earns its place, with 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 1-parameter deletion tool with strong annotations, the description fully covers purpose, usage, and relevant constraints. It lacks an output schema but that's not needed for a delete operation, and it appropriately references 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?

The input schema has one parameter with a clear description ('Memory key to delete'), and schema coverage is 100%. The description merely says 'by key', adding no significant semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Delete'), a resource ('previously stored memory'), and a mechanism ('by key'), which clearly defines the tool's function. It distinguishes from memory-related siblings like remember and recall by specifying the delete action.

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

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

The description explicitly lists when to use the tool: when context is stale, the task is done, or to clear sensitive data. It also mentions pairing with remember and recall, giving complementary tool context, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail: it fetches the page, extracts title/description/key links, and emits a specific markdown output format, which goes 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?

The description is appropriately sized with three sentences, each providing distinct value: purpose, process, and use cases. It is front-loaded with the core action and avoids redundancy with 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?

For a simple read-only tool with two parameters and no output schema, the description is complete. It covers what the tool does, how it works, what the output looks like, and when to use it. No critical gaps remain.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (url and max_links). The description does not add additional parameter-level detail, but it reinforces the output format and use context. Baseline 3 is appropriate since the schema carries the load.

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 ('Generate a production-ready llms.txt file'), the resource ('for any URL'), and the outcome ('so AI crawlers can index the site cleanly'). It also lists concrete use cases, distinguishing it from sibling tools that focus on visibility checks or research.

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 and specific use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). However, it does not explicitly mention when not to use this tool or name alternative tools for similar tasks.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds value by specifying the return schema and default behavior (active only). It also clarifies the scope ('caller's'), which is useful behavioral context 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?

The description is two sentences: the first states the purpose and outputs, the second gives practical usage guidance. Every word earns its place 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 simple list tool with one optional parameter and no output schema, the description is complete: it names all returned fields, conveys the default filter, and explains when to use it. Annotations cover safety, and sibling tools provide surrounding 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?

Schema coverage is 100% with a single parameter (include_inactive) well-documented in the schema. The description reinforces the default by saying 'active subscriptions' but adds no new parameter-level detail beyond the schema, matching the baseline for high 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 uses a specific verb ('List') and resource ('the caller's active subscriptions'), and enumerates the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). This clearly distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel.' These imply the tool is for inspection before subscribing/unsubscribing, but it does not explicitly state when not to use it or name alternatives beyond the implied context.

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

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

Annotations provide no hints (all false), so the description carries the burden and does it well: it discloses the rate limit (5/day/identifier), that it's free and doesn't count against tool-call quota, the claim_token behavior for anonymous filings, and the intended use of not pasting end-user prompts. No contradiction with annotations.

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

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

The description is a dense paragraph but every sentence carries useful information (usage scenarios, scope, token flow, rate limit, cost). It's appropriately front-loaded with the core purpose. Could be slightly more skimmable with bullets or shorter sentences, but there is no waste.

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

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

The description covers the tool's full behavior: what it does, when to use it, how to scope feedback, the follow-up mechanism with claim_token, and operational details (rate limit, quota). No output schema exists, but the description explains what will be returned (claim_token or status), making it complete for an agent to invoke and interpret.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), the structured context fields (pack, tool, vertical), and message quality guidance. It clarifies the interaction pattern beyond the schema's standalone 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: to send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by explicitly scoping to Pipeworx tools only and excluding other MCP servers' 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?

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear exclusion: do not use for tools from other MCP servers. Also explains the two modes (file feedback vs. check with claim_token) and the rate limit, giving complete usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful context: data derived 'from CF analytics-engine,' 'no PII,' 'just (pack, tool, count),' and 'cached 5min-1h depending on window.' This discloses data source, privacy, and caching behavior beyond the annotations, 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 three well-structured sentences: core function, use cases, and technical details. Every sentence provides unique information—no repetition or filler. It is appropriately sized for the tool's simplicity.

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

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

For a simple read-only tool with no output schema, the description covers return content (top tools, top packs, call volume, pack/tool/count), use cases, caching, and privacy. It could mention sort order or result limits, but these are minor and likely self-evident for a trending list.

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

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

Schema coverage is 100%, and the schema's description already explains the window semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only repeats the window options (24h, 7d, 30d) without adding further nuance, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume over a recent window. The verb 'Returns' is specific and the resource ('what other AI agents are calling on Pipeworx') is unambiguous. It distinguishes itself from siblings like 'discover_tools' by focusing on aggregate agent-call trend data rather than general discovery.

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 three explicit 'Useful for' scenarios (hot data sources, canonical tool confirmation, alignment with agent needs). This gives clear context on when to use it. However, it does not name alternative tools or explicitly state when NOT to use it, so it lacks the exclusivity guidance required for a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: the fill-check mechanism (realizable_edge_pp ≤ 0 means don't trade), partition placeholder filtering, similarity thresholds, and the distinction between theoretical and realizable edges. This richly discloses edge cases and internal logic without contradicting annotations.

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

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

The description is lengthy and dense, but it is well-structured with clear sections (e.g., SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. While every sentence adds value, the sheer length might make parsing harder for an agent; however, the organization mitigates this, earning a high but not perfect score.

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

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

Given the tool's complexity (two optional modes, no output schema, multiple edge cases), the description covers all necessary ground: mode selection, response field examples, fill-check caveats, and a reference to a related tool. It even explains when to avoid trading (realizable_edge_pp ≤ 0). The lack of an output schema is compensated by explicit response field descriptions.

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

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

Input schema coverage is 100% with both 'event' and 'topic' described, but the description goes much further. It explains the exact format for 'event' (e.g., 'fed-decision-may-2026' or full URLs) and gives concrete examples for 'topic' (e.g., 'Fed rate decision'). It also clarifies the behavioral outcome of each parameter: event walks child markets, topic searches related events and flattens markets, adding meaning well 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly defines the tool's unique function and distinguishes it from siblings like polymarket_edges and polymarket_fill_risk, which are referenced but not performing the same arbitrage detection logic.

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

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

The description provides explicit usage guidance for each scenario: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', or 'pass topic for a themed cross-event scan.' It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This clearly tells the agent when to use this tool and when to use a sibling.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond this: response segmentation (by_segment), diagnostics to explain empty segments, 1h KV caching, the 24h-move warning that edge may already be priced in, and filtering logic such as placeholder-slug exclusion. No contradiction with annotations.

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

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

The description is extremely verbose, with dense technical asides such as 'lognormal barrier from 90d FRED log-returns' and 'GDELT 7d/21d article-volume ratio' that are not essential for tool selection. While front-loaded with purpose, it contains far more detail than needed for an agent to decide when to invoke the tool, making it inefficient.

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 thoroughly covers response shape (by_segment, fed_candidates, _diagnostics), filtering gates, and edge-case behaviors (placeholder filter, Fed signal unreliability). It is sufficiently complete for an agent to know what to expect and how to interpret results, even if its verbosity hurts conciseness.

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 documents all 9 parameters with 100% coverage, including slippage context and partition-specific Kelly behavior. The description restates a few knobs but adds no new parameter-level semantics beyond the schema. With schema_description_coverage high, baseline 3 applies; the description's extra context (e.g., min_partition_leg_kelly's interaction) is also already in the schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb+resource with scope. It distinguishes from siblings like polymarket_arbitrage by covering model-driven, structural arbitrage, and concentrated longshot segments. The 'what should I bet on today' framing reinforces the intended purpose.

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

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

Provides clear context: built for discovery without paging hundreds of markets, and describes filtering knobs (min_liquidity, max_spread_pp) for tradeable-edge screening. However, it doesn't explicitly name alternatives or state when not to use this tool vs. polymarket_arbitrage or edge_tracker, so it lacks explicit exclusions.

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 other annotations present, the description goes far beyond them. It discloses non-obvious behaviors: snapshots are written on cache-miss (so gaps mean no scan), history depth is bounded by a 60-day TTL, decay is computed on |edge_pp_net| and signed by trade direction, and expired[] captures opportunities gone from the latest snapshot. The response structure is fully documented. No contradiction with annotations.

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

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

The description is dense but well-structured: purpose statement, Args section, RESPONSE section, and LIMITS section. Every sentence adds value—the response section details tracked/expired/snapshot_dates arrays, and the limits section explains TTL and data gaps. 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?

Given no output schema, the description compensates thoroughly by documenting the full response shape including field semantics (e.g., 'decay_pp_per_day' computed on absolute value, 'snapshot_dates' meaning gaps). It also covers edge cases like snapshot TTL and cache-miss behavior, making the tool behaviorally complete for an agent. The only minor gap is explicit sibling tie-in, but that was already penalized in usage_guidelines.

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 params already have descriptions with defaults/clamps. The tool description adds minor conceptual framing ('snapshot family' for window, 'lookback' for days) but does not significantly increase understanding beyond the schema. Baseline 3 is appropriate because the schema handles the heavy lifting.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the core question: 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges (which likely provides current edges) by framing the tool as a historical/telemetry view.

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

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

The description gives strong contextual guidance on when this tool is valuable: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies the alternative (use the base polymarket_edges for current views) but never explicitly names a sibling tool or provides 'do not use this for X' exclusions. This is clear usage context but lacks explicit alternative differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial context beyond that: it explains how size_usd is interpreted differently in single-market vs basket mode, describes the walk-the-ladder behavior, lists detailed return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), and warns about the risk of partial fills. This is far beyond annotation coverage and gives the agent a clear behavioral model without contradicting 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 long but densely packed with relevant details, and it front-loads the core purpose and required-parameter note. The use of ALL-CAPS for mode and size_usd calls out important distinctions. It could be broken into smaller paragraphs or bullets for easier scanning, but every sentence earns its place 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 burden of explaining return values, and it does so thoroughly: it lists outputs for both single-market and basket modes, includes the verdict values, and highlights risk-relevant fields like thin_legs and forced_directional_risk. It also covers parameter semantics, usage thresholds, and failure modes. This makes the description complete for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage of parameter descriptions, so baseline is 3. The description adds meaningful semantic nuance: for side it explains 'default auto — sell if partition sum > 1, buy if < 1' in basket mode, and for size_usd it clarifies 'max spend on buys, target proceeds on sells' and 'settlement notional — shares per leg, each paying $1 at resolution.' These are not present in the schema, making the description additive beyond structural fields.

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 and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes itself from sibling tools by naming the exact use case: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This leaves no ambiguity about what the tool does and how it differs from related tools.

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

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

The description provides explicit when-to-use guidance, including a direct reference to sibling tools and a threshold: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and warns against a specific misuse case (partial basket fills convert arb into unhedged directional position). No exclusions are stated, but the guidance is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior, but the description goes far beyond by detailing the compatibility_warning conditions (two distinct cases), temporal_alignment significance, and skipped_cross_type/subtype counters. It tells the agent when the spread is mathematically meaningful and when it is not, which is critical for correct interpretation.

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 the description is long, it is well-structured with clear sections: overview, modes, response, safety fields, and warnings. It is front-loaded with the core purpose and each subsequent sentence adds operational detail without fluff. 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?

With no output schema, the description thoroughly documents the response structure (leg-by-leg prices, matched spread[].top_spreads_pp) and all warning/flag fields (compatibility_warning, temporal_alignment, skipped counters). It also explains edge cases where spreads are meaningless, ensuring the agent understands the tool's limitations and output semantics.

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 parameter coverage, listing all topic values and describing explicit ticker/slug fields. The description enhances this by explaining how the 'topic' parameter auto-fetches matching events and that explicit parameters override the mapped side. This adds a layer of interaction semantics not present in the schema alone.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's function and resource. It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on cross-venue comparison rather than single-venue metrics.

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/slugs) and provides context for when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings and that 'pre-mapped ≠ tradeable,' setting expectations. However, it does not explicitly name alternative tools for same-venue spread or arbitrage scenarios.

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

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

Beyond the read-only and idempotent annotations, the description adds valuable behavioral details: the option to list all keys when the key argument is omitted, the scoping to the agent's identifier, and the relationship with remember/forget. It does not cover what happens if a key is missing, but this gap is minor given the simplicity.

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 well-structured sentences: the first states the core action, the second provides the rationale and examples, and the third covers scope and companion tools. Every sentence adds value and the most important information is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete enough: it explains the two modes, the scope, and the family of tools. The only missing piece is explicit return format or error behavior, but the annotations and examples mitigate this for confident use.

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

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

The schema already fully documents the single 'key' parameter with a clear description and examples. The description adds illustrative key use cases (ticker, address, notes) but does not fundamentally alter the parameter semantics. Baseline of 3 is appropriate given 100% 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 opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes recall from its siblings by naming companion tools (remember, forget) and explaining the dual-mode behavior. This is unambiguous and informative.

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 explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and provides concrete examples. It also gives alternatives by pointing to 'remember' for saving and 'forget' for deleting, and implies the alternative of re-deriving data. Scope limitation is also noted.

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 describes mark_read:true which 'flag returned events read so the next call only shows newer ones'—a persistent state mutation. This is a severe inconsistency.

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

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

The description is concise (three sentences) and front-loaded with the primary action. Every sentence adds useful information: return payload, filtering, mark_read behavior, and an alternative access method. No wasted words.

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

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

With no output schema, the description appropriately describes return fields (source, citation_uri, raw payload). It covers all major aspects: filtering, limit, mark_read, unread_only, and polling suitability. Minor gaps like ordering and pagination are not critical for this straightforward read tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving a type example ("sec_8k"), clarifying the since format (ISO timestamp), and explaining the consequence of mark_read (only newer events next call). This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It uses a specific verb ('Pull') and a specific resource ('fired events from your subscription feed'), distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description provides clear usage context, explaining how to filter by type and since, and how mark_read affects future calls. It also suggests an alternative HTTP endpoint for scripts and dashboards, implying when not to use this tool. However, it does not explicitly contrast with other MCP tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: fan-out to multiple sources, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset, and the return format (changes[], total_changes, citation URIs). This exceeds what annotations provide.

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

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

The description is comprehensive yet efficiently structured: it opens with example queries, follows with source/failure details, and closes with return format and an alternative tool. Every sentence adds unique value, with no repetition of schema/annotations. 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?

Given the tool is complex (multi-source, fallback, soft-fail) and there's no output schema, the description fully covers return structure (changes[], total_changes, pipeworx:// URIs), accepted `since` formats, and fallback behavior. It also provides an explicit pointer to entity_profile for static needs, making the tool contextually complete 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?

Schema covers all 3 parameters with descriptions, but the description adds meaningful examples for `since` (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It also clarifies `value` accepts ticker or zero-padded CIK, reinforcing schema semantics. This goes beyond 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 explicitly states the tool provides a 'change feed for a company' and lists the sources (SEC, GDELT/GNews, USPTO). It gives concrete example queries ('What's new with X') and clarifies it returns structured changes[], distinguishing it from entity_profile. This is a specific verb+resource+scope definition.

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 through example natural language queries and describes the time-window scope ('last N days/weeks/months'). It explicitly names an alternative: 'Use entity_profile instead when you want the static profile...', giving a direct exclusion. This is more than sufficient.

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

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

Beyond annotations (idempotent, non-destructive), the description adds key behavioral context: key-value storage, scoping by identifier, and retention policy (24 hours for anonymous sessions, persistent for authenticated). It doesn't explicitly state overwrite semantics, but the persistence caveat is valuable.

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 purpose, usage, and behavioral details without fluff. The structure front-loads the action and uses examples efficiently.

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 what, when, how stored, and retention. It is self-contained and leaves no critical 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% with clear descriptions for both 'key' and 'value'. The description reinforces the key-value pair concept but adds no syntax or additional format details, so it stays at the 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 verb and resource: 'Save data the agent will need to reuse later,' and provides concrete examples (resolved ticker, target address, user preference). It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget.'

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

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

'Use when you discover something worth carrying forward' gives explicit context, and 'Pair with recall to retrieve later, forget to delete' names alternatives, meeting the highest bar for usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details: the cascading lookup through multiple endpoints, graceful degradation ("LEI/FIGI enrichment degrades gracefully"), and how unresolved identifiers are reported ("under `unresolved` rather than omitted"). This goes well beyond what annotations provide.

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

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

The description is comprehensive but fairly long (roughly 10 sentences). While every sentence adds value, the structure could be improved by front-loading the most critical guidance ("Use FIRST whenever you have a name but need an ID") and then going into details. Currently, that key usage directive is in the middle. Some technical details (e.g., GLEIF ISIN-to-LEI mapping) are verbose for an LLM reading it.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, cascading lookups), the description is remarkably complete. It covers what each type returns, what inputs are accepted, how failures are handled, and sources of data. No output schema exists, but the description thoroughly explains the return structure (identifiers labelled with source, unresolved section). Only 2 required parameters with 100% schema coverage further reduces the burden.

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 significant semantic value beyond the schema: it explains that company accepts ticker, CIK, ISIN, or name; that drug accepts brand or generic name; provides concrete examples like "CH0038863350" for ISIN and "ozempic" for drug; and explains the cross-source identity spine for company including LEI, FIGI, and CIK resolution.

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

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

The description uses multiple specific verb-resource pairs ("resolve a user-spoken NAME to the canonical/official identifiers", "look up the ID for…") and clearly distinguishes from siblings like `entity_profile` and `compare_entities` by emphasizing that this tool resolves names/aliases to identifiers, not profiles or comparisons.

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

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

The description explicitly states when to use ("Use FIRST whenever you have a name but need an ID") and what it replaces ("using resolve_entity replaces 2-3 manual lookups"). It doesn't list exclusions but provides extensive context on supported types, making the when/why very 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?

Despite having robust annotations (readOnly, openWorld, idempotent, non-destructive), the description adds meaningful behavioral detail: it probes via ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the output fields (score, confidence, signal density), going beyond the annotations to explain what happens during execution.

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 purposefully crafted sentences: what it does, how it works, and what it returns. Every sentence adds value, no redundancy, and the content is front-loaded with the action verb and key resource.

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 compensates by explicitly stating the return format ('ranked list with score, confidence, signal density per entity'). It covers purpose, process, usage context, and output, making the tool comprehensible 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?

Schema description coverage is 100% — every parameter (models, _apiKey, context, entities) has a clear description. The description adds minimal extra parameter meaning (e.g., 'your brand + N competitors' mirrors the schema note that the first entity is the subject). The schema already carries the semantic load, 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 a specific action ('Compare AI visibility'), the resource ('multiple entities side-by-side'), and the output ('ranked list with score, confidence, signal density per entity'). It distinguishes itself from the sibling tool ai_visibility_check by explicitly noting it probes each entity with that tool, making it a batching/comparison variant.

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

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

Provides clear context for use: 'competitive AI-marketing audits' with a concrete example question. The mention of 'your brand + N competitors' and 'probes each entity with ai_visibility_check' implies it is for multi-entity comparison (vs. ai_visibility_check for single entity), though it does not explicitly state when NOT to use it or name alternative tools.

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

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

Beyond annotations, the description discloses crucial behavioral traits: it is a composite fan-out call, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s, with sources_failed listing timeouts. This adds context that annotations cannot convey, such as latency expectations and 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?

The description is dense but every sentence earns its place: purpose, when-to-use, return structure, ecosystem scope, and failure behavior. It is front-loaded with the core value proposition and uses structured lists for outputs, making it highly scannable 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 enumerates the summary block fields, per-advisory detail, links, and recent versions. It also covers ecosystem limitations, timeout behavior, and graceful degradation, leaving no critical ambiguity for an agent deciding to use 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 description coverage is 100% with detailed parameter descriptions (e.g., package name incl. scoped packages, version defaults to latest). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score 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 opens with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call.' It clearly defines the tool's purpose as a multi-source evaluation for npm packages, distinguishing it from any sibling tools by naming its unique composite nature (deps.dev + bundlephobia).

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives an exclusion for other ecosystems: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' directing to an alternative approach.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond these: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap where longer inputs are truncated and flagged, and output including character offsets and similarity scores. This fully discloses the internal behavior and potential edge cases.

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

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

The description is dense but well-structured, starting with the core function, then its use case, a pairing suggestion, and finally technical specifics. Every sentence earns its place; there is no fluff or repetition. The use of em dashes and punctuation keeps it readable without being lengthy.

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?

This tool has no output schema, so the description must explain the return format—and it does: 'top-N passages with character offsets and similarity scores'. It also clarifies the truncation flag for oversized inputs, gives algorithm details, and provides usage context. This is a complete behavioral contract for an agent, fully satisfying the demands of a tool with no structured output definition.

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 three parameters are fully documented in the schema (100% coverage), so the baseline is 3. The description adds value by providing concrete examples of what 'text' can be (SEC 10-K body, article, long tool result) and reinforcing the 'query' as a natural-language request with sample phrasings. These examples enrich the understanding without adding new technical constraints, so a 4 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 'Semantic search INSIDE a fetched record', clearly stating the verb (semantic search), the resource (a fetched record/text), and the scope (inside that record, not fetching). It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing it takes already-pulled text and returns passages, 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?

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also provides a complementary workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear, actionable guidance for tool selection and sequencing.

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

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

Beyond annotations, the description adds valuable behavior: returns the new subscription id, requires OAuth, phone verification for SMS with a 10/day cap, and describes delivery channels and feed persistence. It also mentions the always-on feed and optional email/SMS. This significantly enriches what the annotations alone 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 information-dense but logically organized: purpose, return, requirements, type examples, delivery options. Every sentence carries unique content, though the long parentheticals and streams of examples make it somewhat heavy. It is still concise relative to the complexity covered.

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

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

The description covers prerequisites, return value, delivery channels, and usage context. It also references sibling tools for consuming alerts. The schema fills in remaining parameter details, and the return value (subscription id) is explicitly stated, making the description complete for a create-subscription tool without an output schema.

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

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

The schema already has 100% coverage with detailed descriptions for all parameters. The description adds real value through concrete examples (sec_8k items:["5.02"] = officer change, polymarket_edge params:{topic:"fed"}, fred_series series_id:"UNRATE") and clarifies delivery semantics. However, it omits two schema types (patent_grant, clinical_trial) in the description, relying on the schema for those.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by stating the creation action and returning a subscription id.

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 specifies a clear prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also references siblings for retrieving alerts ('pull via recent_alerts' or the registry URL). However, it does not explicitly state when NOT to use this tool (e.g., for listing existing subscriptions), leaving some implicit context.

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

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

Annotations (readOnlyHint, idempotentHint) already cover safety, and the description adds functional transparency: it returns 'category-bucketed example questions' with 'exact tool + argument shape,' drawn from the live catalog. It also notes the behavior of calling with no arguments vs. passing a topic. This goes beyond the annotations without contradicting 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 detailed but efficiently organized, front-loading example queries to quickly orient the reader. Every sentence contributes useful context—purpose, return value, parameter usage, and when to use—though slightly long, it avoids fluff and earns its length for an onboarding tool.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and the presence of strong annotations, the description is complete. It covers what the tool does, what it returns, how to invoke it, and when to use it, making it fully adequate for an agent to select and call correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by explaining the topic parameter's effect: 'pass `topic` (e.g. "finance", "pharma", "betting") to focus' and 'Omit for a cross-category spread.' This enriches the schema description with concrete examples and behavioral expectations.

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: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the verb (suggest questions), the resource (Pipeworx capabilities), and distinguishes itself from sibling tools by noting it teaches how to call meta-tools like ask_pipeworx and entity_profile.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter and what happens when omitted, providing clear context for when to use this tool versus alternatives.

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

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

Annotations already indicate this is a non-read-only, non-destructive, idempotent operation. The description adds value by explicitly stating ownership enforcement and that the row is deactivated (not deleted), preserving historical events. These are meaningful behavioral traits that go 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?

The description is two sentences, front-loaded with the primary action, and adds only essential details about ownership and deactivation. Every word contributes meaning; 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 cancellation tool with one parameter and no output schema, the description covers the action, ownership constraint, and the crucial deactivation behavior. It points to recent_alerts for historical events, making it fully complete for expected use.

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

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

The input schema provides 100% coverage of the single parameter, including its type and source ('returned by subscribe'). The description adds no additional parameter details, which is fine given the schema handles it; 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 'Cancel a subscription by id,' which clearly states the verb, resource, and method. It also distinguishes itself from siblings like subscribe and list_subscriptions by specifying the cancellation behavior and the deactivation (not deletion) nuance.

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—when you want to cancel a subscription—and clarifies that ownership is enforced (only your own subscriptions). It doesn't explicitly name alternatives, but the deactivation note implies the distinction from deletion and points to recent_alerts for historical events, offering solid usage guidance.

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

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

Beyond the read-only and non-destructive annotations, the description explains internal routing (SEC EDGAR vs grounded pipeline), defines the full set of verdicts, and adds critical caller instructions about how to interpret 'could_not_verify' (it does not happen and must not be shown as evidence) and 'unsupported'. This is rich behavioral context that annotations alone do not provide.

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

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

The description is relatively long but every sentence contributes: trigger phrases, use case, dual-path mechanics, output format, caller warning, and efficiency rationale. The 'IMPORTANT for callers:' section front-loads a critical caveat. Nothing feels redundant or wasteful.

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

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

Given the tool has no output schema, the description explains the return types (verdicts, value with citation, reasoning) and clarifies ambiguous statuses. It covers both main use cases (financial vs. other), parameter behavior, and edge cases, making it self-contained for an agent to decide whether and how to call 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 already provides 100% coverage with detailed descriptions for both 'claim' and 'tolerance_pct'. The description adds no parameter-specific meaning beyond examples; it mentions a default tolerance cap but that is already in the schema. With schema carrying full weight, the baseline of 3 is appropriate.

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

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

The description opens with concrete trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and clearly states the tool verifies natural-language claims against authoritative sources. It also distinguishes itself from sibling research tools by focusing on fact-checking and explicitly describing the claim → verdict workflow.

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 explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear trigger. It also mentions that it replaces 4–6 sequential calls, helping agents prefer this tool for fact-checking. However, it does not name alternative tools or explicitly state when not to use it, 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.