Sports Game Odds

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read-only nature is covered. The description adds valuable behavioral context: the default free model (Workers AI Llama-3.3-70b), the BYO Anthropic key cost implication, and the per-model return shape. This goes 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?

Three sentences, ~60 words, front-loaded with the core action and immediately followed by key operational details. Every sentence earns its place: what it does, how the models work, return format, and use cases. 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?

The tool has no output schema, so the description correctly explains the return value (per-model object with score, confidence, signals, raw_response plus combined view). It also covers default behavior, optional cost, and practical use cases. Given the moderate complexity and rich annotations, the description is complete enough for an agent to select and invoke confidently.

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 every parameter is documented structurally. The description adds meaning beyond the schema by clarifying the default model for the 'models' parameter and explaining that '_apiKey' is only needed to enable Anthropic probes with direct payment. This enriches the parameter semantics beyond raw JSON schema.

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

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

The description opens with a specific verb ('Probe') and resource ('LLMs'), and clearly states the output: a visibility score (0-100) per model. It distinguishes itself from sibling Q&A tools like ask_pipeworx by focusing on scoring what models know, and from scan_competitor_ai_presence by targeting LLM knowledge rather than general AI presence.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to invoke the tool. It does not list exclusions or alternative tool names, but the use-case list is enough to guide an agent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavior: routes internally, fills arguments, returns citation URIs, works on every tier, and is a single fast call. It does not mention failure modes or rate limits, so I deduct one point.

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 the calibration exemplars, but every section earns its place: usage guidance, examples, differentiation. It is front-loaded with the 'PREFER OVER WEB SEARCH' directive. Slightly verbose 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?

For a complex routing tool with no output schema, the description covers return format (structured answer with citation URIs), tier availability, and alternatives. It gives concrete examples and addresses when to use it universally. No obvious gaps for the agent to select and invoke.

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

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

Schema covers 100% of parameters, including aliases. The description adds no new parameter-level details beyond examples that mirror the schema's examples. Baseline 3 is appropriate; the schema already does 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 states a clear, specific purpose: it routes factual questions to the most appropriate tool among 5,462 tools and returns structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with tailored use cases.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', lists concrete trigger phrases, provides examples, and explains when to escalate to grounded or deep_research. This is exceptionally actionable guidance for an agent.

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

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

Beyond annotations (read-only, idempotent, open-world), the description discloses that this is an experimental edge with live candidate routing changes, that no candidate is active currently so it matches ask_pipeworx exactly, and that it is a full working router with no fallback. This substantially enhances understanding of its behavior.

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

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

The description is composed of four information-dense sentences that are front-loaded with the beta identity. It's slightly repetitive with 'ask_pipeworx' but each sentence adds value without excessive verbosity.

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

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

The tool is complex (universal router), but the description covers its current state, usage, and relationship to ask_pipeworx. It mentions the same response shape, which is adequate given that ask_pipeworx's response can be referenced, though it doesn't spell out the response format directly.

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

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

The schema covers 100% of parameters, all being aliases for 'question' with descriptions. The description adds no extra parameter semantics beyond referencing 'same arguments' as ask_pipeworx, so it doesn't go beyond the schema's existing coverage.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,462 tools and arguments. It distinguishes itself from the stable sibling by noting candidate routing improvements, making its 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?

The description says to use it exactly like ask_pipeworx when you want the newest routing, and that results are compared against the stable router. This gives clear context and an implied alternative, but it doesn't explicitly mention when to prefer the stable router or other siblings like ask_pipeworx_grounded.

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 signal read-only and idempotent, but the description adds substantial behavior: it returns evidence verbatim, refusal reasons, and only uses tool result content. 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 and front-loaded with purpose, then details routing, return format, and tradeoffs. At ~100 words it is longer than minimal, but every sentence contributes necessary information for correct use.

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

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

No output schema exists, yet the description fully defines the success response shape and all refusal_reason values, covering error scenarios and cost implications. This makes the tool complete for agent decision-making.

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

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

Schema has 100% coverage for the question parameter and aliases. Description adds that the tool auto-fills arguments and routes to internal tools, so the agent only needs to provide a natural language question—beyond the schema's simple description.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its routing and extraction behavior, distinguishing it from sibling ask_pipeworx by emphasizing grounded answers and explicit refusal.

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 ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including cost tradeoff of one extra LLM call.

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 tool's annotations indicate it's read-only and non-destructive, and the description adds extensive behavioral detail beyond that: low-confidence matches short-circuit, closed markets return a blocking status, wide-spread markets are flagged, and resolution rules are parsed. It also explains the resolver contract and the fallback behavior for news sources, providing deep transparency about internal logic and 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 extensive and uses labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) making it navigable despite length. Every section contributes actionable information, and the complexity of the tool justifies the length. However, it could be seen as long, but it's well-structured.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: result.market fields, analysis fields, evidence keying, resolver contract fields (market_match_confidence, alternatives, suggestions), parent_event extractor, and news fallback fields. It even covers safety blocking mechanisms and resolution-rule risk, making it complete for an agent to invoke and interpret results.

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

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

The input schema already documents all three parameters thoroughly (market format, depth enum, include_raw flag). The description provides examples of specific fan-out patterns for depth but doesn't add new semantic meaning to the parameters themselves; most parameter-level detail is redundant. Thus a 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 opening sentence clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further specifies the input formats (slug, URL, question text) and distinguishes itself from siblings like polymarket_arbitrage by focusing on comprehensive research rather than arbitrage or edge tracking.

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

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

The description explicitly says to use it for queries like 'should I bet on X' and 'what does the data say about Y', giving clear application context. However, it doesn't 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/idempotentHint, so the bar is lower. The description adds meaningful behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output composition ('paired data + pipeworx:// citation URIs per entity'). 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 front-loaded with the purpose and query patterns. Each segment adds new information (preference rule, type-specific data, sorting, citations, efficiency), and while phrases like 'side-by-side' and 'head to head' overlap slightly, the paragraph remains efficient 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 moderate complexity and no output schema, the description explains return format (paired data + citation URIs), sorting behavior, and data sources. It also handles edge cases like off-calendar fiscal years. It's complete enough for an agent to select and invoke correctly, especially with sibling differentiators and a 100% schema-covered parameter set.

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

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

Schema covers both parameters with descriptions and examples, so baseline is 3. The description adds semantic enrichment by mapping type='company' to specific financial metrics (revenue, net income, cash, long-term debt) and type='drug' to FAERS counts, approval counts, and trial counts. This goes beyond the enum labels, earning a 4.

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

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

The description opens with explicit query patterns ('Compare X and Y' / 'X vs Y') and defines the tool as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by stating it should be preferred over sequential single-pack lookups and by detailing type-specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 direct usage triggers ('which is bigger / better / larger / more profitable' / 'rank these companies') and an explicit instruction: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies what each entity type returns, reinforcing appropriate selection. The only missing piece is naming a specific sibling tool as alternative, but the guidance is sufficiently 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account prerequisites, expected latency (15-90s), the structure of the findings packet (verbatim evidence, confidence, source, fetched_at, citations), explicit gaps[] when data can't answer, contradictions[] for deeper depths, and the behavior of semantic excerpting. This is rich behavioral context far 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 information-dense, front-loaded with account requirements and alternatives. Every sentence carries operational value (timing, citation format, gap handling), though it could be tightened with clearer structure. It earns its length 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 fully explains the return format: findings packet components, gaps[], contradictions[], hop field, and citation_uri fetchability. It also covers edge cases (empty gaps for trending topics) and timing, making the tool's behavior predictable 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?

While the schema already provides 100% coverage, the description enriches both parameters significantly: it elaborates depth levels with facet counts and hop behaviors, and clarifies that 'question' is meant for broad, multi-part natural language queries. This adds practical meaning beyond the schema's bare descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in one call, contrasting it with open-web search and single-lookup tools. It explicitly distinguishes itself from siblings like ask_pipeworx by naming the alternatives and their appropriate use cases.

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

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

The description gives explicit when-to-use guidance: it names ask_pipeworx for single lookups and breaking news scenarios, and it specifies account requirements (including a paid tier for 'thorough'). It also explains depth-level trade-offs for iterative research, leaving no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral context: that results include full input schemas with curated examples, are ready to call directly with no second lookup needed, and that it returns the most relevant tools. This goes beyond annotations and clarifies what the agent can expect.

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

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

The description is well-structured: the first sentence states the core purpose, followed by a usage directive, a clear explanation of the return value, and a strategic placement as 'FIRST' step. Each sentence earns its place, is appropriately front-loaded, and contains 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 the tool's role as a discovery tool with no output schema, the description fully explains what will be returned (top-N tools, names, descriptions, full input schemas with examples) and when to call it. With a large set of sibling tools, the description makes its unique position and value clear, making the tool self-contained.

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

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

The schema has 100% description coverage, so the baseline is 3. The description adds semantic value by explaining what kind of query to provide ('describing the data or task') and enumerating example domains (SEC filings, financials, FDA drugs, etc.), which helps the agent formulate useful queries. This is meaningful added meaning beyond the schema's parameter names.

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

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

The description clearly states 'Find tools by describing the data or task' with a specific verb and resource, and immediately distinguishes itself from sibling tools by listing the broad domains it covers. It is not a tautology and effectively conveys the tool's role as a discovery mechanism.

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

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

The description explicitly says '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.' It also implies when not to use it ('not just one answer') suggesting direct tools for single answers, providing clear 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it 'fans out' across multiple sources, describes a soft-fail for the USPTO patents API (sunset May 2025), and specifies a fallback chain (GDELT→GNews). This enriches the agent's understanding of the tool's runtime behavior.

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

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

The description is long but densely informative, with every sentence serving a purpose: example queries, data sources, return structure, and constraints. It could be more concise, but the complexity of the tool justifies the length, and it is front-loaded with user-phrase examples.

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

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

No output schema exists, so the description carries the full burden of describing return values, which it does in detail: cik, company_name, up to 5 recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers input constraints, failure modes, and alternative tools, making it highly complete for the agent.

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

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

Schema description coverage is 100%, with the 'value' parameter already documented as 'Ticker (e.g., AAPL) or zero-padded CIK (e.g., 0000320193). Names not supported...' The description repeats this information without adding new parameter-level meaning, so it stays at the baseline for full 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 states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for name-only input.

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

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

Explicitly tells when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and when not to: 'names not supported (use resolve_entity first if you only have a name).' This provides clear context and an alternative tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds context about when deletion is appropriate (stale context, done tasks, sensitive data) and implies irreversibility via 'Delete.' It does not contradict annotations, but also does not go far beyond them—hence a 4 rather than a 5.

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

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

Two sentences with no fluff. The action is front-loaded, followed by usage context and sibling pairing. Every word earns its place. The description is short yet information-dense.

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

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

The tool is simple (one parameter, no output schema), and annotations provide the safety profile. The description covers purpose, usage context, and complementary tools. Nothing important is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% for the single 'key' parameter, with a clear description ('Memory key to delete') and an example. The tool description does not add extra meaning beyond what the schema already provides. Baseline for high coverage is 3, and the description does not elevate it.

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

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

The description states a specific action ('Delete a previously stored memory by key') with a clear resource ('memory') and mechanism ('by key'). It distinguishes itself from sibling tools like 'remember' and 'recall' by naming the delete operation explicitly. The title 'Forget' is expanded into a concrete, actionable statement.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), offering clear alternatives and highlighting the tool's place in a workflow. This is exactly the kind of practical guidance needed.

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 and idempotent behavior. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and notes the output is a 'single text blob'. This goes beyond the annotations and clarifies what the tool actually does.

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: purpose, process/output, and use cases. It is front-loaded with the primary function and avoids 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 tool with 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. The annotations adequately cover safety considerations, leaving no significant gaps.

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

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

Schema coverage is 100% for both parameters (url and max_links), so the baseline is 3. The description does not add extra meaning to the parameters beyond confirming the URL is for any site and mentioning max_links indirectly via 'standard' output. It adds no new semantic value.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It highlights the output format and use cases, which distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit 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'), giving clear context for when to use the tool. It does not mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly and non-destructive behavior. The description adds behavioral context by specifying the scope ('the caller's active subscriptions') and the output shape, which goes beyond what annotations provide. It does not introduce contradictions, and the added scoping constraint 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?

The description is two sentences, front-loaded with the primary action and output, followed by a practical use-case note. Every word earns its place; there is no redundancy or filler.

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

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

Given the simple tool (one optional parameter, no output schema), the description is complete. It states the resource scope, the exact return fields, and when to use it, covering all essential aspects 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 input schema has 100% coverage for its single parameter (include_inactive) with a clear description. The tool description doesn't mention the parameter, but the schema already explains it. Baseline 3 is appropriate since the description adds no extra semantic value beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and further distinguishes it by listing returned fields (id, type, params, etc.). This makes its purpose unambiguous and distinct from sibling tools like subscribe/unsubscribe.

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

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

The description explicitly gives usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool relative to actions like subscribing or unsubscribing, providing clear context without being verbose.

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

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

The description discloses the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and operational context ('The team reads digests daily'). Annotations only say readOnlyHint/idempotentHint/destructiveHint are false, which don't cover these behaviors; no contradictions found.

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

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

It's front-loaded with the purpose and when-to-use, then details, but it runs ~150 words across 7 sentences. Some operational notes (daily digests, roadmap) are useful but could be trimmed; overall it earns its place but is not as tight as a two-sentence description.

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 still explains the key return (claim_token) and subsequent lookup mechanism. Combined with schema's 100% param coverage, exclusions, rate limits, and message guidelines, there are no critical gaps for an agent to invoke it correctly.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds practical value by explaining the claim_token format ('pwfb_…') and how to use it ('with no other arguments'), plus message content guidance ('don't paste the end-user's prompt'). This goes slightly beyond the schema, 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 opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' naming the resource (the Pipeworx team) and the feedback categories. It clearly distinguishes from sibling research/query tools by establishing this as the dedicated feedback channel, reinforced by the 'ONLY for tools served by this Pipeworx connection' boundary.

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

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

It states explicit trigger conditions ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well') and explicit exclusions ('if the tool came from a different MCP server... file it with that server instead'). This is textbook when-to-use/when-not-to-use guidance with a named alternative.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond by disclosing the data source (CF analytics-engine), privacy (no PII), the exact data shape (pack, tool, count), and caching behavior (5min-1h). This is rich context that annotations 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 well-structured: a clear opening sentence, a concise bulleted list of use cases, and a compact final sentence about data source and caching. Every sentence adds value without unnecessary padding.

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), strong annotations, and no output schema, the description provides sufficient context: expected outputs, use cases, data provenance, and freshness. There is no notable gap.

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

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

The schema fully documents the only parameter 'window' with enum values and explanations (e.g., 'Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description does not add additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a specified window. It uses a specific verb ('Returns') and resource ('Pipeworx'), and distinguishes itself from siblings like discover_tools and recent_alerts by focusing on aggregated trending data.

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

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

The description explicitly provides three 'Useful for' scenarios, giving clear context on when to use the tool. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial detail beyond these: partition_check threshold (deviations >3pp emit signals), semantic similarity threshold (≥0.30 Jaccard), placeholder filtering, and a critical fill-check caveat ('realizable_edge_pp ≤ 0 means... do not trade it').

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

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

The description is lengthy but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary purpose. While dense, each section contributes essential operational context; a slight trim could improve conciseness without losing value.

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

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

No output schema exists, so the description compensates by explicitly listing response fields (opportunities[], partition_check{}, fill_check) and explaining edge cases (e.g., when realizable edge is ≤ 0). It also references polymarket_fill_risk for custom sizing, making it self-sufficient for agent use.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic'. The description enriches this with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains what each mode does, and clarifies expected input formats (event slugs vs seed questions).

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies multiple modes (trending_scan, event, topic) and distinguishes from sibling tools by mentioning polymarket_fill_risk for custom sizing.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets, explains trade-offs, and points to polymarket_fill_risk for custom sizing, giving clear when-to-use vs alternatives.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing cache duration ('Cached 1h at the KV level'), edge net of slippage, per-sport coefficients, placeholder-leg filters, diagnostic funnel counters, and a 24-hour price-move warning. 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 information-dense but extremely long and presented as a single unstructured paragraph with heavy parentheticals and slashes. It is front-loaded with the core purpose, and the CAPS segment labels help, but it would benefit from bullet formatting and trimming.

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

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

With no output schema, the description compensates thoroughly by specifying top-level response fields (by_segment, fed candidates, _diagnostics), explaining empty-segment diagnostics, and detailing caveats like the Fed signal unreliability. This is sufficient for a complex 9-parameter read-only 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?

Input schema already covers 100% of parameters with detailed descriptions, so baseline is 3; the description adds value by explaining the interplay of knobs (e.g., why min_partition_leg_kelly exists, parent-level Kelly is zero for basket trades, and slippage assumptions). This lifts it above 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?

Clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and explicitly targets 'what should I bet on today', distinguishing it from sibling Polymarket research tools. The specific verb+resource+proprietary-data comparison makes purpose unambiguous.

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

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

Explicitly frames the tool as a daily opportunity discovery mechanism ('without paging hundreds of markets') and documents filtering knobs for tradeable edges. It does not directly name sibling alternatives or when not to use them, but the use case is clear enough to differentiate 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?

With annotations covering read-only/idempotent/non-destructive, the description adds substantial behavioral context beyond that: the 60-day snapshot TTL limit, the fact that gaps mean nobody scanned that day, daily-close-based decay calculations, and the signed nature of edge_pp_net. This goes well beyond what annotations provide and gives the agent a realistic model of the tool's data constraints.

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

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

The description is lengthy but efficiently structured: purpose first, then Args, then a RESPONSE block clearly detailing return fields, and LIMITS. Each section contains dense, non-redundant information. The front-loaded purpose and clear formatting make the length justifiable.

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 fully explaining the response structure: tracked[], expired[], and snapshot_dates[] with field meanings. It also covers key operational constraints (TTL, data gaps, close-based decay). The description is complete enough for an agent to correctly invoke and interpret 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% for both parameters, with defaults and ranges already documented. The description restates defaults ('days default 14, max 30', 'window default 1wk') but adds minimal additional semantics—it does not explain how different window families affect time series or how days influences the response. Baseline 3 is appropriate as the schema does 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 clearly states the tool's purpose with a specific verb+resource+scope: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots'. It answers a concrete question ('how long has this edge existed and is it shrinking?'), and distinguishes itself from sibling tools by focusing on historical trend rather than current edges.

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

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

The description clearly implies when to use the tool—when you need to evaluate edge persistence over time—and provides contextual reasoning ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternative tools or 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.

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description goes far beyond this by detailing mode-specific behavior, return fields, partial-fill risks, forced directional risk, clamping behavior, and the interpretation of size_usd in different modes. It adds substantial operational transparency 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 front-loaded with the core purpose and contains highly valuable content, but it is presented as a dense, unbroken paragraph. It would be significantly more readable with bullet points or section breaks. While no sentences are purely wasted, the sheer volume makes it less concise than ideal.

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

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

With no output schema, the description carries the full burden of explaining return values and edge-case risks. It enumerates all key outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk, etc.) and explains the dominant loss mode (partial basket fills converting arb to unhedged directional). This is exceptionally complete for the tool's complexity.

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

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

Although the schema already documents all four parameters, the description adds critical semantics: it states 'REQUIRES one of market or event', explains the default side selection for basket mode, and clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S' in basket mode. This goes 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, informative phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the tool's function as a fill-risk verification tool, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges, which are about finding or tracking opportunities rather than checking fill feasibility.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket), the required input for each, and the default behaviors, giving clear when-to-use context.

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

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

Even though annotations declare readOnly/openWorld/idempotent behavior, the description goes far beyond that by explaining safety fields, compatibility_warning conditions, temporal alignment, and skipped_cross_type/subtype counters. It discloses limitations like pre-mapped topics not always being tradeable, adding rich 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 long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose and every section adds necessary detail for correct usage. It is slightly verbose but not wasteful; the density of information justifies its length.

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

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

Given the absence of an output schema, the description compensates thoroughly by describing the response structure, safety fields, and edge cases. It covers parameter interactions, temporal alignment, and why certain comparisons are invalid, making the tool's behavior fully understandable for an agent.

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

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

The schema already documents all three parameters at 100% coverage, but the description adds meaningful semantics by explaining the two modes, how explicit parameters override topic-mapped defaults, and providing concrete examples of ticker/slug formats. This goes well beyond the schema's property descriptions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes and examples. It distinguishes itself from sibling tools by emphasizing the cross-venue comparison aspect and the compatibility-warning behavior.

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

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

The description explains when the spread is a real signal versus when it is not, and it details the two modes (topic shortcuts vs explicit tickers). It does not explicitly name alternative tools for single-venue analysis, but it provides clear contextual guidance for using this tool correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by disclosing scoping ('Scoped to your identifier: anonymous IP, BYO key hash, or account ID') and the dual behavior of omitting the key to list all keys.

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 compact and front-loaded with the principal action, then expands with usage context, scoping, and sibling relationships. Every sentence provides useful information with no redundancy or filler.

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

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

For a simple 1-parameter read tool with no output schema, the description covers purpose, usage scenarios, scoping, and relationships with siblings. It is sufficiently complete for an agent to select and invoke this tool correctly without further clarification.

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

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

Schema description coverage is 100%, with the key parameter already described as 'Memory key to retrieve (omit to list all keys).' The description reinforces this but adds only illustrative examples (ticker, address, research notes), not new semantic details about the parameter itself.

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

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

The description clearly states the tool retrieves saved values or lists keys, with a specific verb ('Retrieve') and resource ('value previously saved via remember'). It distinguishes itself from sibling tools remember and forget by explicitly naming them and positioning this as the lookup counterpart.

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

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

The description provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples, and references alternatives by pairing with 'remember to save, forget to delete.' This clearly differentiates it from siblings and explains when to invoke 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?

The annotation readOnlyHint=true directly contradicts the description's statement that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones.' This implies a state-changing side effect, contradicting the readOnly annotation. Therefore, the description undermines rather than clarifies behavioral transparency.

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

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

The description is concise (three sentences), front-loaded with the main action, and every clause adds useful information—return fields, filtering, mark_read side effects, and alternative access. No wasted words 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?

Despite no output schema, the description tells the agent what each alert contains (source, citation_uri, raw event payload), explains filtering and mark_read behavior, and notes polling suitability. It lacks an explicit note on pagination, but the limit parameter is in the schema, so this is not a significant gap.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by giving a concrete example for the type parameter (e.g., 'sec_8k') and explaining the functional impact of mark_read, which goes beyond the schema's basic description. It does not elaborate on limit or unread_only, but those are adequately covered by the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts, including specific fields. It distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing on the feed's alert events with filtering and read-marking options.

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

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

The description provides usage context by recommending polling and offering an alternative HTTP endpoint ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'). However, it does not explicitly contrast with sibling tools or state when to prefer this over alternatives like recent_changes, missing the 'when-not' guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description richly discloses behavior: it fans out to multiple sources, describes the GDELT→GNews fallback trigger, notes the PatentsView API sunset, and explains the result shape. This is substantial added 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 dense but every sentence earns its place: intent examples, source behavior, fallback logic, input format, output summary, and an explicit alternative tool. It is front-loaded with the most important user-facing purpose and structured logically.

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

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

With no output schema, the description compensates by stating the return contract: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It covers sources, fallback behavior, date-window semantics, and the alternative tool, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, and the schema already explains each parameter. The description adds extra practical semantics: 'since' accepts ISO or relative shorthand (with examples), recommends '30d' or '1m' for typical monitoring, and clarifies that value can be a ticker or CIK. This goes beyond the schema, though not dramatically.

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

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

The description opens with concrete natural-language examples ('What's new with X', 'latest on Y') and immediately states the core function: a change feed for a company in the last N days. It explicitly distinguishes itself from sibling entity_profile, which provides a static profile.

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

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

The description gives clear when-to-use guidance via example queries and specifies the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains internal fallback behavior between GDELT and GNews, and the USPTO sunset soft-fail.

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

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

Adds context beyond annotations: scoping by identifier, persistence differences between authenticated/anonymous sessions, and relationships with recall/forget. No contradiction with annotations (idempotentHint aligns with key-value store behavior).

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

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

Four sentences, front-loaded with the core purpose, and every sentence adds value (usage, scoping, retention, pairing). No redundant or filler content.

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

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

For a simple 2-parameter store tool with no output schema, the description completely covers purpose, usage, persistence, and integration with sibling tools. No missing critical 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 meaningful descriptions for both key and value. The description reinforces the key-value nature but does not add materially new parameter-level detail, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with specific verb+resource. It also distinguishes from siblings by explicitly pairing with recall and forget, making it 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?

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'), and mentions alternatives (recall for retrieval, forget for deletion). This gives clear context for tool selection.

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

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

The description adds rich behavioral context beyond the annotations: it explains the internal cascading lookups, auto-disambiguation, exact return fields (ticker, CIK, RxCUI, ingredient, brand), and citation URIs. This is far more than the annotations alone 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 front-loaded with user-phrased queries and then structured by supported type. It is moderately long but every section earns its place, covering input forms, returns, and citation URIs without irrelevant fluff.

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

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

Given the tool's complexity (two entity types, multiple lookup endpoints) and absence of an output schema, the description thoroughly covers input forms, output fields, citation URIs, and its role as a first-step resolution tool. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds concrete input formats and clarifies the accepted value forms for each type (e.g., ticker, CIK, or company name; brand or generic name). It also explains the auto-disambiguation behavior, which the schema does not convey.

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

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

The description clearly states that the tool resolves a user-spoken name to the canonical/official identifier required by other tools. It explicitly lists the supported entity types (company and drug) and what they return, distinguishing it from siblings like entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not name alternative tools for when not to use it, but the described use case is sufficiently distinct among the sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is established. The description adds valuable behavioral detail: it says the tool 'probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized,' and specifies the return fields ('ranked list with score, confidence, signal density per entity'), going 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 three sentences, with the primary action in the first sentence and supporting details in the following sentences. It is front-loaded, concise, and free of redundancy.

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

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

The tool is moderately complex (multi-entity comparison), and with no output schema, the description must explain return values—it does, mentioning 'ranked list with score, confidence, signal density per entity.' It also names the underlying probe tool, giving enough context for an agent to understand the tool's behavior. It could add edge-case behavior (e.g., failed probes), but for the typical use case it 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 coverage is 100%, and each parameter already has descriptive text explaining models, _apiKey, context, and entities. The description reinforces that the first entity is treated as the 'subject' (already in schema) and that the tool operates across all entities, but it doesn't add significant new parameter-level details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side,' using a specific verb and resource that clearly distinguishes it from the sibling tool ai_visibility_check, which presumably handles single entities. It also adds the ranking and output details, 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 frames the use case as 'competitive AI-marketing audits' with an illustrative question. While it doesn't state when not to use it or name alternatives, it clearly implies that this is for multi-entity comparison, whereas the sibling ai_visibility_check handles single probes. This gives clear context without 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?

Despite annotations already indicating read-only/idempotent behavior, the description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timed-out sources. This informs the agent about potential latency and error handling 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 for the tool's complexity. Every sentence earns its place: the first explains functionality, the second gives usage guidance, the third details return values and failure behavior. It is front-loaded with the core purpose and avoids redundancy.

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

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

The description is fully self-contained: it explains the synthesis of multiple data sources, the specific output fields, ecosystem limitations, and failure modes. Since there is no output schema, the description compensates by enumerating exactly what is returned. This is complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions for both package and version, so the baseline is 3. The description adds minimal extra parameter meaning beyond noting scoped packages are accepted (already in schema) and mentioning that alternative versions are returned, but it does not significantly enrich the parameter semantics.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, combining deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency') and distinguishes it from siblings by highlighting the multi-source aggregation. The phrase 'in ONE call' further clarifies the unique value.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion (NPM only; other ecosystems should use deps.dev:version directly), which serves as an alternative path. This makes when-to-use versus alternatives crystal clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds substantial behavioral detail: BGE-base-en embeddings, cosine over 500-char overlapping windows, a 200K character cap with truncation flagging, and output including offsets and similarity scores. This goes well beyond the annotation hints and explains real operational constraints.

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 compact paragraph where every sentence contributes: purpose, use case, integration, and technical details. It is front-loaded with the core action and avoids 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 tool with no output schema, the description covers inputs, outputs (offsets, similarity scores), constraints (200K cap, truncation flag), and integration with sibling tools. It fully prepares an agent to select and invoke the tool correctly in various scenarios.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'text' is previously fetched content (e.g., a SEC 10-K body) and that 'query' is natural language with concrete examples. It also explains the 'limit' behavior via 'top-N passages,' enriching the schema's description.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination. It explicitly distinguishes this tool from sibling ask_pipeworx_grounded by positioning search_within as the retrieval step over already-fetched text, rather than whole-document grounding.

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 clearly states 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also names the sibling tool ask_pipeworx_grounded and describes how the two pair, giving explicit alternative/complement context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context by detailing the return contents: moneyline, spread, total markets, player props, and prices across sportsbooks. It does not contradict annotations.

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

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

Two concise sentences and a short example convey the tool's purpose and usage with zero wasted words. The main action is front-loaded and the example makes the call structure immediately clear.

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 2-parameter read tool with no output schema, the description sufficiently explains what the tool returns (markets, props, prices). It also gives the necessary prerequisite (sgo_events). The annotations and schema cover safety and parameter semantics, making the description complete.

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

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

Schema description coverage is 100%, with both parameters (eventID and _apiKey) already well-documented. The description provides an example call and reinforces that eventID comes from sgo_events, but it adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the function: 'Get all odds & player props for a specific game.' It specifies the exact markets returned (moneyline, spread, total, player props) and distinguishes itself from sibling tool sgo_events by emphasizing 'specific game' and requiring an eventID.

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 usage context: 'Look up the eventID first via sgo_events.' This guides the user to the correct prerequisite tool and sequence. However, it does not explicitly state when not to use this tool or mention alternatives beyond sgo_events, so it stops 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, covering the safety profile. The description adds minimal behavioral context beyond annotations—only listing return fields and the eventID handoff. No contradictions, but no additional risk-relevant details.

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 plus a usage example. It front-loads the main purpose, includes a concrete invocation example, and contains no fluff.

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

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

With no output schema, the description covers the key return fields (team names, start time, status, eventIDs) and explains their purpose. The schema handles parameter details and defaults; annotations cover safety. It's reasonably complete for a list tool, though pagination details are absent.

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 has a description. The description's example and league examples add no new semantic information. Baseline 3 is appropriate since the schema does 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 clearly states the tool lists upcoming games for a league, with a specific verb ('List') and resource ('events'). It distinguishes itself from the sibling sgo_event_odds by noting that eventIDs are returned 'to fetch full odds', implying the odds tool is separate.

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

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

The description implies a workflow: list events first, then use eventIDs to fetch full odds (presumably via sgo_event_odds). It gives a concrete example and clarifies the league scope. However, it doesn't explicitly name the alternative tool or state when not to use this tool.

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

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

Discloses significant behavioral details beyond annotations: authentication requirements, delivery channel constraints (SMS 10/day cap), webhook HMAC signing and secret-once behavior, and auto-disable after 10 consecutive failures. No contradiction with annotations.

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

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

The description is long but densely packed with essential information, using structured lists and examples. It front-loads the core purpose and then expands into types and delivery details without redundancy.

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

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

Covers return value, prerequisites, type-specific params, delivery channels, and failure behaviors. No output schema exists, but the description compensates by stating what the response includes (subscription id, webhook secret).

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

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

The schema covers all parameters with detailed descriptions and examples (100% coverage). The description largely reiterates schema content, adding a few contextual examples like items:['5.02'] but not much new semantic information beyond what's 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?

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. The verb 'Create' plus resource 'subscription' distinguishes it from sibling tools like list_subscriptions 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?

Provides context for when to use (proactive monitoring) and prerequisites (OAuth account, verified phone for SMS). It references recent_alerts/registry as alternative consumption methods but does not explicitly name sibling tools as alternatives, though the sibling names make the distinction clear.

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

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

Annotations already disclose read-only and idempotent behavior. The description adds useful behavioral detail: it 'Returns category-bucketed example questions... each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' This goes beyond security hints to explain output structure and dynamic sourcing, with no contradictions.

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

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

The description is moderately long but well-structured and front-loaded with example user queries that help an agent recognize when to invoke it. Every sentence contributes context (purpose, output, usage, parameter). It's not overly verbose 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?

With no output schema, the description effectively explains the return shape ('category-bucketed example questions... with the exact tool + argument shape'). It also covers all invocation details (no args vs topic) and how to use it first. Minor missing details like number of examples per category or potential failure modes are not critical for this tool's 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 coverage for the single topic parameter is 100%, with a clear description of the allowed values. The tool description adds only a few example synonyms ('finance', 'pharma', 'betting') that don't materially expand on the schema. Per the rubric, baseline is 3 when schema covers parameters completely.

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

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

The description clearly defines the tool as the onboarding entry point for discovering what to ask Pipeworx. It uses a specific verb ('suggest') and resource, and explicitly distinguishes itself from meta-tools by saying 'Use this FIRST' and naming ask_pipeworx, entity_profile, compare_entities as things you can learn about.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes an optional topic parameter to focus results. However, it does not explicitly state when NOT to use it or compare with the sibling discover_tools, so it stops short of a perfect score.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses ownership enforcement (only cancel your own subscriptions) and the soft-delete behavior (deactivated, not deleted) with downstream impact on recent_alerts. This provides meaningful behavioral context that annotations alone do not convey.

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

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

Three sentences, each earning its place: what it does, a security constraint, and the retention behavior. No fluff or repetition of schema details.

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

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

For a single-parameter mutation tool with good schema and annotations, the description covers purpose, ownership constraints, and post-call state (deactivation with retained history). It's sufficient for an agent to select and invoke correctly.

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

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

The schema already describes the id parameter with 100% coverage ('Subscription id (uuid) returned by subscribe'). The description reinforces the ownership constraint on the id, adding a semantic detail beyond the schema, though it doesn't discuss format or examples further. Baseline 3 is elevated to 4 for the added ownership constraint.

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

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

The description opens with a clear verb-resource pair ('Cancel a subscription by id'), and the title 'Unsubscribe from Alerts' reinforces its purpose. It distinguishes from siblings like subscribe and list_subscriptions by clearly indicating this is a cancellation operation.

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: it's used when you need to cancel an existing subscription by id, with the key constraint that ownership is enforced. It does not explicitly contrast with alternative tools, but the inverse relationship with subscribe and the pointer to recent_alerts for historical events gives adequate 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 readOnlyHint and other annotations, the description discloses a rich behavioral model: the exact percent-delta math for financial claims, the grounded pipeline with verbatim evidence for other claims, and the complete return structure (verdict, actual value, pipeworx:// citation, reasoning). It also reveals that it replaces 4–6 sequential calls, which is useful operational context. 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 moderately long but every sentence serves a purpose: query examples, tool purpose, routing behavior, output details, and efficiency value. It is front-loaded with NLP triggers for routing. There is no filler, though the example phrase list could be trimmed slightly; the overall compactness is good for the tool's complexity.

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

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

The tool is complex with two processing paths and five possible verdicts, but the description covers all essentials: input (claim, tolerance), output (verdict, actual value, citation, reasoning), and behavior for both financial and non-financial claims. Since there is no output schema, the description fully compensates by enumerating return components and the fallback mechanism.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful extra guidance, especially for tolerance_pct: 'set 1–2 for hallucination detection where any material error must be refuted' and explains the default cap of 5. It also provides concrete claim examples. This goes beyond the schema's basic field 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 explicit natural-language triggers ('Is it true that…', 'fact check') and then states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly differentiates from siblings like ask_pipeworx by focusing on fact-checking with a defined verdict taxonomy, and it specifies two distinct execution paths (SEC EDGAR fast path and grounded fallback).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. It also explains how claim types are routed (financial vs. other), but it does not explicitly name an alternative tool for non-factual queries, so the 'when-not' is implied rather than stated.

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