Markdown

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

Annotations already declare read-only/open-world/idempotent traits. The description adds valuable behavioral context beyond annotations: the default free model, the BYO-key cost implication for Anthropic, and the per-model response structure. It does not mention rate limits or failure modes, but the bar is lowered by 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 three sentences: the first states core purpose, the second details model configuration and cost, the third covers return format and use cases. It is front-loaded, efficient, and contains 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?

Despite having no output schema, the description clearly explains the return structure ({score, confidence, signals, raw_response} + combined view) and all key configuration aspects. For a read-only probe tool, it is fully 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?

Schema coverage is 100%, so baseline is 3. The description enhances parameter understanding by explaining the default model (workers-ai), the role of _apiKey in enabling Anthropic, and the cost implications, which go beyond the schema's basic descriptions.

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

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

The description clearly specifies the verb 'Probe' and resource 'one or more LLMs' for scoring visibility (0-100) per model. It implicitly distinguishes from sibling tools by focusing on multi-model visibility scoring rather than single-question probing or competitor scanning, making the purpose unmistakable.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use the tool. However, it does not name alternative tools or exclusion criteria, so it stops short of full guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds valuable behavioral context: it 'fills arguments', returns 'structured answer with stable pipeworx:// citation URIs', and 'works on every tier, one fast call'. This goes beyond the annotation safety profile, though it doesn't fully detail error behavior or rate limits.

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

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

The description is long but each sentence contributes: use-case guidance, source breadth, examples, and escalation options. It's front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and ends with practical alternate-tool cues. Slightly dense, but 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 routing tool with no output schema, the description covers expected output (structured answer with citations), scope (verified sources), limitations (when to step up to grounded/research tools), and operational details (works on all tiers, one fast call). This is complete for an agent to safely invoke.

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

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

Schema coverage is 100% with a clear description of the 'question' parameter and aliases. The description enriches this by explaining that the question should be a factual real-world query and provides examples (e.g., 'current US unemployment rate'), which helps the agent formulate input correctly. This justifies moving above the baseline of 3.

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

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

The description states the tool's exact job: 'Routes the question to the right one of 5,462 tools across 1419 verified sources' and returns a structured answer with citation URIs. It clearly distinguishes itself from web search and sibling tools by being the default factual-query entry point.

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 instructions on when to use ('START HERE', 'PREFER OVER WEB SEARCH') and when to use alternatives ('Step up only when needed: ask_pipeworx_grounded for verbatim evidence + confidence, deep_research for broad/multi-part'). Also gives concrete query examples, making 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: it is experimental, may have candidate routing improvements, currently matches ask_pipeworx exactly, and has no fallback. This goes beyond annotations and explains the potential for behavior changes during tests.

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

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

The description is three sentences and front-loads the key point about being a beta router. Each sentence adds useful info (identical to ask_pipeworx, current state, usage guidance), but the final sentence about 'falls back to nothing' is slightly redundant with the earlier 'full working router' statement. Still, it is appropriately sized and 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?

The description explains the tool's purpose, experimental nature, current state, and usage in enough detail for an agent to invoke it correctly. It references the same response shape as ask_pipeworx, but since there is no output schema, it does not fully define the return format. However, the simplicity of the input and the reference to ask_pipeworx make it sufficient.

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 covers all 6 parameters (question and 5 aliases) with descriptions, so schema description coverage is 100%. The description does not add any extra parameter information beyond what the schema provides, meeting the baseline but not exceeding it.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same 5,462 tools and response shape, distinguishing it from siblings like ask_pipeworx and ask_pipeworx_grounded. The verb 'use' implies the action, and the resource (universal router) is specific.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use context. It implies the alternative of using the stable ask_pipeworx for non-experimental tasks, but does not explicitly state 'when not to use' or name an alternative, so it stops short of full explicitness.

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 hints, but the description adds rich behavioral context: it extracts answers only from tool result content, returns a structured success object with verbatim evidence, and provides explicit refusal reasons (not_in_source, no_tool_match, etc.). It also discloses the extra LLM call cost, exceeding what annotations cover.

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

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

The description is dense yet efficient, front-loading the core purpose and then detailing return/refusal formats, usage guidance, and cost tradeoff. Every sentence adds value with no redundancy, appropriate for the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly specifies the success return fields and all possible refusal reasons, effectively compensating for the missing structured output documentation. It also covers the routing behavior and cost, making it complete for high-stakes use cases.

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

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

Schema coverage is 100%—all six parameters are aliases for the same natural-language question, each documented in the schema. The description does not add parameter-level semantics beyond the schema's coverage, so baseline 3 applies.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior. It specifies the exact behavior (picks tool, fetches data, extracts answer only from tool result) and the resource (5,462 tools across 1419 sources).

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including a cost tradeoff (one extra LLM call). This directly guides tool selection against its sibling ask_pipeworx.

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

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

Even with annotations declaring readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral disclosure: low-confidence short-circuit status, closed-market handling, wide-spread illiquidity signaling, news fallback fields, and cancellation-rule risk with EV impact. This far exceeds what annotations convey and directly informs agent decision-making.

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

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

Although long, the description is methodically structured with capitalized sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence carries actionable information for tool selection and result interpretation; there is no filler or repetition.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers resolution confidence, parent-event partitions, news fallback behavior, safety blocking, market-closed handling, illiquidity warnings, and cancellation-rule risk. An agent can correctly anticipate response shapes and edge cases without an output schema.

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

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

The input schema already covers all three parameters with descriptions, providing a baseline of 3. The description enriches this with concrete examples for the market parameter (slug, URL, question text), fan-out examples tied to specific values (e.g., BTC bet → coingecko + fred + gdelt+gnews), and practical guidance on include_raw (recommended false, response size trade-offs). 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 description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from siblings by emphasizing one-call fan-out to category-specific data packs and market-vs-model comparison, which aligns with neither generic tools like deep_research nor specialized sibling tools like polymarket_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?

Explicit usage triggers are given: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." This provides clear context for when to invoke. It does not explicitly name alternatives or exclusion cases, but the detailed fan-out and resolver contract imply how it differs from sibling tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. It adds meaningful behavioral details: single parallel call, latest 10-K data source (SEC EDGAR/XBRL), off-calendar fiscal year handling, sorting by primary metric, and citation URIs per entity.

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

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

The description is front-loaded with trigger phrases and then compactly delivers behavior, data sources, sorting, and output format. Every sentence adds essential information; no filler or repetition. Despite length, the structure is scannable and information-dense.

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

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

Given no output schema, the description sufficiently explains the return shape ('paired data + pipeworx:// citation URIs per entity'). It covers purpose, data scope, constraints (2–5 entities), and advantages over sequential calls. The context is complete for an agent to select and invoke correctly.

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

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

The schema already gives 100% coverage for both parameters, so baseline is 3. The description adds value by explaining what each type pulls (10-K financials vs. FAERS/FDA/trial counts) and providing concrete examples for values ([AAPL, MSFT], [ozempic, mounjaro]), going beyond the schema's enum descriptions.

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

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

The description opens with concrete query patterns ('Compare X and Y', 'X vs Y', 'rank these companies') and clearly states the action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from siblings like entity_profile by emphasizing multi-entity comparison vs. single lookups.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a strong when-to-use directive. It also disambiguates type='company' vs type='drug' and notes it replaces 8–15 sequential lookups, effectively excluding use for non-comparison queries.

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

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

Annotations provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to restate safety. The description adds valuable behavioral context: the tool decomposes questions into facets, routes to 5,462 tools in parallel, returns gaps[] for unanswered facets, never invents evidence, performs iterative hops, and can take 15-90s. The one small gap: it doesn't explicitly mention rate limits or quota, but the account-requirement/depth-paid-plan details cover the most important constraint. Since annotations already declare safety, the additional behavioral detail justifies a 4.

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 efficient; it front-loads the critical account requirement and alternative tool first, then explains behavior, use cases, and caveats in a logical flow. Every sentence adds distinct information (data sources, parallel routing, gaps, citations, hop behavior, contradictions, timing). It is longer than average but earns its length given the tool's complexity—though a slightly tighter edit could trim redundancy between 're-angles unanswered gaps' and later 'gap recovery' phrasing.

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 research tool with no output schema, the description covers the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), timing, auth, and limitations. It doesn't need to explain return values in detail since the description already describes the findings packet. The only missing element is explicit mention of error or empty-result behavior (like when the structured catalog has nothing), though gaps[] is mentioned. Overall it is nearly complete for a tool of this complexity, so a 4 is fair rather than a 5.

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 meaningful semantics beyond the schema: it explains what the depth values actually mean in behavioral terms ('quick=3 (single hop), standard=5... adds a gap-recovery hop... thorough=8 (paid)...'), and clarifies that 'question' can be broad/multi-part because decomposition is the point. This goes beyond the schema's descriptions and enriches the agent's understanding, earning a 4.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call, and clearly distinguishes itself from open-web search. It explicitly differentiates from sibling ask_pipeworx ('For a single lookup use ask_pipeworx'), which shows a distinct use case. The resource (structured data catalog) and action (parallel multi-facet research) are crisply defined.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names alternatives (ask_pipeworx) and explains the account-required caveat with a clear fallback ('If you are not signed in, use ask_pipeworx instead'). This is an exemplary usage guideline section with exclusions and alternatives.

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

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

The description adds meaningful behavioral context beyond the annotations: it discloses that results include full schemas 'with curated examples' and are 'ready to call directly, no second schema lookup needed.' While the readOnlyHint and idempotentHint are already provided, the output behavior and the 'top-N' ranking are described, which is useful for an agent. It does not, however, detail limitations like truncation or ranking criteria, but the core behavior is transparent.

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

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

The description is three sentences, front-loaded with the main verb and resource ('Find tools'), followed by a compact list of example domains and a clear explanation of output and usage priority. Every sentence contributes value; there is no redundancy or filler.

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

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

For a discovery tool with no output schema, the description adequately covers the return behavior (names, descriptions, full schemas, curated examples), usage context (when to call first), and the scope of data domains. It provides enough information for an agent to select and invoke the tool without further lookup.

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

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

Schema description coverage is 100% — every parameter (query, q, task, limit, search, description) is documented in the input schema, including aliases and default limits. The description itself does not add parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies what it returns (top-N relevant tools with names, descriptions, and full input schemas), distinguishing it from sibling tools like ask_pipeworx or deep_research, which are concrete tools to be discovered rather than a meta-search utility.

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

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

Explicit usage guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly contrasts with using specific tools directly, providing both when-to-use and a directional preference.

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

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

Annotations already declare readOnly and idempotent, and the description adds behavioral details: fans out across multiple sources in one parallel call, notes the USPTO API sunset and soft-fail behavior, describes the fallback chain (GDELT→GNews), and specifies the output fields including URI formats. This adds context beyond the safety hints without contradiction.

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

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

The description is dense but well-organized, front-loading trigger phrases and the key 'always prefer' directive before enumerating output details. Every sentence carries useful information, though it is longer than average; it earns its length given the tool's complexity.

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

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

Despite having no output schema, the description fully enumerates the return structure (CIK, company name, recent filings with URL format, fundamentals, patents, news, LEI) and covers edge cases like patent API sunset and unsupported name inputs. It also positions the tool relative to resolve_entity, making it complete for selection and invocation.

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

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

The input schema already provides full descriptions for both parameters (type and value), including the zero-padded CIK requirement and name-not-supported note. The description reinforces this with concrete examples like 'AAPL' and '0000320193', and opens with natural-language trigger phrases that help map user intent to parameters.

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

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

The description clearly states it creates a full cross-source profile of a US public company in one parallel call, with explicit example queries. It distinguishes itself by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for name-only inputs.

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 when to use: whenever the user asks for a holistic view/company profile, and gives a directive to prefer this over chaining single-pack lookups. It also provides an alternative: use resolve_entity first if only a name is available.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds extra context by noting the output is 'keyless' and 'offline'. It also specifies the exact output format as {level, text} entries, contributing behavioral transparency beyond the annotations.

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

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

The description is a single, front-loaded sentence that every word contributes to understanding the tool's purpose and output. No filler or redundant information is present.

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 with one parameter and no output schema, but the description covers the core behavior, input, and output format. The presence of annotations and the explicit mention of 'keyless, offline' make it adequate for an agent to use correctly, though a bit more detail on edge cases (e.g., malformed markdown) could push it higher.

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 single 'markdown' parameter is described accurately as 'The Markdown text.' The tool description does not add further parameter-level detail, so it meets the baseline for full schema coverage without extra insight.

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 'Extract' with a clear resource ('ATX heading outline') and defines the output structure as {level, text} entries. It distinguishes itself from siblings like markdown_to_text and extract_links by focusing solely on ATX headings.

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

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

The description implies when to use the tool (when you need ATX heading outlines) but provides no explicit alternatives or when-not-to-use guidance. The purpose is clear enough for the agent to infer usage, but there are no stated 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 cover read-only, open-world, idempotent, and non-destructive hints. The description adds useful behavioral context beyond annotations: 'keyless' (no credentials) and 'offline' (no network), and it clarifies the handling of bare autolinks. These details are not redundant and paint a fuller picture of the tool's behavior.

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

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

The description is one concise sentence, front-loading the action and including the output format and key behavioral notes. Every word earns its place; there is no fluff or unnecessary detail.

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

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

For a simple tool with one parameter and no output schema, the description is complete: it explains the output format ({text, url} pairs), the input type (Markdown), and key constraints (keyless, offline). The annotations cover safety, and the schema covers the parameter. No critical information is missing for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage for the single 'markdown' parameter with a minimal description ('The Markdown text.'). The description does not add significant meaning beyond the schema, so the high coverage baseline of 3 applies. The examples in the schema provide more practical context than the description.

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

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

The description clearly states the function: 'Extract all Markdown links [text](url) (and bare autolinks) as {text, url} pairs'. It specifies the resource (Markdown links), the exact link formats, and the output structure, distinguishing it from siblings like extract_headings and markdown_to_text.

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

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

The description implies when to use the tool (when you need to extract links from Markdown) but provides no explicit alternatives or exclusions. It does not mention when not to use it or compare with sibling tools, leaving the usage guidance to inference.

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 aligns with annotations (destructiveHint=true, idempotentHint=true) and adds use-case context ('clear sensitive data'). It does not elaborate on edge cases like missing keys, but annotations already cover the destructive/idempotent nature.

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

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

Two sentences, front-loaded with the primary action followed by usage guidance. Every sentence is purposeful with no redundancy.

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

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

For a single-parameter destructive tool, the description fully covers purpose, usage, and context. Annotations handle safety, and no output schema is needed.

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

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

Schema coverage is 100% with the 'key' parameter fully described in the schema. The description does not add extra parameter semantics beyond what the schema already provides.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning its relationship with 'remember' and 'recall'.

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

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

Provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data'. This gives clear guidance on when to invoke the tool versus alternatives.

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

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

The description adds valuable behavioral context beyond the annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is 'a single text blob ready to drop at site-root/llms.txt.' Annotations already declare read-only and idempotent, so the description enhances rather than repeats.

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

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

The description is three sentences, front-loaded with the primary purpose, then process, then use cases. Every sentence earns its place without redundancy or filler.

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

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

For a tool with only two parameters, no output schema, and strong safety annotations, the description covers purpose, process, output format, and use cases comprehensively. 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 input schema provides 100% coverage for both parameters (url and max_links) with clear descriptions. The tool description adds no additional parameter-specific details, so the baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's specific function: 'Generate a production-ready llms.txt file for any URL.' It specifies the exact output (llms.txt markdown) and distinguishes itself from siblings like extract_links by focusing on the complete file generation rather than just extraction.

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

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

Provides clear use cases under 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives strong guidance on when to use the tool, though it does not explicitly name alternative tools or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying exactly what is returned: 'id, type, params, created_at, last_fired_at, fire_count for each.' It also clarifies the default scope is 'active' subscriptions, adding behavioral context beyond the annotations.

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

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

The description is three concise sentences: the first states the purpose, the second lists return fields, and the third gives usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

Given the low complexity of the tool (one optional parameter, no output schema) and comprehensive annotations, the description is fully adequate. It explains return values (since no output schema exists), specifies the caller's scope, and provides usage context. No important information is missing for this simple listing tool.

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

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

The input schema fully describes the only parameter `include_inactive` with 'Include cancelled subscriptions in the response (default false)', so schema coverage is 100%. The description does not add any additional semantic meaning about this parameter, which aligns with the baseline score of 3.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and explicitly lists the return fields. It distinguishes itself from sibling tools like subscribe/unsubscribe by mentioning 'review what you're monitoring before adding more or to find an id to cancel.'

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 this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use scenarios. It implies the alternatives of subscribe and unsubscribe, making the usage guidance actionable.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds useful behavioral context beyond annotations: 'keyless, offline' discloses privacy/access requirements, and 'turns links/images into their text/alt' specifies transformation 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 two sentences, front-loaded with the main purpose, and every phrase adds value: the parenthetical 'keyless, offline' is a key differentiator, and the specific items stripped are concise and informative. No filler or redundancy.

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

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

For a simple single-parameter tool with safe annotations, the description covers the main transformation behaviors and output ('readable plain text'). It could specify edge-case handling (e.g., lists, blockquotes) but given the low complexity and existing structure, 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% and the parameter 'markdown' is already described as 'The Markdown text.' The description does not add parameter-specific details (e.g., format limitations) beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Convert') and resource ('Markdown to readable plain text'), and enumerates exactly what it strips ('headings, emphasis, code fences') and how it handles links/images ('text/alt'). This clearly differentiates it from sibling extraction tools like extract_headings and extract_links.

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 phrase 'Ideal for de-formatting Markdown' gives a clear use-case context, implying when to choose this tool. However, it does not explicitly mention alternatives or exclusions, so it falls just short of a 5.

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

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

Annotations are all false (no hints to lean on), yet the description fully discloses behavioral traits: rate-limited to 5 per identifier per day, free and not counting against quota, digest review cadence, and road-map impact. No contradiction with annotations.

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

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

The description is longer than average but every clause contributes: use cases, exclusions, formatting instructions, and operational limits. It is front-loaded and logically organized, though it could be trimmed slightly without losing value.

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

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

For a feedback tool with no output schema, the description covers all necessary context: what to report, how to frame it, what not to do, rate limits, and what happens with the feedback. No ambiguity remains about when or how to invoke this tool.

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

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

Schema coverage is 100% and the schema already documents all parameters, so baseline is 3. The description adds extra semantic guidance on how to write the message (describe in terms of Pipeworx tools/packs, don't paste end-user prompt), and clarifies the 'type' enum usage through examples, elevating it above the schema alone.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly distinguishes itself from feedback about other MCP servers, making its purpose unmistakable.

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

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

The description provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...') and an explicit when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead'). This perfectly guides tool selection.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable beyond-schema context: self-aggregating from CF analytics-engine, no PII, (pack, tool, count) format, and cached 5min-1h. This provides meaningful transparency about data source, privacy, and freshness that annotations do not cover.

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

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

The description is front-loaded with the core purpose, then organized into a bullet-like use case list, and closes with concise technical notes. Each sentence adds value—no filler. The structure makes it scannable and efficient.

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

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

For a tool with a single optional parameter, no output schema, and helpful annotations, the description is complete. It tells the agent what it returns (top tools, packs, volume), how to use it (three use cases), and important constraints (caching, no PII). No gaps remain for the agent to infer.

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

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

Schema coverage is 100% with the window parameter's enum. The description goes further by explaining why different windows matter: shorter windows show 'what's hot right now' while longer windows show 'steady-state demand'. This semantic guidance helps the agent choose the right value, exceeding the schema's basic description.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb ('returns') and resource ('Pipeworx trending data'). It distinguishes itself from siblings like discover_tools by focusing on aggregate AI agent usage rather than individual tool discovery.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning use cases with agent demand. It lacks direct comparison to alternatives but the 'Useful for' list effectively implies when to use this tool over others.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds critical behavioral details: the >3pp deviation threshold for signals, the placeholder filter (>20% returns null), and the fill check warning that realizable_edge_pp ≤ 0 means 'do not trade it'. These go far 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 well-organized with internal labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence conveys necessary operational detail; while dense, it avoids fluff. A slightly more scannable layout would push it to 5.

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 specifying the response shape (opportunities[], partition_check fields, fill check outputs like theoretical_edge_pp_at_book). It also documents edge cases like low-similarity rejection and placeholder throttling. For a tool of this complexity, the description is fully 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?

Although the schema descriptions for event and topic are useful, the tool description significantly expands on them with concrete examples ('fed-decision-may-2026'), explains what each mode does internally (walks child markets, runs comparator on union), and clarifies the difference between modes. This adds substantial 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 opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by focusing on partition sums and cross-event comparisons.

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

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

It provides explicit guidance for each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative for related functionality: 'For custom sizing use polymarket_fill_risk.'

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior, and the description adds extensive context beyond that: it details response structure (by_segment, diagnostics), explains that Fed bets are excluded, mentions a 1h cache keyed on knobs, warns about 24h moves, and explains rare-by-design longshot gates. This is rich behavioral disclosure with no contradictions.

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

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

The description is quite long but well-structured with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds meaningful detail about the complex tool, though it is not as concise as it could be if some redundancy with schema descriptions were removed.

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

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

With no output schema, the description fully explains the response structure: top-level segments, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), fed_candidates/fed_note, and _diagnostics. It also covers caching, filtering behavior, and model logic, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage of all 9 parameters with detailed descriptions. The tool description summarizes the tradeable-edge knobs and explains how min_partition_leg_kelly interacts with partition_overround, but this largely restates schema information. Since schema coverage is high, the description adds marginal value, so a 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 function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the verb (scan/return), and the unique angle (Pipeworx data vs market price), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 states it is 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets, giving clear context for when to use it. It also describes knobs to filter tradeable edges, but it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Beyond the read-only annotation, the description discloses critical behavior: snapshots are written on cache-miss, data gaps exist, history is bounded by 60-day TTL, and decay is computed from daily closes not intraday. It also clarifies the signed nature of edge_pp_net and the absolute value used for trend/decay. This is substantial added context, not contradicted 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 long but well-structured with Args, RESPONSE, and LIMITS sections, and every sentence provides load-bearing detail. It is front-loaded with the core purpose. While dense, the structure prevents bloat, making it appropriate for the tool's complexity.

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

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

With no output schema, the description thoroughly specifies the exact response shape: tracked[], expired[], snapshot_dates[], each with field details. It also covers limitations (TTL, daily closes) and data gaps. This is complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description restates defaults and adds 'snapshot family' context for window, but does not significantly enhance beyond schema. The description omits the min clamp of 2 for days, so it's not fully accurate. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry, answering how long an edge has existed and whether it is shrinking. It references polymarket_edges snapshots, distinguishing it from sibling tools like polymarket_edges that likely list current edges. This is a specific verb+resource with scope.

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

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

The description gives clear context for when to use it: when you need to know edge persistence/decay rather than just current edge values. It explains the distinction between fresh and old wide edges, and notes data gaps. However, it does not explicitly name alternatives or state when not to use it, so it's close to 4.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description complements rather than repeats them. It discloses detailed behavior: 'walks the ladder', returns fields like 'top_of_book, vwap_fill_price, slippage_pp', and flags 'forced_directional_risk naming the legs most likely to strand you unhedged.' No annotation contradiction exists.

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

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

The description is dense and information-rich, front-loaded with the core purpose and using capital labels for modes. It is long, but every sentence contributes critical operational detail. A slightly more structured layout (bullets or headings) would improve scanability, yet there is no filler or redundancy.

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

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

With no output schema, the description must explain return values, and it does thoroughly: top_of_book, vwap_fill_price, slippage_pp, verdict, capture_ratio, thin_legs[], max_clean_notional_usd, forced_directional_risk, and more. It also covers modes, defaults, clamps, and failure risks, making it complete for an agent to decide and execute correctly.

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

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

Input schema coverage is 100%, so baseline is 3, but the description adds substantial semantics. It explains the REQUIRES one-of relationship between 'market' and 'event', mode-specific interpretation of 'side' (single vs basket with auto default), and the different meaning of 'size_usd' (spend vs target proceeds vs settlement notional). This goes well beyond the schema descriptions.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It names the specific resource (Polymarket CLOB) and action (fill-risk check), and clearly differentiates from siblings by positioning it as a pre-trade validation for polymarket_arbitrage and polymarket_edges signals.

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

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

Usage guidance is explicit: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It not only names the exact sibling tools but explains why, including the risk of partial basket fills turning into unhedged directional positions. This is strong when-to-use guidance with alternatives implied.

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

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

While annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, the description goes far beyond by detailing safety fields, compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype counters. It transparently explains what happens when matches fail and why spreads might be meaningless, giving the agent a complete behavioral model.

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

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

The description is long but well-structured with distinct paragraphs for purpose, modes, response, and safety fields. It avoids redundancy and each sentence contributes value, though it could be tightened without losing key details.

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

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

Given the tool's complexity, no output schema, and three optional parameters, the description covers the response structure (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skip counters) and explains all edge cases. It provides concrete examples of topic shortcuts and explicitly defines when the spread is meaningful, making the tool fully understandable to an agent.

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

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

The input schema already provides descriptions for all three parameters (100% coverage), but the description adds meaningful semantics about how the parameters interact—e.g., topic is a pre-mapped shortcut, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. This mode-based explanation significantly enriches parameter understanding.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's specific function and distinguishes it from siblings like polymarket_arbitrage. The subsequent explanations of modes and response fields reinforce a unique, well-defined purpose.

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

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

The description provides explicit usage context with TWO MODES (topic shortcuts vs explicit event ticker/slug) and explains when custom pairings should be used. It also warns that pre-mapped topics often return compatibility_warning and that 'pre-mapped ≠ tradeable,' setting expectations for when the tool yields meaningful results. However, it doesn't explicitly contrast with alternative tools like polymarket_arbitrage, so it falls short of a full when-not-to-use.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by explaining the scoping model (anonymous IP, BYO key hash, account ID) and the behavior of omitting the key (listing all saved keys), going beyond what annotations provide.

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

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

The description is concise and well-structured: first sentence states the core functionality, second gives a practical use case, third covers scoping and companion tools. Each sentence adds 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 simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and integration with sibling tools. It could mention the behavior when a key is not found, but the core information needed for correct selection and invocation is present.

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

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

The schema already covers the sole parameter 'key' with a clear description, including that omitting it lists all keys. The description reinforces this but only adds content-type examples rather than new semantic details about the parameter, so it does not exceed the schema baseline.

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

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

The description clearly states the tool's action: retrieve a previously saved value via the key, or list all saved keys when the key is omitted. It distinguishes itself from related sibling tools 'remember' and 'forget' by explicitly naming them as counterparts, and gives concrete content examples (ticker, address, 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 provides explicit guidance on when to use the tool: to look up previously stored context without re-deriving it, citing specific use cases. It also outlines the full workflow by pairing with remember and forget, effectively indicating when this tool is the appropriate choice 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?

The description states that setting mark_read:true will 'flag returned events read,' which is a state-modifying side effect. However, the annotations declare readOnlyHint:true, implying the tool is read-only. This is a direct contradiction between the description and the annotations, so transparency must be scored as 1.

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

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

The description is succinct and well-structured: it opens with the primary purpose, then describes the return format, filtering, mark_read semantics, and polling. Each sentence adds useful information without 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?

Without an output schema, the description carries the burden of explaining return values, which it does (source, citation_uri, raw payload). It also covers filtering, mark_read usage, and polling. It does not mention potential interactions between unread_only and mark_read, but that is a minor gap given the schema descriptions. The contradiction with annotations is a transparency issue, not a completeness one.

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 has 100% coverage for all parameters, so the baseline is 3. The description adds value beyond the schema by giving a concrete example for 'type' (e.g., "sec_8k"), explaining that 'since' is an ISO timestamp, and detailing the behavioral effect of mark_read on subsequent calls. This additional context justifies a score of 4.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' This uses a specific verb ('Pull') and identifies the resource ('fired events from your subscription feed'), and adds detail about event contents (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing on fed events.

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

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

The description provides clear usage context: it explains filtering by type and/or since, the effect of mark_read on subsequent calls, and that polling is fine. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly name sibling tools as alternatives or provide exclusion criteria, so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds concrete behavioral detail: fans out to SEC EDGAR, GDELT→GNews fallback on rate-limit/5xx, USPTO PatentsView sunset soft-fail, accepted `since` formats, and return shape (changes[] grouped by source + total_changes + citation URIs). 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?

Dense but well-organized: front-loaded user-intent phrases, then a single paragraph covering source fan-out, fallback logic, date syntax, and return shape, ending with a clear pointer to entity_profile. No filler or repetition of schema fields.

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

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

High-complexity tool with no output schema, yet the description covers input semantics, source selection, fallback behavior, sunset risk, output grouping, and citation URIs. Combined with 100% schema coverage and rich annotations, this is complete enough 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 covers 100% of parameters, but the description adds practical semantics: `since` accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It also clarifies that `value` can be a ticker or zero-padded CIK, reinforcing schema guidance with usable examples.

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 natural-language triggers ('What's new with X') then defines 'change feed for a company in the last N days/weeks/months in ONE parallel call,' naming the three source categories. It distinguishes itself from sibling entity_profile by explicitly directing static-profile requests there.

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

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

Explicit when-to-use via query examples and 'in ONE parallel call'. It names the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also clarifies GDELT→GNews fallback conditions, guiding agents on expected behavior across sources.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds significant behavioral context: storage is 'scoped by your identifier', authenticated users get persistent memory, anonymous sessions retain for 24 hours. This discloses persistence and scoping traits not implied 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 three sentences, front-loaded with purpose, then usage, then storage details. Every sentence contributes new information without fluff or redundancy.

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

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

Given the simple 2-parameter schema, present annotations, and no output schema, the description fully covers purpose, usage, persistence, and sibling integration. It is complete for an agent to select and invoke the tool correctly.

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

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

The input schema already provides full descriptions and examples for 'key' and 'value' (100% coverage). The description adds no per-parameter specifics beyond what the schema offers, though it reinforces the key-value pair concept. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb ('Save') and resource ('data'). It distinguishes from siblings by explicitly pairing with 'recall' and 'forget' for related operations, making its role unique.

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It names complementary tools ('Pair with recall... forget to delete') but does not explicitly state when not to use it, so it falls short of the full 5 criterion.

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 significant behavioral detail beyond annotations: it cascades through multiple lookup endpoints internally, returns specific structures (ticker, CIK, company_name, citation URI for companies; RxCUI, ingredient, brand, citation URI for drugs), and notes auto-disambiguation. No contradiction with annotations.

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

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

The description is longer than average but well-structured with examples up front and a 'SUPPORTED TYPES' section. Each sentence contributes to understanding usage, types, and output. It is not minimal, but efficiency is traded for valuable operational detail.

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

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

With no output schema, the description fully describes return values for each supported type (company: ticker, CIK, company_name, citation URI; drug: RxCUI, ingredient, brand, citation URI). It also explains why the tool is useful (replaces multiple lookups) and covers disambiguation behavior. This is complete for a 2-parameter lookup tool with strong annotations.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds extra meaning by clarifying that company input accepts ticker/CIK/name and is 'auto-disambiguated', and that drug input accepts brand or generic names. It also specifies which parameters produce which return fields, exceeding the schema's basic descriptions.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It lists concrete examples ('ticker for', 'CIK for', 'RxCUI for') and supported types (company, drug) with exact return fields. This clearly distinguishes it from siblings like entity_profile, which focuses on profiles rather than ID resolution.

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

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

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides example user queries and notes it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so safety is covered. The description adds valuable transparency by revealing it 'Probes each entity with ai_visibility_check', ranks by score, and returns a 'ranked list with score, confidence, signal density per entity'. This goes beyond annotations to describe the tool's internal behavior and output 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 three sentences, each earning its place. The first states the core purpose, the second explains the mechanism (probing and ranking), and the third provides a use case and expected output. No filler, well front-loaded.

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

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

There is no output schema, but the description compensates by stating the return type: 'ranked list with score, confidence, signal density per entity'. It also explains the role of the first entity (your brand) and competitor relation. Some minor omissions exist, such as potential latency from multiple external calls, but overall it's adequately complete given the rich annotations and schema.

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

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

Schema description coverage is 100% with all four parameters described in detail (models, _apiKey, context, entities). The description does not add any parameter-level meaning beyond what the schema already provides; it reinforces the entities array but doesn't deepen understanding. Thus the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and specifies that it 'ranks by score' and 'surfaces which is most/least recognized'. It distinguishes this from sibling ai_visibility_check by focusing on multiple entities and from compare_entities by specifying the AI visibility domain.

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

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

The description provides a clear context: 'Useful for competitive AI-marketing audits' with a concrete example query. It implicitly indicates this is the multi-entity counterpart to ai_visibility_check, but doesn't explicitly state when NOT to use it or mention alternatives like compare_entities. This is a strong 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 readOnly/idempotent annotations, the description discloses partial failure behavior, bundlephobia's first-measurement latency (5-30s), and the sources_failed field. This gives the agent realistic expectations 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 structured with purpose first, then usage criteria, return payload overview, ecosystem limitation, and failure handling. Every sentence provides necessary operational context for a composite tool; no fluff or repetition.

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

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

With no output schema, the description fully details return contents: summary block fields, per-advisory detail, links, and recent alternatives. It also covers timeouts, partial failures, and ecosystem scope, giving the agent adequate context to 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?

The input schema already provides complete descriptions for both 'package' (with scoped package note) and 'version' (with default behavior). The description adds no additional parameter-level semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

The description opens with a specific composite check for adding npm packages, clearly distinguishing it from generic research tools. It enumerates the data sources (deps.dev, bundlephobia) and the exact categories of information returned, making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion for non-npm ecosystems, directing to deps.dev:version directly, which serves as both an alternative and a boundary.

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

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

Annotations already cover read-only/idempotent/destructive safe, but description adds non-obvious behavior: BGE embedding model, cosine similarity, 500-char overlapping windows, 200K char cap, truncation flag, and offset availability for quote verification. No contradiction.

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

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

Two dense but purposeful sentences. First sentence front-loads the core function and outputs; second packs usage guidance, pairing, and technical constraints. No filler or redundant restating of the name.

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

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

Despite no output schema, the description explains return contents (passages, offsets, similarity scores), scale limits (200K chars), truncation flagging, and how to use with a gateway tool. Covers all key operational aspects for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by giving example query types ('supply-chain risk', 'fiscal year 2024 revenue'), explaining the text provenance ('a SEC 10-K body, an article'), and noting the truncation behavior for long text. This goes slightly beyond schema descriptions.

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

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

The description states a specific action ('semantic search INSIDE a fetched record') with clear resource (a text blob) and outcome (top-N passages with offsets and scores). It distinguishes itself from siblings like ask_pipeworx_grounded by positioning as the 'inside the record' alternative.

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 when to use ('when the record is too big to cram into the prompt'), what it saves (context), and pairs with ask_pipeworx_grounded as a recommended flow. This is textbook usage guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description goes far beyond that by explaining account requirements, delivery channel behaviors, webhook signing details, auto-disabling after 10 failures, and the fact that the signing secret is returned only once. This is rich behavioral context that helps the agent anticipate side effects and constraints.

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

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

The description is long but every sentence earns its place. It is logically organized: purpose → requirements → types → delivery channels. It is dense with actionable details without being redundant. No fluff or repetition of schema fields.

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

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

Given the tool's complexity (3 params, nested objects, 5 types, no output schema), the description covers all necessary aspects: return value, prerequisites, per-type parameters, delivery options, and operational caveats. The agent has enough to invoke the tool correctly and anticipate side effects.

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?

Though schema coverage is 100%, the description adds substantial meaning beyond the schema. It provides concrete examples for each type (sec_8k, polymarket_edge, fred_series, etc.), explains delivery configurations in depth (e.g., HMAC signing, phone verification, 10/day cap), and details webhook behavior. This goes well beyond the baseline 3 for full schema coverage.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation. The supported types and delivery channels are enumerated, leaving no ambiguity about what the tool does.

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

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

The description provides strong guidance on when to use the tool (e.g., to monitor live data, requires OAuth account, phone verification for SMS, 10/day cap). It does not explicitly state when not to use it or name alternative tools, but the context and constraints effectively imply usage. A clear exclusion or sibling comparison would push it to 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context about the output: it returns category-bucketed example questions with the exact tool and argument shape, drawn from a live catalog. This goes beyond what annotations provide, though it doesn't describe potential response sizes or edge-case behavior.

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

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

The description is somewhat long but well-structured: it opens with user-intent phrases, then explains the return value, then call modes, then usage guidance. Each section adds necessary information, though the opening synonym list ('what can you do? / give me ideas') could be trimmed 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?

Given the tool has no output schema, the description thoroughly explains what the response contains (category-bucketed questions with tool+argument shapes). It also covers the optional parameter and provides a clear usage recommendation. For a simple onboarding tool, this is fully adequate.

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

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

The schema already covers the optional `topic` parameter with a description and allowed values (100% coverage). The description reinforces this by giving concrete examples ('finance', 'pharma', 'betting') and explains the no-argument behavior. This adds value beyond the schema's enum-like list.

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

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

The description clearly defines the tool as the onboarding entry point for answering 'what can I ask Pipeworx?' and distinguishes it from sibling tools by focusing on example questions rather than tool discovery. It uses specific verb-noun phrasing ('Returns category-bucketed example questions') and identifies the resource (Pipeworx capabilities). This is a specific, non-tautological purpose.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions it teaches how to call meta-tools. It also explains the two call modes (no args vs topic) and lists example topics. This gives clear context and differentiates from alternatives like discover_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 declare idempotentHint=true and destructiveHint=false, and the description adds crucial context: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. This goes well beyond what annotations alone provide and clarifies side effects and permissions.

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

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

The description is two sentences with a front-loaded action, and every clause adds meaningful information: the action, ownership, deactivation behavior, and data retention. There is zero redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: purpose, permission constraint, side effect (deactivation vs deletion), and downstream impact on historical data. It is fully sufficient for an agent to invoke correctly.

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

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

The schema description for 'id' is complete (100% coverage), stating it is the subscription uuid returned by subscribe. The description adds only 'by id' and ownership context, which marginally extends meaning but doesn't significantly compensate for anything missing in the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions). It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing specifically on cancellation, making the purpose unambiguous.

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

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

The context is clear: the tool is for canceling a subscription by id. It includes a key ownership restriction ('you can only cancel your own subscriptions'), which guides correct invocation. However, it doesn't explicitly mention alternatives or exclusions, though the availability of recent_alerts for historical events subtly references an alternative for viewing data.

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 behavior beyond that: it details the two-path routing (SEC EDGAR + XBRL for financial claims, grounded pipeline for others), the exact percent-delta math with tolerance_pct overrides, and the output structure (verdict, actual value with citation, reasoning). It does not describe edge cases like ambiguous claims, but the added context is valuable.

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

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

The description is relatively long but every part serves a purpose: trigger phrases, usage directive, routing explanation, output summary, and efficiency claim. It is structured logically and front-loaded with the most important info (what it does and when to use). It could be tightened slightly, but the detail is necessary for a composite tool.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does so by listing the verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), the actual value with citation, and reasoning. It also explains the internal decision process. Given the tool's complexity (2 params, no output schema), this description is adequately complete, though it could mention what happens when the claim is entirely unsupported.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description goes further by explaining the behavioral effect of tolerance_pct—'overrides the tolerance implied by the claim wording—set 1–2 for hallucination detection'—and the default cap at 5. It also provides richer examples of the claim parameter beyond the schema's examples.

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

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

The description states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself as a composite fact-checking tool by listing trigger phrases and describing its two routing paths (SEC EDGAR fast path vs. grounded pipeline), which sets it apart from sibling tools like ask_pipeworx_grounded or compare_entities.

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

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

It gives an explicit when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs. other factual claims, and notes it 'Replaces 4–6 sequential calls,' implying when to prefer this tool over manual multi-step workflows. This is strong usage guidance, even though no sibling tool is named directly.

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