catfacts

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable operational behavior: defaults to a free Workers AI model, requires a BYO Anthropic key with direct cost, and returns per-model score/confidence/signals/raw_response plus a combined view. 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 compact sentences, front-loaded with the main function. Every sentence adds functional value (purpose, defaults/cost, return format and use cases), with zero 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?

The description is complete for this tool: full schema descriptions, strong annotations, clear return shape, and explicit use cases. No output schema exists, but the described per-model structure and combined view are sufficient for an agent to understand expectations.

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

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

Schema coverage is 100% for all 4 parameters. The description further clarifies the models/_apiKey relationship by noting the default free model and BYO key cost, which adds meaning beyond the schema. It also helps understand the output that parameters influence.

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+object: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes the tool from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on cross-model visibility scoring.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which tells an agent when to invoke it. Though it doesn't name specific alternative tools, the context is clear enough to guide selection.

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

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

It discloses meaningful behavioral traits beyond the annotations: automatic routing to thousands of sources, argument filling, and returning stable pipeworx:// citation URIs. The readOnly/idempotent hints align with the description, and no contradiction exists, though it does not cover failure modes or ambiguity handling.

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

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

The description is front-loaded with the most important guidance and uses examples efficiently. It is somewhat long and the final breaking-news sentence is awkward, but most content earns its place given the tool's broad scope.

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-required-parameter tool with readOnly annotations and no output schema, the description covers scope, domain coverage, source routing, citations, and trigger language. It is sufficient for an agent to select and call the tool correctly, though it could briefly note limits or fallback behavior.

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 'question' and its aliases well, so the baseline is 3. The description adds value by specifying the kind of natural-language input expected and giving concrete example questions, which helps an agent phrase requests appropriately.

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 a natural-language question router over authoritative sources, with a specific verb ('routes'), resource ('5,798 tools across 1517 verified sources'), and many concrete examples. It is unambiguous about what the tool does, though it does not distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives strong contextual guidance: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is', 'look up', 'find', and 'START HERE for most questions'. It makes the primary use case very clear, but it does not explicitly describe when not to use the tool or name alternative siblings such as deep_research or compare_entities.

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

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

Annotations already indicate a read-only, idempotent, non-destructive tool, and the description adds substantial behavioral context beyond that: candidate routing improvements are enabled live only when one is under test, no candidate is currently active, the tool currently matches ask_pipeworx exactly, and it falls back to nothing because it is a full working router. This is excellent disclosure of the experimental nature and current operational state, with no contradiction of annotations.

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

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

The description is longer than average but every sentence contributes: beta status, identity with ask_pipeworx, live-candidate behavior, current state, usage direction, comparison purpose, and the 'full working router' reassurance. It is front-loaded with the most important distinction and is structured logically, though it could be trimmed slightly without losing meaning.

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

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

For a beta alias tool with no output schema, the description covers the critical context: what it is, that it is currently identical to ask_pipeworx, how to use it, and what experimental behavior means. It intentionally defers response-shape detail to ask_pipeworx rather than restating it; this is acceptable given the sibling relationship, but it leaves an agent without direct access to ask_pipeworx's description slightly under-informed.

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 the parameters with 100% coverage, including aliases for the required question field. The description adds that the tool has the 'same arguments' as ask_pipeworx, which is mildly helpful, but it does not enrich the meaning of individual parameters beyond what the schema already provides, so the schema-carrying 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 is specific and immediate: it identifies the tool as a beta version of ask_pipeworx, an identical universal router over 5,798 tools with the same arguments and response shape. It clearly distinguishes this tool from the stable ask_pipeworx by labeling it the experimental edge with candidate routing improvements, so an agent can tell them apart.

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

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

"Use it exactly like ask_pipeworx when you want the newest routing" gives an explicit usage condition, and the description explains that results are compared against the stable router to decide merges. It lacks an explicit when-not-to-use statement, such as 'prefer ask_pipeworx for stable production use,' but the context is clear enough.

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 well beyond the readOnlyHint/idempotentHint annotations by disclosing the full behavioral contract: internal routing pipeline (5,798 tools, 1517 sources, argument filling, fetching), the success response shape with evidence as verbatim quote, and the explicit refusal taxonomy (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the cost trade-off of an extra LLM call. 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 core purpose is front-loaded in the first sentence, and every subsequent sentence earns its place: differentiation from siblings, return contract, refusal reasons, usage policy, and cost trade-off. It is dense, but the refusal-code enumeration and cost note are operationally necessary for correct agent behavior rather than padding.

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

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

With no output schema present, the description carries the full burden of return-value disclosure and fully meets it — detailing both the success shape ({answer, evidence, confidence, source, fetched_at}) and all refusal variants. Combined with 100% schema coverage for parameters and annotations covering the safety profile, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100% — the schema fully documents the single conceptual parameter 'question' and its six aliases. The description adds contextual framing about what kinds of questions suit this mode (high-stakes reads) but no additional parameter syntax or format semantics, so the baseline of 3 applies.

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

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

The description opens with a precise purpose — 'Hallucination-resistant answer mode for high-stakes reads' — identifying a specific verb, resource, and behavioral constraint. It explicitly differentiates itself from the sibling ask_pipeworx by name ('Same routing as ask_pipeworx') and clarifies what makes this mode different: it extracts answers using ONLY what the tool result contains.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also states the exclusion rule — 'prefer ask_pipeworx for casual lookups' — backed by a concrete cost rationale (one extra LLM call).

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses major behaviors: low-confidence matches short-circuit with status, closed markets skip fan-out, wide spreads carry tradeability warnings, and resolution-rule risk with refund_50_50. These are genuine behavioral traits that help agents anticipate side effects and edge cases.

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

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

The description is more verbose than typical tools, but it is well-structured with clear section headers and front-loaded purpose. Every section (classifiers, fan-out examples, resolver contract, safety) adds distinct value, so the length is justified though not perfectly 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?

With no output schema, the description carries full burden for return values, and it delivers: market fields, analysis fields, evidence keys, resolver contract, parent_event extraction, news fallback, and safety behaviors. It also covers edge cases like cancellation rules and illiquid markets, making it complete for a complex research 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 already documents all three parameters with detailed descriptions and examples (100% coverage). The description adds fan-out context but does not add meaning beyond what the schema's parameter definitions already provide, 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?

Description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on evidence gathering and explicitly stating use cases ('should I bet on X', 'what does the data say about Y').

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

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

The description provides explicit use cases for when to invoke the tool ('Use for...') and shows fan-out examples for different bet categories. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is clear enough to guide agent selection.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL vs FAERS), specific metrics pulled, off-calendar fiscal-year handling, result sorting, and citation URI output. This gives substantial behavioral context the annotations alone would 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 dense and front-loaded with common query patterns before the core statement, with every sentence carrying useful information. However, it is a long single paragraph that could be better segmented for scannability.

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

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

With no output schema, the description compensates by summarizing the return format (paired data + citation URIs), sorting behavior, scope (2–5 entities), and the tool's advantage over sequential lookups. It covers key edge cases like off-calendar fiscal years, making it sufficiently 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%, including enum descriptions and array constraints. The description adds meaningful semantics by specifying what each entity type pulls (company: 10-K financial metrics; drug: adverse-event/FDA/trial counts) and notes sorting by primary metric, though it leaves 'primary metric' somewhat underspecified.

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 names a specific verb+resource ('side-by-side comparison of 2–5 companies or drugs') and immediately distinguishes itself from sibling single-entity lookups. It clearly states this is the preferred tool for comparison queries and gives concrete trigger phrases.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use rule and exclusion of the alternative approach. The trigger examples ('X vs Y', 'rank these companies') further guide when the tool is appropriate.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, so the description's job is to add detail, and it does: it discloses parallel decomposition across 5,798 tools, the exact findings packet fields, gaps[] for unanswered facets, the never-invented guarantee, contradictions[], semantic excerpting of large records, and latency windows. No annotation is contradicted.

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 major clause carries operational value—account requirement, fallback tool, grounding, not-open-web, output schema, depth nuances, and latency. The most critical operational facts are front-loaded, though some depth details duplicate what the schema already states.

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

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

With no output schema, the description fully specifies what the agent will receive: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. Auth requirements, latency, input constraints, and usage guidance are all present, so an agent can invoke and interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by giving expected latency per depth (15-60s, thorough up to ~90s), clarifying the paid plan requirement for 'thorough', and re-emphasizing that the question can be broad/multi-part because decomposition is the point. That is meaningful beyond the schema's existing text.

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

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

States a specific verb ('research') and a specific resource ('Pipeworx's 1517 STRUCTURED data sources'), then explicitly differentiates itself from open-web search and from sibling ask_pipeworx. The description makes clear it is a multi-source research tool for broad/multi-part questions, giving the agent a decisive usage profile.

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

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

Explicitly says to use ask_pipeworx instead when not signed in or for a single lookup, and identifies itself as best for broad/multi-part questions over structured data. It also gives example questions and a clear condition ('If you are not signed in') that makes the alternative selection unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful context about the return format (top-N tools with schemas and curated examples) and the 'ready to call directly' behavior, which is beyond what annotations provide.

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

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

The description is somewhat long due to the extensive domain list, but every sentence earns its place: it states purpose, gives usage context, and explains output behavior. It is front-loaded with the core verb and resource.

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

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

Since there is no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and full input schemas. It also provides the important context to call this tool first when many tools are available, making it complete for decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the concept of 'top-N' and 'query as natural language description' but these are also present in the schema. It does not provide meaningful extra parameter-level detail.

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 'Find tools' and clearly states the resource (tools) and purpose (describing the data or task). It distinguishes itself from siblings by positioning as a meta-tool for discovery, listing concrete data domains it covers.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available'. It implies when not to use (when you need a single answer) but does not name alternative tools explicitly.

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

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

Beyond the readOnlyHint/idempotentHint flags, it discloses fan-out sources, soft-fail behavior for the USPTO PatentsView sunset, expected-empty semantics for fda_products, and private-company resolved:false handling. This is valuable behavioral context that annotations alone cannot 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 long, but the tool is genuinely complex with many output sections and failure modes, and the upfront examples plus 'ALWAYS PREFER' directive front-load the key decision. It earns most of its sentences, though it is somewhat verbose and partly repeats 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: sources_used/sources_failed, each returned field, expected-empty cases, and failure behavior. An agent has enough information to invoke it correctly and interpret the result.

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 both the schema and the description already document the accepted types, value shapes, and interchangeable type/value behavior. The description reinforces this with examples but does not add materially new parameter-level semantics.

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

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

The description opens with concrete user utterances and a crisp one-line definition: 'full cross-source profile of a US public company in ONE parallel call.' This clearly identifies the resource and distinguishes it from single-source lookups and siblings like compare_entities or resolve_entity.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' naming the exact condition and alternative. It also covers input forms and private-company behavior, so an agent knows when the tool does and does not apply.

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, so the description doesn't need to restate that. It adds marginal context ('clear sensitive data') but doesn't disclose behavior beyond annotations, such as what happens if the key doesn't exist.

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

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

Two sentences, first states the core action, second provides usage context. No filler or redundancy; 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?

For a simple 1-parameter, no-output-schema tool with annotations covering destructive and idempotent behavior, the description provides purpose, timing, and relationships to siblings. It omits only minor details like return value or missing-key behavior, which are not critical given the simplicity.

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

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

Schema description coverage is 100% — the only parameter 'key' is already fully described as 'Memory key to delete'. The description adds no further meaning 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 a specific verb ('Delete') and resource ('previously stored memory') along with the mechanism ('by key'), which clearly distinguishes it from sibling tools like remember and recall. It also names the action context (clearing sensitive data).

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

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

The description explicitly states when to use the tool ('context is stale, the task is done, or you want to clear sensitive data') and even directs pairing with remember and recall, giving clear context versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that it fetches the page and emits a standard markdown blob, which is useful behavioral context beyond the annotations. It does not go into failure modes or rate limits, but given the rich annotations, it meets a 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?

Four sentences, front-loaded with the core action, followed by process, output format, and use cases. No redundant phrases; every sentence adds value.

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

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

With two simple parameters, a well-described output ('single text blob' in standard llms.txt format), and rich annotations, the description is sufficient for an agent to understand and invoke the tool correctly. The 'Useful for' section adds practical 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?

Input schema covers 100% of parameters with descriptions (url and max_links with default/max). The description does not repeat parameter details, but the schema carries the burden; no additional semantic value is added.

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 'Generate' with the resource 'llms.txt file for any URL', then elaborates the process (fetches, extracts, emits). This clearly distinguishes it from sibling tools like ai_visibility_check, which focus on visibility measurement rather than file generation.

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

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

Provides a clear 'Useful for' list with three concrete use cases (client site indexing, personal project drafting, competitor auditing), giving context for when to use. However, it does not name alternatives or explicitly state when not to use it, though the sibling list includes potentially overlapping tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the 'random' nature of the fact and the specific return fields (fact text and character length), which are behavioral details beyond the annotations. It does not mention any edge cases, but for a simple read-only tool this is sufficient.

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

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

The description is two sentences, front-loaded with the primary action, then the return value, and finally the alternative. Every sentence contributes meaningful information with no redundancy or filler.

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

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

For a zero-parameter tool with strong annotations (read-only, idempotent, non-destructive) and a defined output schema, the description provides sufficient detail: what it does, what it returns, and when to use the sibling tool. There are no gaps for this level of 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?

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to explain. The baseline for zero parameters is 4; no additional explanation is needed or provided. The description does not need to add parameter information.

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 'Get a random cat fact' with a specific verb and resource, and further specifies what is returned ('fact text and character length'). It also distinguishes from the sibling tool get_facts by indicating this one retrieves a single fact. This is a clear, specific purpose.

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

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

The description explicitly says 'Use get_facts to retrieve multiple facts at once,' providing direct guidance on when to use this tool versus the alternative. This is explicit and actionable usage guidance.

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

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

Beyond the read-only, idempotent, and non-destructive annotations, the description discloses that facts are random and that it returns an array of fact texts with character lengths, adding useful behavioral context. It does not mention the default count, but the schema covers that.

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 every sentence earns its place. No redundant or filler content.

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

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

Given the tool's simplicity, full annotations, and output schema, the description is complete: it covers purpose, randomness, count specification, and return format. No significant gaps remain.

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

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

The schema provides full coverage for the 'limit' parameter with a description and default value. The tool description adds an example ('e.g., 5') but no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get'), resource ('multiple random cat facts'), and scope ('at once'), clearly distinguishing it from the singular sibling get_fact. It also mentions specifying a count, which clarifies the tool's function.

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: use this tool when you need multiple random cat facts at once. It does not explicitly mention alternatives or exclude single-fact usage, but the plural language implies the distinction from get_fact.

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 annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to restate those. It adds value by mentioning the return fields. However, it fails to disclose that no filtering parameter exists; instead, it implies search-by-name is available, which is a transparency gap.

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 long, front-loaded with the main action, and every word contributes. It is concise and well-structured with no fluff.

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

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

Given the simple tool (one optional param, no nested objects, output schema present), the description is mostly sufficient. However, the unsupported 'search by name' claim makes it incomplete because the description doesn't clarify the actual scope (only limit-based listing) and could lead to incorrect expectations.

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

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

The schema has 100% coverage for the single parameter (limit), so the description doesn't need to explain it. However, the description introduces a 'search by name' capability without a corresponding parameter in the schema, which actively misleads the agent about the tool's filtering capabilities.

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 primary action (list cat breeds) and specifies the domain (cat breeds), which distinguishes it from unrelated sibling tools. However, it also claims a 'search by name' capability that is not supported by the input schema (which only has a 'limit' parameter), making the purpose slightly misleading.

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

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

The description provides clear context for when to use the tool: to search or list cat breeds. It implies two usage modes (by name or all), but it does not explicitly mention alternatives or exclusions. Given that sibling tools are in unrelated domains, this level of guidance is acceptable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by specifying the scope ('caller's active subscriptions') and the exact return fields, which goes beyond the annotations and gives the agent a clear expectation of the tool's behavior. It stops short of prescribing pagination or ordering details, but for a simple filtered list tool this is sufficient.

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

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

The description is composed of two sentences, the first stating the main purpose, the second listing return fields and usage context. There is no redundancy or filler; every sentence earns its place, making it highly concise and well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description is complete. It explains what the tool does, what data it returns, and when to use it, leaving no significant gaps for the agent to guess.

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

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

The schema covers the single parameter include_inactive with a complete description, so schema coverage is 100%. The tool description does not add extra meaning about the parameter beyond repeating the 'active' notion, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' It uses a specific verb-resource pair and further specifies the returned fields (id, type, params, created_at, etc.), making it easy to distinguish from sibling tools like subscribe or unsubscribe which perform different actions.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to invoke this tool relative to subscribe (before adding) and unsubscribe (finding id), which is excellent guidance and distinguishes it from alternatives.

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

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

While annotations are all false, the description adds substantial behavioral context beyond them: filing returns a claim_token, passing it later returns status and resolution details, the report is rate-limited to 5 per identifier per day, feedback is free and doesn't count against quota, and the team reads digests daily. This fully discloses side effects, limits, and lifecycle behavior without contradicting any annotation.

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

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

The description is long but every sentence serves a purpose: purpose, usage triggers, exclusion scope, claim-token workflow, rate limit, and roadmap impact. It is front-loaded with the core action then flows logically into conditions and constraints. No redundant filler; each clause adds behavioral or contextual detail that an agent needs.

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

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

Given the absence of an output schema, the description fully covers what to expect: a claim_token on filing and later status/changes when reclaimed. It addresses the tool's scope (only Pipeworx tools), the feedback categories, and operational limits. The parameter count (4) and nested context object are adequately explained, making the tool fully usable from the description alone.

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

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

The schema already provides 100% coverage with detailed descriptions for all four parameters. The description adds semantic value by explaining the practical use of claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising to 'not paste the end-user's prompt,' which clarifies the expected content for the message parameter. It also reiterates the type categories in prose, reinforcing schema enums but not duplicating them excessively.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback categories (bug, feature/data_gap, praise), making the tool's purpose unmistakable. It also distinguishes itself from siblings by scoping to 'tools served by this Pipeworx connection,' a differentiation absent in other tool descriptions.

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

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

Explicitly states when to use the tool ('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)') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also gives concrete naming guidance for feedback content, which is actionable and helps the agent decide.

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

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

Beyond annotations (readOnly, idempotent), the description discloses additional behavioral traits: self-aggregating signal, no PII, derived from CF analytics-engine, and caching (5min-1h). This enriches the agent's understanding of data freshness and privacy without contradicting annotations.

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

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

The description is well-structured and succinct: a clear one-sentence summary, a bulleted list of three use cases, and a concise note on data sourcing and caching. Every sentence adds value, with no redundant 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 having no output schema, the description specifies return contents (top tools, top packs, total call volume, and raw (pack, tool, count) data). It also explains caching and data source, making the tool's behavior fully understandable for a simple one-parameter interface.

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

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

Schema coverage for the single parameter 'window' is 100%, but the description adds interpretive meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's enum/description, providing decision-making nuance.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource, and differentiates itself from siblings by focusing on aggregated trending data rather than individual queries or entity 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?

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It implies when to use this tool without naming specific alternatives, but gives clear context for application.

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 safety, but the description adds substantial behavioral detail: monotonicity + partition-sum methodology, the 3pp threshold, semantic similarity anchor (≥0.30 Jaccard), placeholder filter (20% fraction → null arb), and the critical fill check statement that realizable_edge_pp ≤ 0 means 'do not trade it.' This goes far beyond the 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 a dense, run-on paragraph covering many modes, filters, and response details. It is front-loaded with the purpose but exceeds reasonable length and lacks visual structure (bullets/headings). While every sentence carries value, the overall form is not concise and hampers quick scanning.

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 2-param tool with no output schema, the description fully covers the response shape (opportunities[], partition_check{}, fill check fields), edge cases (skipped_low_similarity, placeholders_filtered), and explicit warnings. It anticipates user questions about semantics and safety, leaving little ambiguity.

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

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

Both event and topic are optional and schemas already cover 100%, but the description elevates meaning by explaining mode-specific behavior, recommended usage, examples, and response differences (e.g., partition_check in event mode). The alternatives are clearly contrasted, making the parameter roles unambiguous.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket' and immediately distinguishes three invocation modes (no-args trending_scan, event, topic), clearly separating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to use each mode: event is 'recommended for a specific market,' topic is for cross-event scanning and catches patterns single-event misses, and it directs custom sizing to polymarket_fill_risk. Provides concrete example slugs and seed questions.

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

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

Despite annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds extensive behavioral context: the three model segments, edge calculation details, slippage netting, Kelly caps, 24h-move warnings, diagnostics funnel, and 1h KV-level caching. This far exceeds what the annotations alone convey.

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

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

The description is extremely dense and runs as a single long paragraph without section breaks. While information-rich, it could be better organized with shorter paragraphs or bullet-like structure. The length is largely justified by the tool's complexity, but it is not 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?

With no output schema present, the description fully covers the return value: by_segment structure, fed_candidates/fed_note, diagnostics, and why segments might be empty. It also covers caching, slippage assumptions, and edge-case details, making it highly complete for a complex tool.

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

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

All 9 parameters are fully described in the input schema, so the schema carries heavy weight. The description complements this by explaining how tradeable-edge knobs (min_liquidity, max_spread_pp) interact and clarifying the subtle behavior of min_partition_leg_kelly (parent-level kelly always 0). This adds meaning 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 first sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, giving a specific verb, resource, and scope. The detailed model-family breakdown and response segments further distinguish it from sibling Polymarket tools, even though no alternatives are explicitly named.

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 intended use case ('what should I bet on today') and explains that Fed bets are excluded due to unreliable data. However, it does not explicitly mention when to use this tool instead of siblings like polymarket_arbitrage or polymarket_edge_tracker, so exclusions/alternatives are missing.

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

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

Annotations already declare readOnly/idempotent/destructive flags; the description adds valuable caveats about the 60-day snapshot TTL, dependence on snapshotting being enabled, and that decay numbers come from daily closes rather than intraday. These behavioral details go 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 lengthy but information-dense, including purpose, args, response payload, and data caveats. Each section earns its place, though it could be slightly trimmed. It is well-structured with clear sections for args and response.

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

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

No output schema exists, so the description thoroughly specifies the response format: tracked[] with edge_pp_net time-series, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with data-gap semantics. Limits such as TTL and data start time are also disclosed, making the tool's behavior fully transparent.

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

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

Schema coverage is 100% and both parameters are described in the schema itself (days with lookup/clamp, window with enum values). The description reiterates these values ('default 14, max 30', 'default 1wk') and adds the context that window refers to a 'snapshot family', but does not significantly extend 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?

Description states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly addresses the question 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling polymarket_edges which likely surface current edges.

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

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

The description contextualizes usage by explaining the trade-off between fresh and old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), making the intended use clear. It does not explicitly name alternatives or when-not-to-use, but the framing is sufficient.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond these by detailing internal behavior (walks the ladder, returns top-of-book vs VWAP), output fields (verdict, thin_legs), and risk context (partial basket fills convert an arb into an unhedged directional position). No contradiction with annotations.

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

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

The description is long but every sentence carries essential information. It is front-loaded with the core purpose, then organized into explicit mode sub-sections and output enumerations. No fluff or repetition; the length is justified by the tool's complexity.

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

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

Despite having no output schema and high complexity (two modes, many outputs), the description comprehensively details return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), risks (forced_directional_risk), and usage preconditions. It is complete enough for an agent to decide when and how to invoke the tool correctly.

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

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

Although the schema provides 100% coverage, the description adds significant semantic layer: size_usd is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional per share paying $1), and side defaults are explained (auto for basket based on partition sum). This clarifies ambiguity beyond bare parameter descriptions.

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by stating it is the fill-risk check to use before acting on their signals. The two modes (single-market and basket) are also clearly articulated.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the alternative scenarios for single-market vs basket mode and warns against using it when theoretical overround is not capturable on thin books.

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

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

The description discloses far more than annotations: compatibility_warning and compatibility_codes[] can be non-empty even when matched_pairs>0, pairing_unverified is always set, spread_pp is gross and excludes Kalshi fees, temporal_alignment null means 'could not be computed' not 'aligned', and unclassified legs are never paired. It also explains the meaning of every safety code and skipped-counter semantics, giving an agent a detailed operational picture beyond readOnlyHint/idempotentHint.

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 tightly structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes), and every sentence adds operational detail required because there is no output schema. It is front-loaded with the core definition and mode explanation before the deep safety-code catalog. Minor redundancy exists (e.g., restating that both modes use the same matcher), but overall the length is justified by 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 there is no output schema, the description carries full responsibility for explaining return values, and it does: leg prices, matched top_spreads_pp, per-entry flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment, fees_note, and skipped counters. It also covers edge cases like temporal_alignment_unknown vs confirmed-aligned and the gross-vs-net caveat. Nothing an agent needs to call or interpret this tool is missing.

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

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

Even though schema coverage is 100%, the description adds substantial meaning: it defines the `topic` values as auto-fetch macros, explains that `kalshi_event_ticker` and `polymarket_event_slug` override the mapped sides, and provides concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'. It also clarifies that both modes yield identical matcher behavior, which is not evident from 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 verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the two venues, the concept (spread), and the object (same resolving question), which distinguishes it clearly from sibling tools like polymarket_arbitrage or polymarket_edges. The two-mode structure (topic vs explicit) further clarifies the tool's exact job.

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 distinguishes when to use the `topic` mode (10 pre-mapped macros) versus the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, stating both run the same matcher. It also warns that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable', which is an explicit caution against blind use. It does not name alternative sibling tools for comparison, but mode-level guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: listing all keys when key is omitted, scoping to identifier, and pairing with remember/forget. It doesn't contradict annotations, but doesn't mention edge cases like missing keys or return format.

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

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

The description is four sentences, each packed with relevant information: primary action, use case, scoping, and tool pairing. No fluff or repetition; it is front-loaded with the action and structured logically.

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

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

The tool is simple (one optional param, no output schema), and the description covers purpose, usage, scoping, and sibling relationships. It lacks explicit notes on return values or error handling, but these are not critical for this simple tool. Overall, it is sufficiently 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% (the 'key' parameter is fully described). The description reinforces the parameter behavior (omit to list all keys) and adds examples of what keys might contain, but doesn't add substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the primary action ('Retrieve a value previously saved via remember') and secondary behavior ('list all saved keys (omit the key argument)'), using a specific verb and resource. It distinguishes itself from siblings by naming 'remember' and 'forget' and giving concrete examples like 'ticker', 'address', and 'research notes'.

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 to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives (remember, forget) and notes scoping to identifier, providing clear context for when to use versus other tools.

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

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

The description discloses a side effect: setting mark_read=true flags returned events as read, altering subsequent calls. This directly contradicts the annotations' readOnlyHint=true, which asserts the tool is read-only. Since the description contradicts the annotation, score is 1 and annotation_contradiction=true.

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

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

The description is compact and front-loaded, with no redundant sentences. It covers purpose, return fields, filtering, mark_read behavior, and an alternative access method in a few sentences of appropriate 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?

The description is comprehensive for a read tool with 5 optional parameters: it explains return payload structure, filtering, side-effect parameter, and provides an alternative endpoint. Given the annotations and schema coverage, it equips the agent to use the tool correctly.

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

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

Schema describes all 5 parameters with 100% coverage. The description adds detail about mark_read's effect ('so the next call only shows newer ones') and implies filtering use, but the schema already documents these. It doesn't add significant semantics beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource. It clearly distinguishes from siblings like list_subscriptions (listing subscriptions) and recent_changes (tracking changes) by focusing on fired events from the feed. The mention of 'evaluator' and 'persisted feed' adds specific context.

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

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

The description gives clear usage context: it mentions that polling works fine and offers an alternative URL for scripts and dashboards, implying this tool is for interactive/polling use. However, it doesn't explicitly contrast with sibling tools like recent_changes or ask_pipeworx, so the guidance is clear but not exhaustive.

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 and idempotent; description adds multi-source fanout behavior, GDELT→GNews fallback, USPTO soft-failure context, and return structure (changes[], total_changes, citation URIs), going well beyond annotation info.

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 every clause delivers value: query intents, source list, parameter options, return shape, and alternative. Front-loaded with purpose despite length, 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?

For a complex multi-source tool with no output schema, description covers return values, source behaviors, fallbacks, and caveats (USPTO sunset). Sufficient for an agent to understand capabilities and 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 covers all 3 parameters with descriptions (100% coverage). Description repeats since/value semantics without adding new syntactic meaning, 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?

Description explicitly states it provides a change feed for a company over a window, with clear query examples. Distinguishes from entity_profile by contrasting static vs dynamic profile, fulfilling sibling differentiation.

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

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

Provides typical user prompts ('What's new with X') and explicitly recommends entity_profile for static profile needs, offering a clear when-to-use vs alternative. Also gives practical guidance on since parameter for typical monitoring.

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 (idempotentHint, destructiveHint), the description adds critical context: 'Stored as a key-value pair scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' These retention and scoping details are not in the annotations.

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

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

The description is concise and front-loaded with the core purpose, followed by usage context, storage details, and sibling pairing. Each sentence adds meaningful information without redundancy, earning 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?

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, retention, and sibling relationships. The annotations plus this description give the agent everything needed to invoke correctly.

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

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

The input schema already covers 100% of parameters with descriptions. The description adds value by giving concrete examples ('a resolved ticker, a target address, a user preference') and defining value as 'findings, addresses, preferences, notes', enriching the schema's generic descriptions.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later'. The verb 'Save' and resource 'data' are specific, and it distinguishes itself from siblings by explaining the key-value storage and pairing with recall/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?

Provides explicit 'Use when' guidance: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also names complementary tools: 'Pair with recall to retrieve later, forget to delete,' clarifying when to use this vs alternatives.

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

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

Beyond the read-only/idempotent annotations, the description discloses important runtime behavior: the call 'cascades through several lookup endpoints internally,' LEI/FIGI enrichment degrades gracefully if a source is unavailable, ambiguous instrument matches 'asserts nothing and returns figi_candidates,' and unresolved identifiers are explicitly listed under unresolved. This is rich behavioral context that an agent needs to interpret outputs correctly.

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

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

The description is front-loaded with purpose and the 'use FIRST' directive, and the SUPPORTED TYPES grouping helps an agent scan by entity type. It is dense and parenthetical-heavy, and the value-parameter guidance partly duplicates the schema description, which keeps it from a perfect conciseness score.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete: it covers supported types, accepted input forms, source provenance, ambiguity behavior, unresolved identifiers, and graceful degradation. An agent has enough information to know when to call it and how to interpret its results.

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

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

Although the schema already documents both parameters at 100% coverage, the description adds substantial semantic value: it gives concrete examples for ticker/CIK/name, distinguishes company vs drug inputs, and warns against passing full noun phrases ('NEW YORK ST DORM AUTH revenue bonds') because trailing security-class words will not match. This goes far beyond the 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 is anything but tautological: it opens with concrete user phrasings ('What's the ticker for…', 'find the CIK for…') and states a specific action and resource — resolve a user-spoken NAME to canonical identifiers. It also enumerates supported entity types and the exact identifier spaces (CIK, LEI, FIGI, RxCUI), making it easy to distinguish from other tools in the sibling list such as entity_profile or validate_claim.

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

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

The description gives explicit routing guidance: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to prefer this tool. It stops short of naming sibling alternatives or conditions to use them, so it lacks the full when-not/exclusion dimension of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond those: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds transparency regarding internal mechanism and output, without contradicting the annotations.

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

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

The description is concise and front-loaded: the first sentence states the core action, the second explains the mechanism, the third gives a use case, and the fourth lists return fields. Every sentence earns its place with no redundancy or fluff.

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

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

Given there is no output schema, the description appropriately describes the return value ('ranked list with score, confidence, signal density per entity'). It also explains the tool's relationship to sibling ai_visibility_check and covers the competitive audit use case. This is complete for a tool with 4 parameters and a single required field.

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

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

Schema description coverage is 100%, with each parameter (models, _apiKey, context, entities) already described in the input schema. The description does not add new parameter semantics beyond what the schema states (e.g., first entity as subject, rest as competitors). Since schema covers all params, 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 the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a concrete verb ('Compare'), a resource ('AI visibility'), and the scope ('multiple entities'). It also distinguishes from sibling tool ai_visibility_check by emphasizing multi-entity comparison, ranking, and output specifics.

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

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

The description provides clear context for use, stating it is 'Useful for competitive AI-marketing audits' and gives an example with a concrete query. It implicitly differentiates from single-entity sibling ai_visibility_check by focusing on multiple entities, but it does not explicitly state when not to use this tool or name alternatives as 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 declare readOnly/idempotent/non-destructive, and the description adds valuable behavior: composite fan-out, partial failure degradation, bundlephobia's first measurement taking 5-30s, and the sources_failed field. This exceeds what annotations provide.

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

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

The description is longer than typical but well-structured: purpose, usage, return values, ecosystem scope, and failure handling each earn their place. Front-loaded with the purpose, making it easy to scan.

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

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

With no output schema, the description fully enumerates return fields (summary block, advisories, links, versions), describes failure modes and timing, and states ecosystem limitations. This makes the tool's behavior predictable and complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific semantics beyond the schema, though the NPM-only ecosystem note adds context for the package 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 it is a composite 'should I add this npm package' check, listing the sources (deps.dev, bundlephobia) and the specific question it answers. This distinguishes it from sibling research tools, which focus on other domains.

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

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

Explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also specifies NPM-only in v1 and directs PyPI/Maven/Cargo/Go to deps.dev:version directly, providing clear 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?

The description discloses behavioral details beyond annotations: it returns top-N passages with character offsets and similarity scores, specifies underlying embeddings (BGE-base-en) and chunking (500-char windows), and states the 200K char limit with truncation behavior. This enriches the safe-read profile defined by annotations.

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

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

The description is dense but every sentence serves a purpose: main action, use case, pairing info, technical details, and limits. It is front-loaded with the core purpose and structured logically, with 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 no output schema, the description compensates by describing return format (passages with offsets and scores), technical behavior (embedding model, window size), and edge cases (truncation). Combined with 100% schema coverage and strong annotations, the description fully covers what an agent needs.

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 contextual meaning by giving examples of 'text' (SEC 10-K, article) and query examples, plus the practical motivation for passing text directly. This adds value beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the resource (record text) and the action (search). It distinguishes itself from siblings by positioning it as a context-saving alternative to ask_pipeworx_grounded and by emphasizing character offsets for verification.

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

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

Explicit usage guidance is provided: use when the record is too large for the prompt, pair with ask_pipeworx_grounded, and leverage offsets to verify quotes. This gives clear when-to-use and alternative tool connections.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds substantial behavioral detail: OAuth requirement, inability to persist for anonymous/BYO, always-on feed with pull endpoints, phone verification requirement, 10/day SMS cap, webhook signing secret returned once, and auto-disabling after 10 consecutive failing runs. This goes far beyond the annotations and provides crucial side-effect and prerequisite information.

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

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

The description is front-loaded with the core purpose and then expands into requirements, types, and delivery. It is dense but each sentence carries actionable information without fluff. It is longer than typical descriptions but appropriately so given the complexity of multiple subscription types and delivery options. It is structured with clear separators, making it easy to scan.

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

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

For a tool with no output schema, the description at least mentions the return value (subscription id) but could go further by explaining how to use that id (e.g., for management or unsubscribe). However, given the rich parameter details, prerequisites, and delivery semantics, the description is largely complete. The only notable gap is the lack of explicit guidance on using the returned id in downstream operations.

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

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

Input schema covers all 3 parameters with detailed descriptions, achieving 100% coverage (baseline 3). The description adds value with concrete examples and domain explanations, such as 'items:["5.02"] = officer change' and 'Polymarket↔Kalshi cross-venue mispricings', which clarify the intended usage beyond the schema. It also reiterates constraints like the 10/day cap and phone matching, reinforcing but not completely duplicating 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 verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the return value (new subscription id) and distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation. The supported types and delivery channels are enumerated, providing a specific and comprehensive 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 gives strong contextual usage guidance, including the requirement for a Pipeworx OAuth account and explicit caveats for anonymous/BYO users. It explains the delivery channels and how to consume the feed via recent_alerts, but it does not explicitly compare to alternative tools or state when not to use this tool (e.g., for one-time data fetching). Thus it has clear context but lacks explicit exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral detail: it returns category-bucketed example questions, each with the exact tool and argument shape, drawn from a live catalog of thousands of tools. It also explains the optional topic focus 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?

The description is somewhat long due to the initial list of example user phrasings, but this list is useful for intent matching. The core purpose, behavior, and usage are clearly stated in structured sentences that follow the front-loaded examples. Every part serves a purpose, though it could be trimmed 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?

Despite having no output schema, the description fully explains what the tool returns: category-bucketed example questions with tool and argument shape. It also covers the parameters, use cases, and relationship to meta-tools. The annotations handle safety context, making the description complete for an agent to invoke the tool confidently.

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

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

The schema describes the single optional 'topic' parameter with a list of values and meaning, providing 100% coverage. The description adds further context by giving examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread. This reinforces and slightly extends the schema.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It uses a specific verb ('suggest') and resource ('Pipeworx capabilities'), and distinguishes from siblings by positioning itself as the 'first' step for learning what to ask and how to call meta-tools.

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

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

It gives explicit guidance to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the no-argument vs. topic-argument options. However, it does not explicitly state when not to use it or name alternative tools like discover_tools, though it references meta-tools as related.

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 meaningful behavior beyond the annotations: ownership enforcement (auth), soft-delete vs hard-delete, and a pointer to recent_alerts for historical events. This aligns with annotations (destructiveHint=false, idempotentHint=true) while enriching them.

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

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

The description is two concise sentences, front-loaded with the primary purpose, and every clause adds value (ownership, deactivation, historical availability). 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?

For a simple one-parameter cancellation tool with strong annotations and no output schema, the description covers purpose, side effects, ownership, and related tool behavior. It is complete and self-contained.

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

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

The schema already fully describes the single parameter 'id' as 'Subscription id (uuid) returned by subscribe'. The description only says 'by id', adding no new semantic information, 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 states 'Cancel a subscription by id' with a clear verb and object, and further clarifies the deactivation behavior. This distinguishes it from sibling tools like subscribe and list_subscriptions by focusing specifically on cancellation.

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

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

It provides clear context: ownership is enforced, and cancellation deactivates rather than deletes. It implies the tool is for canceling your own subscriptions, but does not explicitly name alternatives (e.g., list_subscriptions for viewing).

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

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

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral detail beyond annotations: it explains the two fallback paths, the meaning of each verdict (especially that 'could_not_verify' does not count as evidence), the inclusion of a verification_error object with stage/detail, and the tolerance_pct override behavior. This goes well beyond the structured annotations.

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

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

The description is long, but every sentence contributes useful information: examples, routing logic, verdict meanings, error semantics, and integration notes. It is well-structured, starting with usage examples then flowing into technical behavior. It earns its length for a complex tool, though a slightly tighter organization could improve scannability.

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

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

With no output schema, the description adequately covers return values (verdict, actual value with citation, reasoning) and error behavior (verification_error, could_not_verify semantics). It also addresses the source routing context and the tolerance override. The tool's complexity is fully matched by the description, leaving no major gaps for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For 'claim' it provides concrete natural-language examples. For 'tolerance_pct' it explains the numeric range, the default behavior (implied by wording, capped at 5), and a concrete use case (hallucination detection with 1–2). This enriches parameter understanding for 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 clearly identifies the tool's purpose with verbs like 'verify', 'confirm or refute', and 'fact check', targeting natural-language claim verification. It distinguishes itself from siblings by describing two routing paths (SEC EDGAR/XBRL fast path and grounded pipeline) and by noting it replaces 4–6 sequential calls, which is unique among likely similar tools like get_fact or get_facts.

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 whenever the agent needs to check whether something a user said is factually correct.' It also gives clear guidance on interpreting results, especially the critical distinction between 'could_not_verify' and 'unsupported'. However, it does not explicitly mention alternatives or when not to use it, though the mention of replacing sequential calls implies a consolidation benefit.

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