wikiviews

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: default model is free, Anthropic calls are paid directly by the user, and it discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view). This enrich the agent's understanding of external side effects (costs) and output shape.

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

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

The description is three sentences, front-loaded with the primary action and output, followed by payment note and return format. Every sentence contributes meaning; no fluff or repetition of schema fields.

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 compensates by explaining exactly what is returned per model and what the combined view contains. It covers the default behavior, optional key usage, and practical use cases, making the description self-sufficient for an agent without additional documentation.

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, but the description adds meaning beyond the schema: it states the default model ('Workers AI Llama-3.3-70b (free)'), explains the `_apiKey` is required if 'anthropic' is in models, and clarifies that `context` helps disambiguate identical names. This aids correct invocation.

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

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

The description uses a specific verb ('Probe') and names the resource (LLMs) and output (visibility score 0-100), making the tool's purpose unmistakable. It also differentiates from sibling tools by focusing on AI visibility scoring rather than answering questions or scanning competitors.

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 states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and BYO-key behavior for Anthropic. It does not explicitly mention when not to use this tool or name alternative tools, but the context is strong enough to guide appropriate use.

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

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

Annotations already declare the safety profile (readOnly, openWorld, idempotent, non-destructive). The description adds valuable behavioral context: it routes to 5,358 tools, fills arguments, returns structured answers with stable citation URIs, and notes it works on every tier with one fast call. It does not contradict annotations, and the added details go beyond the structured metadata.

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

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

The description is longer than average but well-structured: it opens with the crucial directive ('PREFER OVER WEB SEARCH'), then covers scope, routing, return format, examples, and alternatives in a logical order. Every sentence contributes information, and the use of bold and bullet-like examples improves scannability. Minor redundancy between the domain list and trigger phrases prevents a perfect score.

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

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

Despite having no output schema, the description fully prepares the agent: it explains what the tool does, what kinds of questions to use it for, how it works internally (routing to 5,358 tools), what the return value looks like (structured answer with citations), and when to choose alternatives. For a tool with this level of complexity, the description leaves no critical gaps.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for 'question', and the schema already explains they accept natural language. The description adds examples of valid questions and reinforces the alias flexibility, but it does not provide additional meaning beyond what the schema already contains. Baseline 3 is appropriate because the schema carries 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 identifies the tool as a question-answering router that handles factual queries about real-world data, explicitly listing domains such as SEC filings, FDA data, and economic statistics. It distinguishes itself from siblings by stating it should be preferred over web search and naming alternatives like ask_pipeworx_grounded and deep_research, so its unique role is 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?

This is exemplary guidance. It explicitly states when to use the tool ('START HERE for most questions', 'PREFER OVER WEB SEARCH'), provides trigger phrases ('what is', 'look up', 'find'), gives concrete examples, and explains when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). This leaves no doubt about usage conditions.

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

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

Annotations already declare read-only, idempotent, open-world. Description adds that candidate routing improvements are enabled live when under test, that no candidate is currently active (as of 2026-07-26), and that it is a full working router with no fallback. This gives agents clear expectations about experimental variability and current 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?

Three sentences, front-loaded with the essential beta identity and equivalence to ask_pipeworx. Each sentence adds value: identity, current status, usage guidance, and assurance of full functionality. No wasted words.

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

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

Given the tool's complexity as a live experiment, the description is remarkably complete: current status, experimental behavior, usage, and relationship to stable router. It relies on ask_pipeworx for response shape, but that's acceptable since it's a sibling and explicitly states identical response shape. Minor gap: no description of what the response looks like beyond identity.

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 all six aliases for question. The description only notes 'same arguments' as ask_pipeworx without adding further semantics, 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?

Clearly identifies as a beta version of ask_pipeworx, a universal router over 5,358 tools with identical arguments and response shape. Distinguishes itself from the stable ask_pipeworx and other siblings by emphasizing its experimental status and live candidate testing.

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

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

Explicitly instructs to use exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. States the current state matches ask_pipeworx exactly, eliminating ambiguity. Not mentioning alternatives beyond ask_pipeworx is acceptable given the direct reference.

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, openWorldHint, idempotentHint), the description discloses the exact success and refusal response structures, the refusal_reason enum values, the behavior of extracting only from tool results, and the extra LLM call cost. This provides rich 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?

The description is a dense paragraph but quite long. However, every sentence provides value—purpose, routing, output shape, refusal handling, use cases, and cost trade-off. It is front-loaded with the most critical framing. Slight structural improvements (e.g., bullet points for failure modes) would make it more scannable, but it remains efficient for the information density.

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

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

Despite having no output schema, the description fully specifies the return shape on success and all refusal_reason possibilities. It covers failure modes, use cases, and performance trade-offs, and the annotations cover safety semantics. This description is self-contained for an agent to decide when and how to use the tool.

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

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

Schema description coverage is 100%: all six parameters (question plus aliases) are fully described. The description does not add additional parameter-level semantics beyond what the schema already states, so the baseline of 3 is appropriate. The question parameter is self-explanatory, and the description focuses on tool behavior rather than parameter nuances.

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

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

The description opens with a specific, vivid purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool routes through the same mechanism as ask_pipeworx but then extracts answers strictly from tool results, distinguishing it from the sibling ask_pipeworx. The verb-resource pairing is explicit 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?

Usage guidance is explicit and comprehensive: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also states the alternative: 'prefer ask_pipeworx for casual lookups.' This clearly specifies when to use this tool versus its sibling.

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

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

Goes far beyond the readOnly/openWorld/idempotent annotations. Details resolver contract, low-confidence short-circuiting, market_closed_or_inactive status, fallback attempts, cancellation-rule risk with ev_impact, and warning about 24h market moves. No contradiction with annotations.

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

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

The description is long but well-organized with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Some content overlaps with schema descriptions, but the extra context is generally valuable. Not wastefully verbose despite its length.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly covers input forms, resolution behavior, fan-out logic, response shapes, safety mechanisms, and edge cases. It even provides actionable warnings (e.g., flat-50¢ void settlements) that an agent needs to make correct decisions.

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 describes all three parameters fully (100% coverage) with types, defaults, and examples. The description adds fan-out examples and response shape context, but no additional per-parameter semantics beyond what the schema provides, 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like validate_claim or polymarket_edges by focusing on per-bet research with data fan-out, and states concrete use cases ('should I bet on X').

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

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

Provides explicit use-case guidance ('Use for ...') and practical advice like inspecting resolver contract before trusting analysis. However, it does not explicitly name alternative tools or state when not to use this tool, which would elevate it to a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses specific data sources (SEC EDGAR/XBRL, FAERS, FDA approval counts), fiscal-year handling, sorting by primary metric, and citation URI return format. No contradiction with annotations; this adds substantial behavioral context.

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

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

The description is dense and well-structured, opening with trigger phrases that immediately aid tool selection, followed by functional behavior, per-type details, and output characteristics. Every sentence earns its place; no fluff or repetition.

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

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

For a tool with no output schema, the description compensates by explaining it returns paired data and citation URIs. It covers both entity types, data sources, sorting, fiscal-year edge cases, and efficiency rationale ('replaces 8–15 sequential lookups'), making it complete 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 both parameters, but the description adds significant semantics: 'type' determines which data source is used (company vs drug), and 'values' examples clarify format (tickers/CIKs vs drug names). It also explains how results are sorted, which aids parameter interpretation. While schema coverage is 100%, the description enriches meaning beyond the basic schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases ('Compare X and Y', 'X vs Y'). It distinguishes from siblings by positioning itself as the preferred tool over sequential single-pack lookups, making its purpose unambiguous.

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

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

The description gives explicit when-to-use triggers and instructs 'ALWAYS PREFER' over sequential lookups, which is strong usage guidance. It also differentiates between company and drug types. However, it does not explicitly state when NOT to use the tool (e.g., when more than 5 entities need comparison), leaving a minor gap in exclusion 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 readOnly/openWorld/idempotent annotations, the description discloses pricing tiers, gap handling ('never invented', gaps[]), latency expectations (15-90s), semantic excerpting, contradictions[], hop fields, and citation URI structure. No contradiction with annotations; its readOnly hint is consistent with a research-only tool.

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 the account requirement and every sentence contributes distinct behavioral or usage facts. It could benefit from paragraph breaks or bullet formatting, but 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?

For a complex tool with no output schema, the description covers return packet contents (evidence, confidence, source, fetched_at, citation), gaps and contradictions, fallback to ask_pipeworx for unsupported topics, latency, and access tiers. An agent has enough context 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?

Even though the schema covers 100% of params, the description adds meaningful semantics: depth is elaborated with hop counts, paid tier requirement for 'thorough', gap recovery, and contradictions; question is clarified as 'broad/multi-part is fine'. This goes beyond the schema's enums and brief 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 specifies a concrete verb+resource: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources' with decomposition and parallel routing. It explicitly distinguishes from siblings: 'NOT open-web search' and references ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and fallback behavior, giving clear 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?

Annotations already establish read-only, idempotent, non-destructive safety. The description adds behavioral detail about return structure: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This informs the agent of what to expect and that it eliminates extra lookups, adding value beyond annotations.

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

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

The description is about 60 words, front-loaded with a clear verb+resource statement, followed by usage context and return-value details. Each sentence contributes; no redundant content. Slightly longer than necessary but 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?

Given no output schema, the description compensates by explaining the return values (names, descriptions, schemas with examples) and the 'ready to call directly' behavior. It also covers the discovery use case and domain coverage, 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%, so baseline is 3. The description refers to 'top-N' (relating to limit) and 'describing the data or task' (relating to query), but these are already documented in the schema with example aliases. No additional parameter semantics are provided 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 uses the specific verb 'Find tools' and identifies the resource ('tools') with the context of 'describing the data or task.' It clearly distinguishes this discovery tool from siblings by framing it as a browsing/searching layer over the tool set, fulfilling the purpose clarity criterion.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides a clear usage context and implies when not to use (when a single answer is already known).

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

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

Annotations already declare read-only/idempotent, but the description adds meaningful behavioral details: it fans out across multiple sources, returns specific fields with sort order, mentions the USPTO patents API sunset and soft-fail behavior, and lists the fallback chain (GDELT→GNews). This goes well beyond what annotations provide.

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

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

The description is dense but well-structured: opens with example queries, states the core purpose, lists fan-out sources and return fields, and ends with parameter constraints. It could be slightly more scannable, but every sentence contributes useful information.

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

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

Given the tool's complexity (8+ data sources) and lack of an output schema, the description covers all essential aspects: input format, unsupported inputs, return fields, ordering, source failures, and fallback behavior. It is self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already explains both parameters clearly. The description adds value by reinforcing the value format with examples (ticker/zero-padded CIK) and explicitly stating that names are not supported, which helps prevent misuse.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company' in one call, with a specific verb ('profile'), target resource, and explicit scope. It distinguishes itself from sibling tools by positioning as the preferred holistic lookup over chained single-pack queries.

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: 'ALWAYS PREFER... when the user asks for a holistic view.' Also gives alternatives ('use resolve_entity first if you only have a name') and names unsupported inputs, giving clear context for selecting this tool over siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the main behavioral traits. The description adds domain context (previously stored memory) and motivation for deletion but does not provide further operational details like error behavior. Given annotations carry the safety burden, a 3 is appropriate.

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

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

The description is two sentences, with the first defining the purpose and the second covering usage and complementary tools. Every sentence serves a function, and it's appropriately concise.

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 destructive tool with good annotations, the description covers the core purpose, usage scenarios, and relationships to sibling tools. No output schema is needed, and the simplicity of the tool means no additional context is required.

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

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

Schema description coverage is 100%, so the description does not need to explain the parameter further. The text merely restates 'by key' which adds no new meaning beyond the schema's 'Memory key to delete'. Baseline 3 applies.

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

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

The description uses a specific verb 'Delete' and identifies the resource as 'previously stored memory by key', making the function crystal clear. It also hints at complementary tools (remember and recall), further distinguishing its role as the deletion 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 explicitly provides conditions for use: when context is stale, task is done, or sensitive data needs clearing. It also references pairing with remember and recall, effectively indicating alternatives for other memory operations.

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 behavioral traits beyond the annotations by detailing the fetch-extract-emit workflow and emphasizing the output is a single text blob for site-root placement. It adds process context without contradicting the read-only, idempotent annotations.

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

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

The description is three sentences with the main purpose front-loaded, followed by the process and output format. Every sentence adds useful information and there is no redundancy.

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

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

Given the tool's simplicity, the strong annotations, and full schema coverage, the description covers all essential context: purpose, process, output, and use cases. No output schema is needed because the description explains the text blob output.

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

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

The input schema fully covers both parameters (url and max_links) with clear descriptions. The tool description does not add extra semantic detail about parameters, so it does not go beyond the schema baseline.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb+resource. It distinguishes itself from sibling tools by naming the exact output artifact and listing specific use cases like client indexing and competitor audits.

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 concrete contexts in which to use the tool ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), but it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds the date-range scoping and daily granularity, but no additional behavioral traits like return format or pagination. With annotation coverage, a 3 is appropriate.

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

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

Two short sentences with no redundancy. The first sentence states the purpose and scope; the second provides a key validation requirement. Every word earns its place.

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

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

This is a simple, read-only tool with three fully described parameters, an output schema, and comprehensive annotations. The description is sufficient for correct selection and invocation without additional 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 description coverage is 100%, and each parameter is already described with format and example. The tool description reinforces the date format but does not add significant meaning beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Get') and identifies the resource ('daily pageview counts for a specific Wikipedia article') with scope ('over a date range'). This clearly distinguishes it from siblings like get_project_views and get_top_articles.

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 this tool: when you need pageview counts for a specific Wikipedia article within a date range. It does not explicitly provide alternatives or exclusions, but the context is strong given the sibling tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds only a date format reminder already present in the schema, with no additional behavioral context such as rate limits or edge cases. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that conveys purpose, scope, and a key constraint without any superfluous words.

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

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

For a simple two-parameter tool with full schema descriptions, rich annotations, and an existing output schema, the one-sentence description is complete. It covers what the tool does and its scope without needing to explain return values.

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

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

Input schema coverage is 100% and both parameters have descriptive text with examples. The description only reiterates the YYYYMMDD format, adding no new meaning 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 the action ('Get'), the resource ('aggregate daily pageview totals for all of English Wikipedia'), and the scope ('over a date range'). This distinguishes it from sibling tools like get_article_views, which focus on specific articles.

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 makes clear that this tool is for site-wide pageview totals for English Wikipedia, implying it should be used when project-level data is needed. However, it does not explicitly name alternatives or provide exclusions, so it falls 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?

The description adds behavioral context beyond the annotations by stating a return limit of up to 1000 articles and ranking by view count, which is not disclosed in the annotations. It also implies read-only behavior consistent with readOnlyHint. No contradictions noted.

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 one succinct sentence that immediately states the core function and key output characteristics. It is front-loaded with the action and resource, with no filler or redundant information.

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

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

Given the simplicity of the tool, the presence of a rich input schema, and comprehensive annotations, the description covers the necessary context: what is retrieved (most viewed articles), the temporal scope (specific day), and an important output detail (limit of 1000). The describing of the output is sufficient despite the existence of an output schema, as it does not over-explain.

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?

Since the schema already provides descriptions for all three parameters (year, month, day) with 100% coverage, the description doesn't need to add parameter details. It does reinforce that the date parameters target a 'specific day', but this is minor added value. Baseline 3 is appropriate.

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

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

The description clearly states it gets the most viewed Wikipedia articles for a specific day, using the specific verb 'Get' and resource 'most viewed Wikipedia articles'. It distinguishes itself from sibling tools like get_article_views, which focus on individual article view counts, and get_project_views, which focus on project-level 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 provides clear context: use this tool when you need the top articles for a specific day. It does not explicitly name alternatives or exclusions, but the specificity of 'most viewed' and 'for a specific day' strongly implies its niche. The sibling list further clarifies distinctions, though not referenced.

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

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

Annotations already declare readOnlyHint and non-destructive, so the description adds value by detailing return fields and scope (caller's active subscriptions). No contradiction.

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

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

Two sentences: purpose and usage. Front-loaded and no filler.

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

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

Simple tool with rich annotations and schema; description covers return format and usage context. Fully adequate.

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

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

Schema coverage is 100% with a clear description for include_inactive. The tool description doesn't add beyond the schema, but doesn't need to.

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 'List the caller's active subscriptions' with a specific verb and resource, and clarifies scope. It also lists return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description provides clear use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This gives context for when to use, but doesn't explicitly name alternative tools or 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?

Annotations are all false and provide no behavioral hints, so the description carries the burden. It discloses useful behavioral traits: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, and that the team reads digests daily with signal affecting roadmap. This goes beyond the bare schema and helps the agent understand side effects and constraints, though it doesn't detail what happens after submission (e.g., confirmation or async processing).

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

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

The description is four sentences, front-loaded with purpose, then usage, then message guidance, then context about team/rate limit. No word is wasted; every sentence earns its place. It is appropriately sized for the tool's simplicity and rich with substantive information.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description covers purpose, exact usage triggers, message formatting, rate limits, and quota impact. The optional context object is self-explanatory via schema. No gaps remain that would leave an agent uncertain about when or how to invoke this tool.

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

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

Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds valuable guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which helps the agent formulate the 'message' parameter correctly. This extra semantic guidance for message construction places it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this feedback tool from sibling research and subscription tools by being the only one focused on submitting feedback to the Pipeworx team. The phrasing covers the full scope of feedback types (bug, feature, data_gap, praise).

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells users what not to do (don't paste the end-user's prompt) and adds context about rate limits and quota impact, which helps decide if/when to invoke.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavior context: it discloses the data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h depending on window). No contradictions.

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

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

The description is three sentences: front-loaded with the core output, then a numbered list of use cases, then extra context about data source and caching. Every sentence contributes value and there is zero 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 one optional parameter and no output schema, the description fully covers what the agent will get (top tools, top packs, call volume), the window options, and important caveats (caching, no PII). It is 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?

Schema coverage is 100% with only one parameter ('window'), and the schema description already explains the enum options and the trade-off between hot and steady-state signals. The tool description repeats this info but adds no new semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Returns') and resource ('top tools, top packs, and total call volume') with a precise scope: what other AI agents are calling on Pipeworx. It clearly distinguishes from siblings like get_top_articles or discover_tools by focusing on agent call trends, not general articles or tool discovery.

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

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

The description provides three explicit use cases with numbers, giving clear context on when to use the tool. It does not explicitly name alternative tools or state when not to use it, but the use cases are specific enough to guide selection among the large sibling list.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description enriches behavioral understanding significantly. It discloses concrete thresholds (deviation >3pp triggers signals), internal filters (placeholders, Jaccard ≥0.30), and the fill-check workflow against live CLOB depth. It also explicitly warns that realizable_edge_pp ≤ 0 means the edge is not realizable in the book. This goes far beyond what annotations convey and aligns with them without contradiction.

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

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

The description is long and dense, but it is well-structured with semantic labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode breakdowns. Every clause delivers useful operational detail, so it earns its length. The only reason it doesn't get a 5 is that it could be slightly tighter; some redundancy exists (e.g., repeating partition check examples), but the organization mitigates the length issue.

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

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

Given the tool's complexity, two optional parameters, lack of an output schema, and rich annotations, the description is exceptionally complete. It specifies the exact response structure (opportunities[] with fields, partition_check object with fields), the market scope (~200 top markets by weekly volume), the notion of overround at book versus last-trade, and how to handle signals. No important operational aspect is left unexplained.

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 a description, so baseline is 3. The tool description adds substantial semantic depth beyond the schema: it explains what 'event' mode does (walks child markets, checks date-axis/threshold-axis ordering) and what 'topic' mode does (searches related events, flattens markets, runs comparator on union). It also provides concrete examples of valid slugs and seed questions. This elevates parameter understanding well above the schema alone.

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

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

The description opens with a specific and actionable verb-plus-resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the tool's unique method and differentiates it from sibling tools by detailing three distinct modes (trending_scan, event, topic), each with concrete use cases. This is far more than a tautology and explicitly distinguishes what this tool does relative to other Polymarket-related siblings.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event... or topic' and then elaborates on the benefits of cross-event mode over single-event mode. It also directs users to a sibling tool ('For custom sizing use polymarket_fill_risk') and tells them when not to trade based on fill check results ('do not trade it'). This is a model of usage clarity and alternative differentiation.

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

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

Annotations already declare this as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context: caching at the KV level, the 24h-move warning, the exclusion of Fed candidates from ranking, and the diagnostics structure that explains why segments are empty. This goes well beyond the annotation baseline.

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

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

The description is extremely long and dense, including details like per-sport α values and placeholder-slug filter rules that are not necessary for an agent to invoke the tool correctly. It lacks a concise summary and front-loading; the reader must wade through many internal implementation details before reaching the most actionable response-format information. This is over-specification rather than conciseness.

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 must explain the return structure. It does so thoroughly: top-level fields (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume), and the 24h warning. It also explains filter knobs and diagnostics, making the tool's behavior predictable even without structured output documentation.

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 schema already documents all 9 parameters. The description adds higher-level meaning by grouping tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and explaining their purpose ('drop opportunities where edge isn't realizable'). It also clarifies the relationship between min_kelly and min_partition_leg_kelly for basket trades, adding value beyond the 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 a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and distinguishes itself from sibling tools by focusing on discovery without paging hundreds of markets.

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

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

The description gives a clear use case ('what should I bet on today') and explains why agents would use it (avoids paging hundreds of markets). It doesn't explicitly name alternative sibling tools or state when not to use it, but the context is sufficient to infer appropriate usage.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing response structure (tracked, expired, snapshot_dates), explaining edge_pp_net signedness, revealing that snapshots are written on cache-miss, and stating limitations like the 60-day TTL and daily-close computation. This provides substantial behavioral context that annotations alone do not cover.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with the core question. Every sentence adds relevant detail, though it is dense and could be slightly more concise without losing value.

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

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

Given there is no output schema, the description completely specifies return values (tracked, expired, snapshot_dates), explains edge_pp_net semantics, covers limitations (TTL, daily closes), and addresses data gaps. It is sufficiently complete for an agent to understand what the tool returns and its constraints.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section merely restates the schema (days lookback default 14, window snapshot family), adding no new semantics. The RESPONSE section indirectly relates days to 'prior snapshots' but does not add parameter-specific detail beyond the schema.

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

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

The description clearly states the tool's purpose: it provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. This specific verb+resource distinguishes it from siblings like polymarket_edges, which focuses on current edges rather than historical persistence.

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

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

The description gives clear context for when to use this tool: when you need to understand edge longevity and decay over time, contrasting fresh vs. old edges. However, it does not explicitly name alternatives or provide exclusion criteria (e.g., 'if you only need current edges, use polymarket_edges'). The usage context is clear but lacks explicit alternative guidance.

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

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

Annotations already declare readOnly and idempotent, and the description adds significant behavioral detail: 'walks the ladder', returns slippage_pp and verdict, and warns that 'partial basket fills convert an arb into an unhedged directional position.' This goes well beyond the annotations to explain how the tool behaves and its risk implications.

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

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

The description is long but information-dense, front-loading the core purpose and then systematically covering both modes, outputs, and usage rules. It could be improved with sectioning, but every sentence adds value and the complexity of dual modes justifies the length.

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

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

With no output schema, the description thoroughly enumerates all return fields for both single-market and basket modes, including verdict values, thin_legs[], and forced_directional_risk. It also explains size_usd clamps and mode requirements, leaving few 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?

While the schema covers parameter types, the description adds critical mode-specific semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode, but 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains the auto-default logic for side, which is not in the schema.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, with specific verbs and resources. It explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating it is a pre-trade risk check, not a signal generator.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, and partial fills create unhedged directional risk), providing clear context and 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 indicating read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral context: two response modes, safety fields, compatibility warnings with two distinct cases, temporal alignment semantics, and skipped_cross_type/subtype counters. It details edge cases like 'Kalshi range_bucket point-in-time vs Polymarket cumulative_threshold touch-anywhere — no arb exists,' which goes well beyond annotation hints.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence adds substantive detail, though it reads as a dense wall of text. The caps-labels help scanning, but a bulleted format could improve readability slightly.

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

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

Since there is no output schema, the description fully explains the return envelope: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp' and the compatibility_warning/temporal_alignment fields. It covers all key edge cases for a complex cross-venue comparison tool with three optional parameters, making it complete enough for an agent to use correctly.

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

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

The input schema already describes all three parameters (100% coverage), but the description enriches their meaning significantly. It explains that topic auto-fetches pre-mapped events and that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. It also clarifies the topic enum values in context, adding semantic depth beyond bare schema descriptions.

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

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

The description states the tool computes a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource+scope. It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than a single venue's arbitrage.

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

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

The description explicitly outlines two usage modes ('TWO MODES: (1) topic — ... (2) explicit ...') and provides examples. It warns that 'pre-mapped ≠ tradeable' and explains when compatibility_warning fires, giving clear guidance on when results are meaningful. It does not explicitly name alternative sibling tools, but the mode distinctions and caveats effectively direct usage.

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

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

Adds useful behavioral context beyond annotations: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and describes the optional key behavior. 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?

Three focused sentences, front-loaded with the primary action. Every sentence contributes either use case, examples, or pairing instructions, with no redundancy.

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

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

For a simple single-parameter memory retrieval tool with solid annotations, the description covers purpose, usage, and scoping. It could mention behavior for missing keys or return format, but the current level is sufficient for confident tool selection.

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 the key parameter fully (100% coverage). The description reinforces it by restating the omit-to-list behavior and providing examples of key meanings, but adds no new syntactic or format details.

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 the tool retrieves a saved value or lists all keys, with a specific verb and resource. It also distinguishes itself from sibling tools by explicitly pairing with 'remember' and 'forget'.

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

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

Gives explicit usage context: 'look up context the agent stored earlier' with concrete examples. It names the sibling tools for saving/deleting, providing clear when-to-use guidance.

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

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

Annotations declare readOnlyHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones' — a persistent state mutation. This directly contradicts the read-only annotation, making the safety profile inconsistent. The description also lacks discussion of auth requirements or feed persistence behaviors.

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 action and return payload. The only slightly extra detail is the registry URL, but it is justified for script/dashboard users; no filler or repetition.

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

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

The description explains what is returned, how to filter, the mark_read side effect, and polling suitability. It omits unread_only semantics but the schema covers it; without an output schema, the payload description is adequate. The contradiction with annotations is the main gap.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds concrete semantics: example type 'sec_8k', ISO timestamp for since, and the mark_read side effect. This extra guidance pushes it above baseline.

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

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

Description opens with 'Pull fired events from your subscription feed' — a specific verb+resource that clearly distinguishes from sibling tools like recent_changes and list_subscriptions. It also specifies the return payload (source, citation_uri, raw event) and filtering options, leaving no ambiguity about what the tool does.

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

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

Provides contextual guidance: filtering by type/since, polling suitability, and an alternative URL for scripts/dashboards. However, it does not explicitly differentiate when to use this tool over sibling tools such as recent_changes or list_subscriptions, nor does it state when not to use it.

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

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

Beyond annotations, the description discloses significant behavioral details: fan-out to SEC EDGAR, GDELT→GNews fallback logic, USPTO soft-failure due to PatentsView API sunset, and accepted `since` formats. This adds real value over the readOnly/idempotent hints.

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

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

Although the description is long, every clause conveys essential information: query patterns, source fan-out, fallback behavior, soft-fail, date formats, return structure, and alternative tool. 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 complexity (multiple upstream APIs, fallbacks, soft-fail) and lack of an output schema, the description is remarkably complete. It explains return shape (changes[] grouped by source, total_changes, citation URIs) and when to use a sibling tool, leaving few gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds above baseline by giving concrete examples for `since` (7d, 30d, 3m, 1y), a recommendation to use '30d' or '1m' for monitoring, and clarifying the CIK zero-padding. This is helpful but not a huge leap beyond schema.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, with specific verbs like 'what's new' and 'change feed'. It also distinguishes itself from sibling entity_profile by contrasting dynamic changes with static profiles.

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

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

Provides explicit usage context with natural language query examples and an explicit alternative: 'Use entity_profile instead when you want the static profile...'. This gives both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=false. The description adds meaningful behavioral context beyond annotations: key-value storage scoped by identifier, persistence differences for authenticated vs anonymous users (24 hours), and the pairing pattern with recall/forget. No annotation contradiction.

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

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

Four sentences, front-loaded with the core purpose in the first sentence. Each subsequent sentence adds needed context: usage triggers, storage mechanism, retention policy, and companion tools. No redundant information.

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

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

Covers the tool's purpose, when to use, storage semantics, persistence behavior, and related operations. Given the tool's simplicity (two parameters, no output schema), it is fully self-contained for an agent to invoke correctly.

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

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

Input schema provides complete descriptions for both key and value (100% coverage), including examples. The description only refers to 'key-value pair' without adding new constraints or format details, so baseline 3 applies.

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

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

The description opens with 'Save data the agent will need to reuse later,' clearly stating the verb (save) and resource (data for later reuse). It distinguishes itself from sibling tools recall (retrieve) and forget (delete) by explicitly naming them, and clarifies cross-session persistence.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also specifies the complementary tools: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it discloses return values (ticker, CIK, RxCUI, etc.), internal cascading across lookup endpoints, auto-disambiguation, and citation URIs. It stops short of describing failure modes or ambiguity handling, but the added detail is substantial.

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 a tool with two entity types. It front-loads example queries, then clearly organizes supported types and outputs. While a bit dense, every sentence adds value, and the structure helps an agent quickly grasp the tool's primary use case.

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 lookup tool with no output schema, the description covers return formats, input variations, source systems (SEC EDGAR, RxNorm), and citation URIs. It also explains the cascade behavior, giving an agent enough context to invoke correctly and interpret results. Given the tool's complexity and annotations, this is complete.

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

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

Schema coverage is 100% with both parameters described. The description further enriches 'value' with concrete examples (AAPL, 0000320193, ozempic) and adds type-specific semantics (company vs drug), including the 10-digit CIK format and RxNorm sources. This goes beyond the schema, which only gives basic descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific verbs like 'resolve' and explicit examples ('ticker for', 'CIK for'). It distinguishes from sibling tools by focusing on name-to-ID lookup, returning specific identifiers and citation URIs for company and drug types.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also mentions that the tool replaces 2-3 manual lookups, setting expectations about its efficiency. While alternatives aren't named, the 'FIRST' prioritization and type-specific details make usage context clear.

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

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

Adds meaningful behavior beyond annotations: it probes each entity via ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, and signal density. Also discloses external API usage for anthropic. Annotations already cover read-only/idempotent safety, so the description enriches rather than repeats.

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 well-structured sentences with a front-loaded purpose statement. Every sentence contributes: mechanism, use case, and output format. No fluff or repetition of schema 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?

Despite lacking an output schema, the description clearly states the return elements (ranked list, score, confidence, signal density). It covers the use case, probe method, optional model handling, and entity role, making it sufficiently self-contained for invocation decisions.

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 applies. The description adds context (e.g., 'your brand + N competitors') but does not significantly expand on the schema's parameter descriptions. It mirrors rather than deepens the semantic meaning.

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

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

Clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb, resource, and scope. Names the underlying probe (ai_visibility_check) and the output (ranked list), distinguishing it from single-check sibling tools.

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

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

Explicitly frames the tool for competitive AI-marketing audits and provides a concrete example. It implies when to use it (multi-entity comparison) vs. the single-entity ai_visibility_check, but does not explicitly name alternatives like compare_entities or state when NOT to use it, leaving a small gap.

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

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

While annotations already declare readOnly/idempotent, the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. It also explains the fan-out nature and return structure, exceeding annotation coverage.

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 provides unique, essential information: composite behavior, use cases, return fields, ecosystem limitation, and failure handling. No fluff or redundancy; well-structured and front-loaded.

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

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

For a composite tool with no output schema, the description is remarkably complete. It explains the exact return fields, latency behavior, ecosystem scope, and graceful degradation. No significant gaps remain given the complexity and available annotations.

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

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

Schema coverage is 100% with both parameters having clear descriptions. The description reinforces the 'latest published version' default but adds no new meaning beyond the schema. Baseline 3 is appropriate given 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 clearly states the tool is a composite check for 'should I add this npm package to my project' in one call, specifying it fans out to deps.dev and bundlephobia. It distinguishes from siblings by explicitly limiting to NPM ecosystem in v1 and noting alternative tools for other ecosystems.

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

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

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 exclusion guidance for non-NPM ecosystems and describes degrade behavior, making it clear when to use this tool versus deps.dev directly.

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

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

Beyond annotations, discloses return format (character offsets, similarity scores), algorithm (BGE-base-en + cosine over 500-char windows), and truncation at 200K chars with a flag. This adds substantial context beyond the readOnly/idempotent hints, 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?

Dense but efficient; all sentences carry distinct information: when-to-use, output, pairing, algorithm, and limits. Slightly longer than minimal but well-structured front-loaded with purpose.

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

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

For a 3-param tool with no output schema, the description explains return shape, usage context, limitations, and integration with sibling tools. An agent can confidently invoke this tool correctly without needing extra inference.

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 clear descriptions, but the description adds concrete examples for query ('supply-chain risk') and text (SEC 10-K body), plus semantics of top-N passages and offsets. This elevates understanding beyond schema alone.

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

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

Specific verb 'search' + resource 'fetched record'; description states output passages with offsets and similarity scores. It distinguishes from siblings by emphasizing searching inside already-pulled text rather than fetching new 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?

Explicitly states 'Use when the record is too big to cram into the prompt' and names the complementary tool ask_pipeworx_grounded, explaining the division of labor. This gives clear when-to-use and alternative guidance.

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

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

The description discloses substantial behavioral details beyond the annotations: account requirement, inability for anonymous/BYO to persist subscriptions, supported event types, delivery channel semantics (feed always-on, email/sms/webhook), SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 consecutive failing runs. This exceeds what the annotations (readOnly, destructive, idempotent, openWorld) already communicate.

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 serves a purpose: purpose, return value, prerequisite, supported types with examples, and delivery options with limits. It is front-loaded with the main action and contains no fluff, making it appropriately concise 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 no output schema, the description compensates by explaining the return value (subscription id), prerequisites, type-specific parameter patterns, delivery channel behaviors, and failure mode (webhook auto-disable). It provides a complete operational picture for safe and effective invocation.

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

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

Schema coverage is 100%, but the description adds interpretative meaning beyond raw schema: e.g., 'items:["5.02"] = officer change', 'Polymarket↔Kalshi cross-venue mispricings', and delivery constraints like phone verification and rate cap. It helps the agent understand the real-world intent of each parameter.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', and explains it returns a subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe, and the inclusion of supported types further clarifies its purpose.

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

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

The description provides context on when to use the tool (proactive monitoring), prerequisites (OAuth account), and how to consume the feed via recent_alerts or a registry URL. However, it does not explicitly mention alternatives like list_subscriptions or unsubscribe, so it stops short of a full 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 cover readOnly and idempotent hints, and the description adds meaningful behavioral context: returns category-bucketed example questions, each with tool + argument shape, drawn from a live catalog of thousands of tools. It also explains call variations (no args vs. topic). No contradiction with annotations.

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

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

The description is long but well-structured: starts with natural-language user queries, then the core purpose, then return details, then call instructions. Every section contributes onboarding value, and the front-loaded examples make it instantly 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 tool with a single optional parameter and no output schema, the description fully covers what it returns, the categories included, the source catalog, and how to invoke it (with and without topic). It even gives usage guidance relative to sibling tools, making it contextually 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%, so baseline is 3. The description adds value by giving concrete examples for the `topic` value ('finance', 'pharma', 'betting') and explaining that omitting it yields a cross-category spread, enhancing 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 uses a specific verb ('suggest questions') and identifies the exact resource (Pipeworx capabilities), explicitly positioning it as the onboarding entry point. It distinguishes from siblings by naming meta-tools like ask_pipeworx, entity_profile, and compare_entities, clarifying its unique role.

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

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

States explicitly when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains the optional `topic` parameter for focusing and contrasts with alternatives (learning how to call meta-tools), providing clear usage context.

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

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

Beyond the annotations (idempotentHint, destructiveHint false), the description discloses that cancellation is ownership-enforced and performs a deactivation rather than deletion, preserving historical events for recent_alerts. This adds valuable behavioral context the annotations alone don't provide, with no contradiction.

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

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

The description is two sentences, front-loaded with the core action and no wasted words. The first sentence states what it does; the second efficiently covers constraints and behavioral effects, making every sentence meaningful.

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 tool with annotations covering idempotency, the description provides sufficient context: ownership enforcement, soft-delete behavior, and impact on recent_alerts. It omits the return value, but the simplicity of the operation and annotation coverage make it largely complete.

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

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

The schema already fully describes the single parameter ('Subscription id (uuid) returned by subscribe'), and the description only restates that cancellation is by id without adding new parameter-specific details. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from siblings like subscribe and list_subscriptions. The title 'Unsubscribe from Alerts' reinforces the purpose without ambiguity.

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

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

The description provides clear context by explaining the ownership restriction ('you can only cancel your own subscriptions') and the soft-delete behavior, which helps the agent understand when it's appropriate. However, it does not explicitly name alternatives or exclusions, so usage guidance is context-driven rather than directly comparative.

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

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

Annotations indicate read-only, non-destructive, idempotent. The description adds rich behavioral detail: the fast path for company financials, the fallback grounded pipeline, the verdict categories, and the citation+reasoning output. It also declares that it 'replaces 4–6 sequential calls,' which is useful operational 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 not bloated; it opens with example queries and quickly moves to the core use case and routing logic. Some phrases are redundant ('grounded pipeline — routed to the right live source, answered with verbatim evidence, then judged') but overall it earns its length.

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

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

For a complex tool with no output schema, the description covers the input format, output verdict options, evidence/citation behavior, and latency tradeoff (replacing multiple calls). It lacks explicit error/edge-case examples but is substantially complete given 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?

Schema coverage is 100%: both 'claim' and 'tolerance_pct' have detailed descriptions, including examples and value ranges. The tool description reiterates the tolerance concept but doesn't add new parameter semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description uses explicit verbs like 'verify', 'check', 'confirm or refute' and specifies the resource: natural-language claim verification against authoritative sources. It also distinguishes itself from generic research tools by describing the two routing paths, making its unique scope clear.

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

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

It provides an explicit trigger phrase: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for financial vs non-financial claims, giving clear context. However, it doesn't explicitly name alternative sibling tools or state when not to use it, so it's slightly below full marks.

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