numuersapi

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds meaningful context: the default Workers AI model is free, passing `_apiKey` enables Anthropic at direct cost to the user, and the return payload structure (per-model score, confidence, signals, raw_response + combined view). This goes beyond what annotations alone provide.

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

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

Three sentences with no fluff; every sentence adds essential information (purpose, default behavior/cost, return format, use cases). It's front-loaded and well-structured, making it easy for an agent to parse quickly.

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 outlines the response shape (per-model result plus combined view) and key behavioral notes (BYO key, cost). It covers the important aspects for an agent to invoke the tool correctly, though it might briefly mention limitations (e.g., supported models) but that's already in the 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the default model for the `models` array and the cost implication of `_apiKey`, which the schema alone doesn't convey.

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

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

The description uses a specific verb ('probe') and identifies the target (LLMs) and the output (visibility score 0-100). It clearly distinguishes this from generic question-answering tools by focusing on scoring LLM knowledge, though it doesn't explicitly name sibling alternatives like scan_competitor_ai_presence.

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

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

It states concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving the agent clear context for when to select this tool. It doesn't provide exclusions or alternative tool names, but the context is explicit and actionable.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavior beyond those annotations: it explains that the tool routes the question, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No contradiction exists between the description and 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 most important guidance is front-loaded with 'PREFER OVER WEB SEARCH'. The domain list and examples are somewhat long but useful for routing decisions. There is slight redundancy—such as explaining that the tool should be used even when web search could answer—but overall every section contributes to the tool's effective use.

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

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

Given that there is no output schema, the description does a good job of describing the output as a structured answer with pipeworx:// citation URIs, and it covers input scope and use cases well. The remaining gaps are the exact response shape, pagination, and how other ask_pipeworx variants differ, which are minor but relevant for complete selection guidance.

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

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

The schema fully documents the parameter and its aliases, so the baseline is 3. The description adds value by specifying what kinds of questions are appropriate—factual questions about real-world entities, events, and numbers—and it provides concrete examples such as 'current US unemployment rate' and 'active clinical trials for GLP-1'. This helps the agent formulate the question argument correctly.

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 what the tool does—it routes a natural-language question to one of thousands of verified data tools and returns a structured answer with citation URIs. It also clearly distinguishes itself from web search. However, it does not explain how it differs from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so the purpose is clear but not fully differentiated from all siblings.

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

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

The description gives strong usage guidance: 'prefer over web search', 'use it whenever the user asks what is', 'look up', 'find', 'get the latest', and 'START HERE for most questions'. It does not explicitly say when a sibling tool such as deep_research should be selected instead, so the when-not-to-use guidance is incomplete.

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 provide readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows it is a safe read. The description adds context beyond annotations by explaining it is a fully working router rather than a stub, and that routing candidates may be active, and if none are active, it matches the stable version. The falling-back-to-nothing phrase clarifies it is not a limited version, which is useful.

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, front-loading the fact that it is a beta with identical behavior and current status. It contains a few redundancies, such as repeating 'same 5,596 tools' and stating both that it is 'experimental edge' and 'falls back to nothing,' but these serve to reinforce the meaning. Overall, every sentence adds some value for the agent.

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 simple interface (one required question parameter, no output schema), the description covers the instrument's purpose, current identity, and usage instructions. A minor gap is that it does not describe what 'routing' actually does or what kind of result the agent might receive, but the presence of aliases and sibling tools like ask_pipeworx makes it reasonably complete.

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

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

The schema provides 100% coverage for all parameters, including descriptions for question and its aliases. The description adds that the tool uses the same arguments as ask_pipeworx, reinforcing that the question parameter plus aliases are used. Since the schema fully documents the aliases, the description adds only confirmation of compatibility, which is still valuable given the beta context.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with identical routing, same tools, arguments, and response shape. It specifies that it is the experimental edge with candidate routing improvements, distinguishing it from the stable ask_pipeworx. The only minor gap is that the description does not explain what the router itself does, assuming familiarity with ask_pipeworx.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and clarifies that results are compared against the stable router. It also states that no candidate is currently active, making it currently identical to ask_pipeworx. This gives the agent explicit when-to-use guidance and differentiates it from the sibling tools.

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

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

The description significantly expands beyond the annotations by defining the exact return shape on success, the refusal reasons list, the 'only what the tool result contains' behavior, and the extra LLM cost. This gives the agent a precise, realistic model of how the tool behaves.

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

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

The description is dense but every sentence adds value: mode, routing behavior, return shape, refusal cases, usage guidance, and cost tradeoff. It is front-loaded with the most important trait ('hallucination-resistant') and is well-structured with examples and explicit alternatives.

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 fully compensates by listing the success and refusal response fields. Combined with the annotations (read-only, open-world, idempotent, non-destructive), the agent has all necessary guidance; the missing parameter details are already supplied by the 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 has 100% coverage plus a description of the question parameter and its aliases. The tool description adds no parameter-level detail, 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 states the tool is a 'hallucination-resistant answer mode' and explains exactly what it does: route to the right tool, fetch data, then extract an answer using only the tool result. It clearly distinguishes itself from the 'ask_pipeworx' sibling by grounding answers and providing refusals.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on', 'must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also provides the cost tradeoff of one extra LLM call, which is directly actionable for 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=true and idempotentHint=true, but the description goes far beyond: it details the resolver contract, safety short-circuits, closed/dead market handling, wide-spread market tradeability, and resolution-rule cancellation parsing. It even warns agents to inspect match confidence before trusting analysis. These are behavioral nuances not present in the annotations, adding substantial value.

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

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

The description is long but highly structured with clear sections (purpose, classifiers, fan-out examples, response shapes, resolver contract, safety). It is front-loaded with the core purpose and only includes necessary operational detail. It loses a point for overall length, which may overwhelm some agents, but every section earns its place given the tool's complexity.

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

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

With no output schema, the description must fully explain return values – and it does: result.market, result.analysis, result.evidence, match confidence, parent_event, news fields, and status codes. It also covers failure modes (GDELT 429, low-confidence matches, closed markets) and resolution-rule risk. The description is sufficiently complete for an agent to invoke and interpret the tool correctly in most scenarios.

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

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

Schema description coverage is 100%, and the schema already provides detailed descriptions and examples for all three parameters. The description adds some context about market input formats and mentions depth/include_raw in examples, but it does not significantly extend beyond the schema. Baseline 3 is appropriate because the description adds minimal parameter-level semantics beyond the structured 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 from siblings by focusing on Polymarket betting, classifier categories, and the market-vs-model comparison. The fan-out examples and use cases reinforce a unique role among the sibling tools.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear contextual guidance. However, it does not mention exclusions or name alternative tools, so it stops short of the highest tier which would explicitly contrast with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds extra context: it discloses the exact data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, sorting by primary metric, and the return format (paired data + citation URIs). These details go well beyond the annotations and inform the agent of important behavioral traits.

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

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

The description is dense but every sentence contributes: trigger phrases, the parallel-call advantage, per-type data details, fiscal-year handling, sorting logic, and output URI citation format. It is well-structured and front-loaded with user intents, making it highly learnable without wasted words.

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

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

Despite no output schema, the description specifies what is returned (paired data and citation URIs) and how results are sorted. It covers both entity types, data sources, count limits (2–5), and the advantage over sequential lookups. This is a complete picture for an agent to use the tool effectively in a variety of comparison scenarios.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds further semantic value by explaining precisely what type='company' retrieves (10-K revenue, net income, cash, long-term debt) and what type='drug' retrieves (FAERS counts, FDA approvals, trial counts), plus examples for values. This enrichment justifies a score above baseline, though it does not fully detail every possible nuance.

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

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

The description opens with explicit trigger phrases and states the core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sibling tools by noting it should be preferred over sequential single-pack lookups, making the tool's purpose unambiguous and differentiated.

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?

Includes an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete usage scenarios (e.g., 'which is bigger / better / larger') and explains what data each type (company vs. drug) returns, giving the agent clear guidance on when to invoke this tool versus alternatives like single-entity lookups.

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

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

Behavior is disclosed far beyond annotations: it warns about account/paid tiers, describes output as 'verbatim evidence + confidence + source + fetched_at + a stable citation', states that gaps are 'never invented, and standard/thorough return contradictions[] that flag disagreements. It also sets user expectations with expected latency (15-60s, thorough up to ~90s). Nothing here contradicts the readOnly/open/in-omniscent annotations.

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

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

The description is long, but every sentence earns its place: auth restriction, free plan, alternative low-tier tool, the NOT-web, facets, simple remark check, response structure, citation guarantee, gap handling, contradiction behavior, and duration expectation. It is front-loaded with the most critical operational constraints (account and payment), and only then explains tool specifics.

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

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

With no output schema, the description appropriately explains the full return packet (four evidence fields + citation + feedback markers) and special modes. It also includes real requirements (auth, paid depth), edge cases (corpus semantic excerpts, not truncation), and network/external expectations (request latency). There is no missing piece an agent would need to call and interpret the 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?

Parameter meaning is already well covered (schema_description_coverage = 100%), with a rich description of `depth` and `question` in the schema. The description adds contextual facts like cost tiers and timing, but that is not substantially new parameter semantics. This is the baseline 3 for schemas that do the heavy lifting.

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

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

The description states a specific, unique purpose: 'Grounded multi-source research across Pipeworx's 1,165 STRUCTURED sources... Decomposes your question into focused facets, routes each to the right one of 5,596 tools IN PARALLEL'. It explicitly differentiates from open-web search ('this is NOT open-web search') and calls out the key sibling alternative (ask_pipeworx) with its own different role. An agent can confidently identify this tool's distinctive place.

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: 'Best for broad/multi-part questions over structured data' with concrete examples, and the description states the alternative path twice: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It gives both when-to-use and when-not-to-use conditions, with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and claims results are callable without a second schema lookup. It also notes it returns an option set, not a single answer.

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

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

The description is moderately long but every sentence carries information: purpose, use cases, data domains, return format, and prioritization. The list of domains is lengthy but directly relevant for a discovery tool. It is front-loaded with the core verb. Slightly dense but not padded.

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 presence of annotations and a fully described schema, the description covers return structure ('names, descriptions, and full input schemas'), usage precedence, and supported content areas. It even states that results are directly callable, reducing ambiguity. No output schema exists, so the return description is important and included.

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

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

Schema description coverage is 100%, with detailed descriptions for query (including aliases) and limit. The description does not add further parameter-level semantics; it only reinforces that query is a natural language description, which the schema already states. Baseline 3 applies.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It also differentiates from siblings by positioning itself as a discovery/meta tool ('Call this FIRST when you have many tools available') and lists supported data domains. This distinguishes it from research tools like deep_research 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?

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist for:' and instructs to 'Call this FIRST when you have many tools available' — clear when-to-use guidance. It does not name specific alternatives, but the precedence and scope are 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?

Beyond the readOnlyHint/idempotentHint annotations, the description reveals significant behavioral details: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), soft-fails when the patents API sunsets, uses a GDELT→GNews fallback, and returns specific URI formats for filings. This level of disclosure goes well beyond the annotation baseline.

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

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

The description is long but well-structured: it leads with example queries, states the core purpose, gives usage preference, then details the fan-out sources and return fields. While dense, nearly every sentence provides value, though it could be trimmed slightly by removing some redundancy with the schema.

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

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

With no output schema, the description compensates by listing all return fields (CIK, recent_filings with URIs, fundamentals, patents, news, LEI), including sort order and limits. It also discloses important caveats like the USPTO sunset, input restrictions, and fallback chain, making it fully actionable for an agent.

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

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

The input schema already documents both parameters with high coverage (100%), including ticker/CIK formats and the note about names not being supported. The description repeats this information without adding new parameter-level semantics, so it stays at the baseline 3 for fully-covered schemas.

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: 'full cross-source profile of a US public company in ONE parallel call.' It gives concrete example queries ('Tell me about X', 'brief me on Tesla') and enumerates the specific return components, making it easy to distinguish from siblings like compare_entities or resolve_entity.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names a clear alternative for name-only queries: 'use resolve_entity first if you only have a name.' This covers both positive and negative use cases.

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 (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by describing a deletion operation. It adds some contextual framing around clearing sensitive data but does not disclose additional behavioral details beyond what annotations provide, such as permanence or error handling. Since annotations already convey the destructive and idempotent nature, this is adequate.

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

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

Three short sentences, each serving a purpose: statement of function, usage conditions, and relationship to sibling tools. No unnecessary words.

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

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

For a single-parameter destructive tool, the description provides purpose, clear usage triggers, and relation to companions. Annotations cover safety profile; no output schema is expected. The description is sufficiently 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 schema covers 100% of the parameter, including a description and example. The description mentions 'by key' but does not add new meaning beyond the schema's 'Memory key to delete.' 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 the specific verb 'Delete' with resource 'memory' and identifies the key parameter, making its purpose immediately clear. It also distinguishes from sibling tools by mentioning 'Pair with remember and recall,' which signals a distinct role in the memory workflow.

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

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

The description explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references related tools, providing context for when this deletion tool is appropriate versus memory storage or retrieval.

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

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

The description adds behavioral context beyond the annotations: it states the tool 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This is consistent with the readOnlyHint and idempotentHint annotations. No contradiction detected.

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 main purpose and outcome, followed by a concise 'Useful for' list. It is appropriately sized and does not waste words, though the list could be slightly trimmed 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?

The description covers the tool's purpose, process, output format, and use cases. Since there is no output schema, it explicitly states that the output is a 'single text blob ready to drop at site-root/llms.txt.' It does not address error handling or site accessibility requirements, but these are not critical for a simple 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 description coverage is 100% (both 'url' and 'max_links' have descriptions including default and max values). The description adds only a minor example URL format and reiterates the output, but does not significantly deepen parameter understanding beyond the schema.

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

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

The description uses a specific verb ('generate') and a specific resource ('llms.txt file for any URL'), and clearly distinguishes this tool from siblings like 'scan_competitor_ai_presence' by focusing on creating the file rather than scanning AI presence. It also states the output format (standard llms.txt markdown).

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, but it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond annotations by disclosing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope is 'caller's' subscriptions. This adds meaningful behavioral context without redundancy.

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 return fields and usage guidance. Every sentence earns its place with zero wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers the necessary context: what it does, what it returns, and when to use it. No gaps in understanding remain.

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

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

Schema coverage is 100% and the single parameter include_inactive is well-described in the schema. The description mentions 'active subscriptions' which aligns with the default behavior, but adds no additional semantic value beyond what the schema already provides. 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 'List the caller's active subscriptions' – a specific verb and resource. It also distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing, making its purpose unambiguous.

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

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

Explicitly provides when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly references the sibling operations (subscribe/unsubscribe) and gives context for when this tool is appropriate.

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

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

Annotations provide no safety hints (all false), so the description carries the burden. It discloses the claim_token mechanism, rate limiting ('Rate-limited to 5 per identifier per day'), and that filing returns a token for later follow-up. It also warns against pasting end-user prompts. This adds meaningful behavioral context beyond the structured fields.

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

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

The description is longer than typical, but every sentence conveys useful guidance. It is front-loaded with the core purpose, then logically flows through usage, exclusions, formatting, and follow-up. No wasted words, though the last sentence about team digests could be seen as motivational rather than strictly necessary.

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 explains the return behavior (claim_token flow), prerequisites (none required), rate limits, and exclusions. It fully compensates for the missing output schema and integrates cleanly with the input schema's full descriptions. Nothing critical is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), and by instructing users to describe issues in terms of Pipeworx tools rather than pasting prompts. This enriches the message parameter semantics.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like ask_pipeworx by framing it as feedback about the tools themselves, not as a general Q&A or research tool.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a strong exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This fully answers the when/when-not question.

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

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

Annotations already declare read-only and idempotent. The description adds valuable context: it's self-aggregating, derived from CF analytics-engine, contains no PII, and includes caching behavior (5min-1h). This goes beyond the annotations and describes data provenance and privacy.

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

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

The description is well-structured with a clear first sentence, a bulleted 'Useful for' list, and a final transparency sentence. It's slightly longer than necessary but each part serves a purpose.

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

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

For a read-only tool with one optional parameter, the description covers return values, use cases, data origin, privacy, and caching. Without an output schema, it adequately explains what to expect in the response.

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 tool description mentions the window values but doesn't add semantics beyond what the schema parameter description already provides ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). No additional parameter meaning is introduced.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now' and specifies the returns ('top tools, top packs, and total call volume'). It distinguishes from siblings like discover_tools by focusing on aggregate trending usage rather than general discovery.

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

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

The 'Useful for' list provides three concrete scenarios with clear context, such as discovering hot data sources and confirming canonical choice. However, it does not explicitly name alternatives or state when not to use the 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?

Annotations already declare readOnlyHint/openWorldHint/idempotentHint and destructiveHint=false, and the description enriches this with detailed behavior: no-arg default behavior, partition_filter thresholds (>20% placeholder returns null), fill_check pricing against live CLOB depth, and explicit advice that 'do not trade it' when realizable_edge_pp ≤ 0. This is far beyond what annotations alone convey.

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

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

The description is information-dense and well-structured, front-loading purpose and mode selection before diving into mechanics. It is long, but nearly every sentence adds value: examples, thresholds, response shape, and fill-check caveats. Only minor redundancy exists (e.g., repeating 'partition_check' details), so it loses a point for verbosity but remains strong.

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

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

Given the tool's complexity, the absence of an output schema, and rich annotations, the description is remarkably complete. It covers all modes, return fields, edge cases (placeholders, low similarity), behavioral caveats (fill check), and cross-references to related tools, leaving the agent with enough 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?

Although schema coverage is 100%, the description adds substantial meaning to the two parameters: event accepts slugs or full URLs and triggers partition_check, while topic accepts seed questions and triggers cross-event scanning with Jaccard similarity filtering. It also explains that no args produces a trending_scan, which is not evident from the schema alone.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' giving a specific verb, resource, and mechanism. It clearly distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by defining its unique arbitrage-detection role and even naming a related tool for custom sizing.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also states exclusions (e.g., placeholder slugs are dropped) and recommends polymarket_fill_risk for custom sizing, making the selection criteria 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 only declare readOnly/openWorld/idempotent hints, but the description adds extensive behavioral context: caching keyed on knobs, diagnostics revealing why segments are empty, a 24h-move warning, the unreliability of the Fed signal, and the rare-by-design nature of concentrated_longshot. No contradictions with annotations.

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

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

The description is a dense monolith with all-caps section headers, packing a high density of information. It is front-loaded with purpose but is not concise and would benefit from bullet points or short paragraphs. Every sentence carries technical detail, but readability suffers.

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 fully compensates by detailing the response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), the 24h-move warning, and diagnostic reasons for empty segments. It leaves little ambiguity about expected behavior.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful nuance, especially for min_partition_leg_kelly (explaining why parent-level Kelly is zero and how the knob applies to per-leg values) and the tradeable-edge knobs (min_liquidity/max_spread_pp) with behavioral intent.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also provides the intended use case ('what should I bet on today'), which clearly distinguishes 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 explicitly states when to use this tool ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and outlines tradeable-edge knobs for filtering. It does not explicitly name alternatives or when not to use it, but the intended context is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond that. It details the response structure, explains that snapshots are written on cache-miss and can have gaps, discloses the 60-day TTL, and clarifies that decay is computed from daily closes, not intraday. This is rich behavioral transparency that adds value beyond annotations.

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

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

The description is lengthy but well-structured, with clear sections for purpose, args, response, and limits. Every sentence carries useful information, though a few asides (e.g., 'the latter is wide for a reason nobody is willing to take', 'the median lifespan is your competition clock') are flavorful but not strictly necessary. It is appropriately sized for the complexity of the tool but could be slightly trimmed, hence a 4.

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

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

There is no output schema, so the description must carry the full burden of explaining the return value. It does this thoroughly, specifying the tracked[], expired[], and snapshot_dates[] arrays, their fields, and the meaning of each. It also defines limitations like TTL and gap behavior. Given the tool's complexity, the description is remarkably complete.

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

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

The input schema already covers both parameters fully (days with default and clamp, window with default and options). The description repeats this information nearly verbatim ('Args: days (lookback, default 14, max 30), window (snapshot family, default "1wk")'). Since schema coverage is 100%, the baseline is 3, and the description adds minimal additional semantic 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 clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers 'how long has this edge existed and is it shrinking?' It differentiates from siblings by focusing on time-series behavior rather than current edges, and provides a concrete use case comparing fresh vs. old wide edges.

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

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

The description implies when to use the tool (when edge history/persistence matters) and contrasts with a fresh vs. stale edge. It doesn't explicitly name alternative tools, but the context (sibling 'polymarket_edges') and the phrase 'built from daily polymarket_edges snapshots' make the intended usage clear. No exclusion statements are provided, so it gets a 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 (readOnlyHint, idempotentHint, non-destructive) cover the mutation risk, but the description adds substantial behavioral context: how it walks the order book, returns detailed fields, interprets size_usd differently by mode, and warns about partial basket fills converting arbs into unhedged directional positions. This goes far beyond what annotations provide and directly describes execution-level behavior.

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

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

The description is long but perfectly structured for the tool's complexity. It starts with a one-line purpose, then covers required inputs, systematically explains single-market and basket modes with uppercase section markers, and ends with concrete usage guidance. Every sentence carries essential information without redundancy, making it appropriately sized for a dual-mode tool.

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

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

Given the tool's complexity, lack of output schema, and four interrelated parameters, the description is remarkably complete. It enumerates all return values for both modes, explains the behavior of the 'verdict' field, identifies risk factors like thin_legs and forced_directional_risk, and covers both correct usage and failure modes. An agent has everything needed to invoke correctly 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?

Even though schema coverage is 100%, the description adds critical parameter semantics that the schema does not convey: size_usd means 'max spend' for single-market buys but 'settlement notional' for basket mode; side defaults to 'auto' in basket mode; and the market/event mutual exclusivity is clarified. This materially improves an agent's ability to set parameters correctly.

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', and then clearly differentiates the two modes (single-market and basket) and their outputs. It explicitly names sibling tools polymarket_arbitrage and polymarket_edges, establishing its distinct role in the workflow.

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

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

It states the required input ('REQUIRES one of market or event') and gives explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. This tells the agent exactly when to invoke this tool and why, with no ambiguity.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description goes much further by explaining the tool's behavior: compatibility_warning cases, temporal_alignment, skipped_cross_type/subtype counters, and the condition 'aligned:false means spreads are mathematically meaningless across the temporal gap.' This adds substantial value beyond the annotations and contradicts nothing.

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

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

The description is long but well-structured with clear sections (two modes, response, safety fields). Every sentence carries substantive information and there is no filler. The length is justified by the tool's complexity, though it could be slightly more scannable with bullet points.

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

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

With no output schema, the description fully explains the return format: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp (Kalshi − Polymarket).' It also documents all safety fields, the meaning of skipped counters, and the caveat about real spreads being rare. This is complete for a complex tool.

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

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

The schema descriptions cover each parameter, but the tool description adds rich semantics: it explains the two-mode interaction (topic vs explicit overrides), lists all 10 macro shortcuts for `topic`, gives concrete examples for the ticker/slug parameters, and clarifies how overrides affect the mapped side. This goes well 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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue spread with explicit venue names and outcome matching.

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

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

The description provides clear context for use: two modes (topic shortcuts and explicit tickers/slugs) and a strong caution that 'pre-mapped ≠ tradeable' and compatibility_warning should be checked. It does not explicitly name alternative tools to use instead, but it gives enough context about when the tool is meaningful (equivalent bet shapes, temporal alignment) and when it is not.

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 safety profile is covered. The description adds valuable context beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys by omitting the argument. Does not contradict annotations.

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

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

Three sentences, each earning its place: the first states the core action, the second explains when to use it, and the third adds scoping and pairing context. No redundancy or fluff; information is front-loaded.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers usage: how to retrieve, how to list, when to use, and how it relates to siblings. There are no significant gaps.

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

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

Schema description coverage is 100%, with the 'key' parameter already described as 'Memory key to retrieve (omit to list all keys).' The description adds only the 'previously saved via remember' nuance, but the schema carries the semantic load. 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 with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It also distinguishes itself from sibling tools by explicitly pairing with 'remember to save, forget to delete.' 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 explicit guidance on when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternative siblings (remember, forget) and describes how they relate, making the usage context very clear.

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

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

The description discloses a mutating behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the annotation readOnlyHint=true, which implies the tool does not modify state. Since the description contradicts the annotation, the transparency score is 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 three sentences, immediately states the core purpose, and each subsequent sentence adds valuable detail about return data, filtering, mark_read behavior, and an alternative access endpoint. There is no filler, and the structure is front-loaded with the primary function.

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 five parameters and no output schema, the description covers the return payload, filtering, mark_read state effect, and polling suitability. It also provides an alternative endpoint. It lacks explicit pagination details, but the limit parameter is documented in the schema. It is reasonably complete, though the contradiction with annotations is a notable gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing an example filter ('sec_8k'), clarifying the 'since' parameter as an ISO timestamp for fired_at, and explaining the effect of mark_read on subsequent calls. It also mentions return fields (source, citation_uri, raw event payload) that correspond to the event data, enriching 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 clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (alerts from the feed) and the action (pull), and distinguishes itself from siblings like recent_changes by focusing on alerts and the persisted feed. It also details the return payload and filters, 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 description provides usage context by noting that 'Polls work fine' and offering an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. However, it does not explicitly compare to sibling tools like recent_changes or list_subscriptions, so it lacks explicit exclusions or when-not-to-use guidance. Clear context is present, but no alternative tool comparisons are mentioned.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses fan-out architecture to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-failure due to PatentsView API sunset. It also specifies `since` format and return structure, providing rich behavioral context beyond the structured fields.

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

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

The description is dense but every clause earns its place: query patterns, data sources, fallback behavior, date syntax, return shape, and alternative tool. It front-loads the most searchable use-case phrases and avoids fluff, making it an efficient reference.

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 multi-source fan-out tool with no output schema, the description is remarkably complete: it explains the sources, fallback order, a known future failure mode, `since` formats, return fields (changes[], total_changes, citation URIs), and the sibling to use instead. This fully equips the 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?

Input schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds valuable semantic detail by explaining `since` supports both ISO dates and relative shorthand ('7d', '30d', '3m', '1y'), and recommending '30d' or '1m' for typical monitoring. It also clarifies `value` accepts ticker or CIK, slightly exceeding 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 opens with concrete user intents ('What's new with X', 'latest on Y') and defines the resource as 'change feed for a company in the last N days/weeks/months'. It clearly distinguishes this from the sibling entity_profile by explicitly naming the alternative for static profiles.

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

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

It provides explicit when-to-use guidance via natural language query examples and notes the tool fans out in 'ONE parallel call'. It also gives a direct exclusion: 'Use entity_profile instead when you want the static profile... regardless of window', naming the specific alternative.

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

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

Annotations already mark this as non-read-only and idempotent. The description adds scoping ('scoped by your identifier') and persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), plus retention limits. 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 tight and front-loaded: purpose in the first sentence, usage in the second, behavior in the next two, and sibling references in the last. No wasted words.

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

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

For a tool with a simple two-parameter schema and no output schema, the description covers the full lifecycle: what to save, when, persistence behavior, and how it relates to recall/forget. It is fully actionable for an agent.

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

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

Schema coverage is 100% with both key and value described in detail. The description reinforces the key-value nature and supplies domain examples ('resolved ticker', 'target address'), but does not add new syntax beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It then names sibling tools ('recall to retrieve later, forget to delete'), clearly distinguishing this write operation from its read and delete counterparts.

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 tells when to use the tool ('when you discover something worth carrying forward') and gives concrete use cases. It also directs the agent to related tools ('Pair with recall to retrieve later, forget to delete'), providing clear alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: it cascades through multiple endpoints, degrades gracefully (if GLEIF/OpenFIGI unavailable, EDGAR still returns), and explicitly states that unresolved identifiers appear in an 'unresolved' field rather than being omitted. 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 verbose (6-7 sentences) but well-structured: front-loaded with examples and usage guidance, followed by detailed explanations of supported types. Every sentence adds value, though some details could be more concise for faster agent parsing.

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

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

No output schema is provided, so the description must cover return behavior. It explains identifier labeling, unresolved items, and graceful degradation. For a tool with two parameters and internal complexity, this is quite complete. A slight gap is the lack of explicit output structure, but the description compensates with rich detail.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial semantics beyond the schema: for 'company' it explains it accepts ticker, CIK, ISIN, or name, and details ISIN-to-LEI mapping; for 'drug' it specifies RxCUI, ingredient, brand. This enriches agent understanding significantly.

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

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

The description clearly states the tool resolves names to canonical identifiers, provides specific examples ('What's the ticker for...'), enumerates supported types (company, drug), and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from other tools like entity_profile and 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?

The description gives strong guidance ('Use FIRST whenever you have a name but need an ID') and explains the exact inputs for each type. It implies this is the primary tool for name-to-ID conversion but does not provide explicit when-not-to-use instructions or list alternatives among the many sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains the tool probes each entity with ai_visibility_check, ranks results by score, and returns a ranked list with score/confidence/signal density. This gives the agent a clear picture of what the tool does internally without contradicting the annotations.

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

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

The description is three concise sentences, leading with the primary action and then covering mechanism and use case. Every sentence earns its place with no redundancy or fluff, making it easy for an agent to parse quickly.

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

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

Given the absence of an output schema, the description explicitly mentions the return format (ranked list with score, confidence, signal density), which is essential for the agent to interpret results. Combined with strong annotations and a clear usage context, the description is fully sufficient for correct 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 provides 100% parameter coverage with detailed descriptions, including the special role of the first entity. The description does not add significant new parameter-level meaning beyond what the schema already offers, 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing itself from sibling tools like ai_visibility_check by emphasizing side-by-side comparison and ranking. It also mentions the mechanism (probing with ai_visibility_check) and outcome (most/least recognized), 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 description gives a clear use case ('competitive AI-marketing audits') with a concrete example question, indicating when this tool is appropriate. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of the strongest guidance seen in high-scoring examples.

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

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

The description goes beyond annotations by explaining graceful degradation: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out.' It also discloses that it fans out to two external services and the NPM-only scope, which are not captured in the readOnly/idempotent annotations.

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

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

The description is dense but efficient, front-loading the core purpose and use case. Every sentence provides value: purpose, trigger examples, return fields, ecosystem scope, and failure behavior. Despite its length, it avoids fluff and is well-structured.

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

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

The description comprehensively covers what the tool returns (summary block with specific fields, advisories, links, alternative versions), the NPM-only limitation, and failure modes. Given the tool's complexity (composite external checks) and lacking an output schema, this level of detail is thorough and 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?

Schema coverage is 100% and the schema itself provides clear descriptions for 'package' and 'version' (including scoped packages and defaulting to latest). The description adds no additional parameter-level semantics, but because the schema fully documents the parameters, 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 purpose: a composite npm package evaluation check using deps.dev and bundlephobia. It specifies the exact resources scanned (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support) and provides a precise use case, distinguishing it from sibling tools focused on AI visibility or entity research.

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

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

It explicitly says to use when an agent asks safety/popularity/size questions (e.g., 'is X safe / popular / small' or 'what does adding lodash cost me'). It also gives a clear when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' effectively routing to an alternative for non-NPM ecosystems.

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

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

Annotations already mark the tool as readOnly and idempotent. The description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character limit with truncation flagging, and the offset property for verbatim quote verification. These details go beyond the annotations and give the agent realistic expectations about input size and output structure.

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, well-structured paragraph that front-loads the core function in the first sentence, then covers usage, output, technical implementation, and limits. Every sentence adds relevant 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 read-only search utility with no output schema, the description covers input expectations, output shape (passages, offsets, similarity scores), technical constraints, truncation behavior, and integration with ask_pipeworx_grounded. It provides a complete picture for correct invocation and interpretation of 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%, with each parameter described. The description enriches the parameters by providing concrete examples for 'text' (SEC 10-K body, article, long tool result) and for 'query' (e.g., 'supply-chain risk', 'fiscal year 2024 revenue'). It also reinforces the character cap mentioned in the schema, adding semantic value 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 'Semantic search INSIDE a fetched record,' clearly stating the verb (search), the resource (a fetched record), and the output (top-N passages with offsets and similarity scores). It also differentiates from the sibling ask_pipeworx_grounded by framing a fetch-then-search workflow, making the tool's distinct role clear.

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

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

The description gives an explicit condition: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding over relevant passages. This provides clear context for when to use the tool, though it does not explicitly state exclusions or mention alternative tools like ask_pipeworx for whole-document search.

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 richly discloses behavioral traits: OAuth account requirement for persistence, 10/day SMS cap, webhook auto-disabled after 10 consecutive failures, and one-time webhook signing secret. With annotations already declaring readOnlyHint=false, the description adds critical context about prerequisites and failure modes without contradicting any annotations.

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

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

The description is dense but well-structured: main purpose first, then supported types with examples, then delivery channels and constraints. Every sentence provides useful operational detail, with no filler or redundancy. Despite its length, it is efficiently organized and easy to scan.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery options) and no output schema, the description covers all necessary aspects: prerequisites, return value, parameter formats, delivery behavior, and limits. It gives an agent everything needed to invoke the tool correctly and handle potential failures.

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

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

Even though schema coverage is 100%, the description adds significant meaning beyond the schema: concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id), detailed delivery object behaviors, and webhook signing specification. This transforms the schema from bare types to actionable usage guidance.

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 'Create a proactive monitoring subscription to a live-data event stream,' using a specific verb and resource that clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also describes the return value (new subscription id) and supported event types, making the tool's 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 clearly states when to use the tool (for monitoring live-data streams) and provides constraints (requires OAuth account, verified phone for SMS, delivery channel options). It indirectly references alternatives by noting 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json' for feed consumption, but does not explicitly say 'use X instead of this' for other sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to cover safety. It adds useful behavioral context: output is drawn from a live catalog, includes category buckets and tool shapes, and supports optional topic filtering. No contradictions found.

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

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

A dense but well-organized single paragraph. It front-loads example queries, then explains what it returns, how to call it, and when to use it. No filler or redundant statements; every sentence contributes actionable information.

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

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

Despite having no output schema, the description fully explains what the tool returns (category-bucketed questions with tool/argument shapes), how to invoke it (no args or topic), and when to use it (onboarding). It also connects to related meta-tools, making it complete for an agent's decision-making.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the 'focus' behavior, providing example values (finance, pharma, betting), and noting that omitting topic returns a cross-category spread. This adds real value over the raw schema.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape needed to answer them. It distinguishes itself from siblings like discover_tools and ask_pipeworx by positioning itself as the 'first' thing to use when unsure what Pipeworx can do.

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. While this is strong context, it doesn't provide explicit when-not-to-use or alternative tool recommendations beyond naming meta-tools.

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

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

The description adds valuable behavioral detail beyond annotations: ownership enforcement and the fact that the row is deactivated (not deleted), preserving historical events. This complements readOnlyHint=false, destructiveHint=false, and idempotentHint=true without contradiction, giving the agent a clear mental model of the tool's side effects.

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

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

Three sentences, each carrying distinct information: action (cancel), ownership (only own), and side effect (deactivated, history remains). No fluff or redundancy; the most important info is front-loaded.

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

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

For a simple one-parameter mutation with good annotations, the description is complete. It covers the action, ownership constraint, and consequences, and even points to recent_alerts for historical data. No output schema is present, but the description adequately sets expectations for a cancellation operation.

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 id parameter with 100% coverage, so baseline is 3. The description adds an important constraint: the id must be the caller's own subscription (ownership), which is not explicit in the schema. This extra semantic meaning justifies a score above baseline.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe (creation) and list_subscriptions (listing) by specifying the cancellation action and the deactivation behavior rather than deletion.

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 usage context: ownership is enforced ('you can only cancel your own subscriptions'), which is a when-not condition for cancelling others' subscriptions. It also directs users to recent_alerts for historical events, serving as an explicit alternative for viewing past data after cancellation.

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

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

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds indispensable behavioral context: the distinction between could_not_verify (pipeline failure, not evidence) and unsupported (not covered), the SEC/XBRL fast path vs grounded pipeline, and the tolerance override semantics. This prevents misuse of potentially ambiguous verdicts.

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

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

The description is longer than the TDQS high benchmark but is front-loaded with trigger phrases and purpose. It's organized into clear sections (purpose, return value, caveats) and every sentence earns its place, covering complex behavior without redundancy.

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

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

With no output schema, the description compensates by enumerating the six verdicts, explaining the verification_error field, mentioning the pipeworx:// citation, and clarifying the meaning of unsupported. The tool's complexity (two paths, tolerance logic, edge cases) is thoroughly covered, giving an agent everything needed for correct 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 schema already covers both parameters with clear descriptions, but the description enhances tolerance_pct with practical guidance (set 1–2 for hallucination detection) and gives concrete claim examples. This adds meaningful usage context beyond schema documentation, though schema coverage is already 100%.

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 natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and states the tool's function: claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by describing the two-path routing (SEC EDGAR for company-financial, grounded pipeline for everything else) and positioning itself as a replacement for a multi-step pipeline.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and lists common phrasings. It also differentiates between company-financial claims and other factual claims, explaining which path handles each, giving clear and actionable guidance without ambiguity.

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