xkcd

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds beyond this by disclosing cost implications (BYO Anthropic key, pay directly, free default) and the return shape (per-model score, confidence, signals, raw_response). This is valuable behavioral context not present in annotations.

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

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

The description is three sentences that front-load the main action, then efficiently cover default, cost, output, and usage cases. No filler or repetition; each sentence adds unique value.

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

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

With no output schema, the description compensates well by describing the per-model result structure and combined view. It also covers defaults, cost, and use cases. Minor gap: it does not explain what 'signals' contains or how the score is computed, but the overall tool behavior is sufficiently complete for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful param context by explaining the default model and the purpose of _apiKey (to also probe Anthropic with BYO key and direct payment), which goes slightly beyond the schema's simple parameter descriptions.

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

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

The description opens with a specific verb ('Probe') and clearly defines the resource (one or more LLMs) and the output (visibility score 0-100 per model). This distinguishes it from siblings like ask_pipeworx, which answer questions rather than score AI visibility.

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

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

Explicit use cases are given ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which helps an agent decide when to invoke it. It does not explicitly name alternative tools or negative usage conditions, but the context is clear enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it routes to thousands of sources, returns structured answers with pipeworx:// citation URIs, and is described as 'one fast call' that 'works on every tier.' This exceeds the baseline 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 long but well-structured, front-loading the primary directive in bold and using examples. Every sentence contributes useful information—domains covered, alternatives, and disambiguation. It is slightly verbose, but the complexity of the tool justifies the length.

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

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

For a meta-tool with enormous scope and no output schema, the description provides complete context: what it does, when to use it, when to prefer alternatives, what it returns (structured answer with citations), and that it is the default entry point. An agent selecting this tool has all necessary information.

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

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

The input schema has 100% coverage, explaining the 'question' parameter and its aliases. The description enriches this with domain examples and sample questions like 'current US unemployment rate' and 'Apple's latest 10-K', giving the agent concrete guidance on how to phrase effective queries, which adds value beyond the schema.

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

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

The description clearly defines the tool's function as a universal router: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It also explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, establishing its unique role as the default entry point.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH' for factual questions, 'START HERE' for most questions, and clear alternatives: 'Step up only when needed' for ask_pipeworx_grounded and deep_research. It even addresses breaking news and gives concrete examples of trigger phrases and sample queries, making when-to-use or when-not-to-use unmistakable.

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 the readOnly, openWorld, and idempotent annotations by revealing that the tool is experimental, with candidate routing improvements enabled live whenever under test. It also notes that no candidate is currently active, so it matches ask_pipeworx exactly, and that it falls back to nothing—it is a fully working router. This is critical behavioral context for an experimental tool that might behave differently in the future.

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 paragraph of four sentences, front-loaded with the purpose in the first sentence. Each sentence provides relevant context (current state, usage, experimental nature), so it is not wasteful. It is slightly verbose for a description, but all information is valuable.

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 experimental nature, current behavior, and usage guidance, and states 'same response shape' which partially addresses return value expectations given no output schema. Since the agent can infer details from the sibling ask_pipeworx, this is mostly complete. However, it could benefit from more explicit details on response content or limitations.

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 100% of parameters, listing 'question' and its aliases. The description adds only 'same arguments' as a reference to ask_pipeworx, providing no additional semantic meaning beyond the schema. The baseline of 3 applies since the description does not need to compensate for schema gaps.

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

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

The description clearly states it is a beta version of ask_pipeworx with the same universal router, tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting the experimental routing improvements and current state where no candidate is active, making it behave identically. The verb 'ask' plus resource 'pipeworx beta' provides a specific and clear purpose.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This gives clear context for when to use it and implies that the stable version is the alternative. However, it does not explicitly state when not to use it, such as when stability is preferred, though the 'newest routing' phrasing implies the experimental edge.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive; the description adds substantial detail: returns a structured contract with {answer, evidence, confidence, source, fetched_at, refusal_reason}, explicit refusal reasons, and behavior of extracting only from tool result. It also mentions the extra LLM call cost.

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

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

Dense but every sentence carries useful information. The description is slightly long with multiple clauses, but it front-loads the purpose and then logically explains routing, return contract, use cases, and cost trade-off. No wasted words.

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

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

Given the tool's moderate complexity, it fully explains the routing behavior, the success and refusal return shapes, the extra call cost, and when to prefer the sibling. The schema covers parameters and annotations cover safety, so the description completes the operational picture.

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

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

Schema description coverage is 100%, with each parameter documented as an alias for question. The description does not add parameter-specific semantics, but the schema fully covers the one semantically meaningful parameter. 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, differentiates from sibling ask_pipeworx by 'grounded' and explicitly mentions 'Same routing as ask_pipeworx' while adding extraction-only-from-result behavior. The description names the specific resource (Pipeworx) and the distinctive guarantee (no invented facts).

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and lists examples (financial verdicts, legal claims, medical lookups, public statements). Also gives when-not: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, making the trade-off concrete.

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

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

The description goes far beyond annotations, disclosing resolver contract, safety mechanisms (low-confidence short-circuit, closed market handling), blocking behavior, news fallback fields, and resolution-rule risks. It also notes that statuses are blocking, providing critical behavioral context not evident from readOnlyHint or other annotations.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section contributes distinct information, and the front-loaded opening sentence states the core purpose. It is not excessively repetitive, though it is detailed enough to be considered more than minimally concise.

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

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

With no output schema, the description thoroughly explains return values including result.market, result.analysis, result.evidence, result.parent_event, and various statuses. It also covers edge cases like low-confidence matches, closed markets, and cancellation risks, making it 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?

Schema coverage is 100% with descriptions for all three parameters. The tool description adds context about response shapes and fan-out examples but does not significantly enhance parameter meaning beyond the schema, which already explains market input types, depth options, and include_raw behavior. 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and process (resolving, classifying, fanning out to data packs), and distinguishes it from sibling tools by focusing on a single bet with evidence gathering.

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

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

Explicit usage is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5 which would require explicit exclusions or alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This goes beyond what annotations provide.

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

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

The description is dense but well-structured: it opens with trigger phrases, then states the core function, then provides per-type details, then output format. Every sentence contributes actionable information with no filler.

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

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

Considering the tool's complexity and lack of an output schema, the description covers input constraints (2–5 entities), data sources, fiscal-year handling, sorting behavior, and output format (paired data + citation URIs). It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant semantic meaning for the 'type' parameter, detailing exactly what data each entity type retrieves (10-K metrics vs. FAERS/FDA/trial counts). It also clarifies the 'values' parameter with examples and constraints. This exceeds the baseline for high schema coverage.

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

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

The description clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies a concrete verb and resource, and distinguishes itself from single-entity lookups by noting it 'Replaces 8–15 sequential lookups.'

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

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

Explicit guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and trigger examples like 'X vs Y' and 'rank these companies.' This clearly tells the agent when to use this tool and when not to (i.e., instead of sequential 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?

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior, but the description adds extensive context: account tier requirements, gap[] handling to avoid invented answers, fetchable citation_uri logic, contradictions[] scans, semantic excerpting of large records, and anticipated latency. These details go far beyond annotation hints and align with them.

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

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

The description is information-dense with every sentence adding value, but it is a single run-on paragraph of roughly 200 words, front-loading account requirements before the core purpose. The lack of paragraph or list structure makes it harder to scan, so it is not optimally concise despite containing no fluff.

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

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

Given there is no output schema, the description thoroughly explains the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] behavior, contradictions[] for standard/thorough, hop field, and citation_uri resolvability. Combined with full schema coverage and rich annotations, an agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% with detailed depth-level explanations, so the baseline is 3. The description adds the meaningful constraint that depth:'thorough' requires a paid plan and provides example question phrasings, which are not present in the schema, warranting a 4.

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

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

The description states a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly differentiates itself from open-web search and names sibling ask_pipeworx as the alternative for simpler or current-news needs, making the purpose unambiguous and sibling-distinct.

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/not-use guidance: prefer ask_pipeworx when not signed in, for single lookups, or for breaking/current-news topics because deep_research would return empty gaps. It also explains depth choices, noting standard recovers gaps and thorough is paid, giving clear directives for tool selection.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds valuable behavioral context by explaining the return format (top-N results with names, descriptions, schemas, and curated examples) and the 'no second schema lookup needed' efficiency. This goes beyond what annotations provide without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds information: what it does, when to use it, and what it returns. No redundant or filler content exists.

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

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

Given the tool's moderate complexity (6 parameters, no output schema) and strong annotations, the description is complete. It covers purpose, usage context, return format, and even examples, making it easy for an agent to invoke correctly without needing to infer missing 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 description coverage is 100%, so the baseline is 3. The description adds meaning by showing example queries ('analyze housing market trends'), listing relevant domains, and mentioning 'top-N', which correlates with the limit parameter. This elevated it slightly 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 uses a specific verb ('Find tools') and identifies the resource ('tools by describing the data or task'). It clearly distinguishes this tool from siblings, which focus on performing tasks like research or entity profiles, by emphasizing discovery and enumeration of available tools. The domain list further clarifies the scope.

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

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

The description provides explicit 'Use when' conditions and recommends calling it FIRST when many tools are available. It stops short of naming specific alternatives or stating when NOT to use it, but the guidance is clear and actionable for parameter selection and tool selection.

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

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

Annotations already mark it as read-only and non-destructive. The description adds meaningful behavioral details: data source fan-out (SEC EDGAR, XBRL, USPTO, news, GLEIF), soft-fail behavior for patents (USPTO sunset), fallback chain (GDELT→GNews), and the exact return fields including URI format for filings. No contradiction with annotations.

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

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

The description is long but information-dense, front-loading with examples and the core purpose. The seven example trigger phrases are somewhat redundant, but they serve as pattern recognition. Every other sentence adds necessary detail about sources, outputs, and fallbacks. Slightly overlong due to examples, hence 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?

No output schema exists, so the description fully compensates by listing every return field (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and noting limitations. This is complete for a complex multi-source tool.

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

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

Schema description coverage is 100%, and both parameters (type, value) are well described there. The description essentially repeats the same parameter guidance (ticker/CIK, names not supported, use resolve_entity), adding no new semantics. Baseline 3 is appropriate since the schema carries the burden.

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 core function: producing a 'full cross-source profile of a US public company in ONE parallel call.' It includes multiple trigger examples and explicitly distinguishes itself from chaining separate SEC/XBRL/news lookups, a key differentiator from 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?

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent when to use resolve_entity first ('names not supported'), and what input formats are acceptable (ticker or CIK). This is clear when-to-use and alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds rationale (clearing sensitive data) and pairing guidance, but does not elaborate on failure behavior or permanence beyond what annotations imply.

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 concise sentences, front-loaded with the primary action, followed by usage context and a pairing hint. Every sentence earns its place with no redundancy.

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

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

For a simple one-parameter tool with no output schema and strong annotations, the description covers purpose, when-to-use, and relationship to peers. Nothing significant is missing.

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

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

Schema description coverage is 100% – the single parameter 'key' is described as 'Memory key to delete'. The description echoes this ('by key') but does not add additional semantics or constraints 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 'Delete a previously stored memory by key' with a specific verb and resource, and the by-key scope distinguishes it from siblings like remember (store) and recall (retrieve).

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 conditions: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also directs pairing with remember and recall, clarifying the tool's role within the memory tool family.

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, covering the safety profile. The description adds valuable behavioral context by explaining the fetch/extract/emit pipeline and that the output is a single text blob in markdown format. It does not contradict annotations.

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

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

The description is concise and well-structured: three sentences plus a 'Useful for' list. The primary action and outcome are front-loaded, and every sentence adds value 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?

Even without an output schema, the description compensates by clearly stating the output format (single text blob in llms.txt markdown). It covers inputs, process, output, and typical use cases, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage for both parameters (url and max_links) with clear descriptions. The tool description does not add additional parameter-specific semantics beyond what the schema already contains, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's deliverable (a production-ready llms.txt file) and the process (fetches the page, extracts title/description/key links, emits markdown). It is specific and distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing solely on llms.txt generation.

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

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

The description provides a 'Useful for' list with three concrete scenarios (client's site indexing, own project drafting, competitor auditing), giving clear context for when to invoke the tool. However, it does not explicitly name alternatives or exclusion criteria, which would warrant a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by disclosing the exact return contents (title, image URL, alt text, date, transcript, permalink), which goes beyond annotations and helps the agent set expectations. 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?

A single, focused sentence that front-loads the core action and resource, then efficiently lists the return fields. Every word earns its place, and there is no redundant or vague phrasing.

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

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

This is a simple one-parameter tool with a clear description, a complete input schema, output schema, and annotations that declare it safe and idempotent. The description covers purpose, parameter, and return content, so it is fully complete for an agent to select and invoke this tool correctly. Minor sibling differentiation gaps are captured in the usage_guidelines dimension.

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

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

The input schema already describes the 'number' parameter thoroughly (type, examples, and meaning), giving 100% coverage. The description reinforces this with a concrete example ('353 for \'Python\'') but adds no new syntax or constraints beyond the schema, so it is at 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 uses a specific verb ('Fetch') and clearly identifies the resource ('a specific XKCD comic') with the key differentiator 'by its number'. It also lists the returned fields, making the purpose unambiguous and easily distinguishable from sibling tools like random_comic or get_latest.

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

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

The description clearly implies when to use this tool: when you have a specific comic number in mind. However, it does not explicitly name alternatives or state when not to use it (e.g., use random_comic for a random comic, get_latest for the most recent). Despite this, the context is clear enough for basic 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 read-only, non-destructive, and idempotent behavior. The description adds value by enumerating the exact return fields (comic number, title, image URL, alt/hover text, date, transcript if available, permalink) and highlights the dynamic nature of 'most recently published.'

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

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

The description is two sentences, front-loaded with the primary purpose and followed by a concise list of return fields. Every word contributes value with no redundancy.

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

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

For a simple, parameterless tool with strong annotations and an output schema, the description is quite complete. It covers the core functionality and return values, though it could have added a note on when to use this versus sibling comic tools, which is a minor gap.

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

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

The tool has zero parameters, so the schema provides no additional meaning. The baseline for zero parameters is 4, and the description appropriately focuses on the output, which matches this baseline.

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

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

The description clearly states the tool fetches the most recently published XKCD comic, using a specific verb and resource. It distinguishes itself from sibling tools like get_comic and random_comic by explicitly focusing on the latest comic.

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 usage when the latest XKCD comic is needed, but it does not explicitly mention alternatives or contraindications. The sibling names provide context, but the description itself lacks explicit when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's subscriptions. This goes beyond the structured annotations.

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

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

The description is two sentences, front-loaded with the purpose and return fields, then a concise usage tip. No redundant words or fluff.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It explains the return fields and provides a clear use case, making it fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with the include_inactive parameter already described. The description does not add much parameter-level meaning beyond implicit mention of 'active subscriptions,' so a baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('List') on a specific resource ('the caller's active subscriptions'). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions for review and finding IDs to cancel.

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

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

The description provides clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies alternatives (subscribe/unsubscribe) but does not explicitly name them or state exclusions, 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?

The description discloses behavioral details beyond annotations: filing returns a claim_token, passing it back later retrieves status/resolution, rate-limited to 5/day, free, and team reads digests daily. Annotations only state flags (readOnlyHint=false, destructiveHint=false), which are not contradicted. This extra context significantly aids agent decision-making.

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

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

The description is longer than average, but every sentence earns its place: purpose, usage, exclusions, content rules, token workflow, rate limit, cost. It is front-loaded with the main action and reads naturally, 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 4-parameter tool with a nested context object and no output schema, the description covers all aspects an agent needs to invoke and follow up correctly: what to report, when to use it, what to avoid, token-based retrieval, and practical constraints (rate limit, cost). This is a fully self-contained description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the claim_token lifecycle (filing returns token; passing it alone reads the reply) and gives content guidance for the message field ('describe in terms of Pipeworx tools/packs, don't paste the end-user's prompt'). This justifies a 4.

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

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

The description opens with a clear, specific verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly differentiates from sibling tools by framing this as feedback (bug/feature/praise) rather than a question or research request, and even excludes other MCP servers to avoid misrouting.

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 scenarios (bug, feature/data_gap, praise), a clear exclusion ('if the tool came from a different MCP server... file it with that server instead'), and content guidance (don't paste the end-user's prompt). This is exemplary usage guidance that prevents common mistakes.

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, so the agent knows the safety profile. The description adds valuable context: it's a self-aggregating signal from CF analytics-engine with no PII, and caching behavior varies by window (5min–1h). This goes beyond annotations but doesn't cover rate limits or failure modes, so a 4 is appropriate.

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

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

The description is moderately sized but every sentence contributes: purpose, return value, use cases, data source, privacy, and caching. It's front-loaded with the main purpose and structured nicely. Not overly verbose, though it could be trimmed slightly without losing critical information.

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

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

Given no output schema, the description adequately summarizes the return content (top tools, packs, total call volume). For a simple tool with one optional parameter, it covers the key aspects: what it does, when to use, data source, privacy, and freshness. It doesn't detail the exact response shape or error handling, but that's acceptable for this complexity level.

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

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

Schema coverage is 100% for the only parameter 'window', with an enum and default value described. The description adds semantic meaning by explaining the trade-off between shorter and longer windows ('hot right now' vs 'steady-state demand'), which is not fully present in the schema. This enhances the parameter's meaning beyond 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 clearly states the tool 'Returns the top tools, top packs, and total call volume' over a recent window, using a specific verb and resource. It distinguishes itself from siblings like 'discover_tools' by focusing on aggregate trending activity rather than individual tool discovery, making its purpose unmistakable.

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

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

The description explicitly lists three 'Useful for' scenarios (discovering hot data sources, confirming canonical choices, aligning use cases) and provides window-selection guidance ('shorter windows surface what's hot; longer windows show steady-state'). It doesn't explicitly mention when not to use or alternative tools, but the context is clear enough to guide an agent.

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

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

Despite annotations already declaring readOnly=true, openWorld=true, idempotent=true, destructive=false, the description adds rich behavioral context: the semantic anchor (Jaccard similarity threshold), partition filter (placeholder fraction >20% returns null), and the fill check (realizable_edge_pp ≤ 0 means do not trade). This goes well beyond the annotation coverage.

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

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

The description is lengthier than typical, but every sentence conveys essential information. It is front-loaded with a clear summary, then details modes, filters, response format, and fill check. While dense and structured, it could be slightly more concise by trimming some redundancy (e.g., repeating the recommendation to use event mode).

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly documents the response structure (opportunities[], partition_check) and edge cases (skipped_low_similarity, null arb scenario, fill check caveat). It is complete enough for an agent to understand what to expect and when to act.

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%, but the description significantly augments meaning: it provides concrete slug examples, clarifies what each mode does with the parameter, and explains the internal processing steps. For instance, it describes how 'event' walks child markets and computes partition_check, which is not in the schema.

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

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

The description opens with a precise statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three invocation modes (default trending_scan, event, topic) and differentiates itself from sibling tools by naming polymarket_fill_risk for 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?

Explicitly specifies when to use each mode: 'Call with NO args for a trending_scan... pass event... pass topic...'. It also recommends event mode for a specific market, explains when cross-event mode is preferable, and references an alternative tool: 'For custom sizing use polymarket_fill_risk.'

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), diagnostics for empty segments ('why a segment is empty'), edge calculation nuances (edge_pp_net after slippage, Kelly caps at 0.25), and design caveats (Fed bets excluded, rare-by-design for concentrated longshots). This substantial extra context helps agents predict tool behavior accurately.

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 dense with information, systematically covering purpose, segments, per-opportunity fields, knobs, and diagnostics. It is front-loaded with the core value proposition and every sentence adds needed detail for a complex tool with 9 parameters and a rich response structure. No redundant or vague phrasing.

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

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

Without an output schema, the description carries the burden of explaining return values. It details the top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), enumerates per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and explains why segments might be empty. This is thorough for a read-only scanning tool, covering caching, filtering, and edge cases.

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

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

Input schema covers 100% of parameters, so the baseline is 3. The description adds practical value by explaining the rationale for tradeable-edge knobs (e.g., 'Set to 2 to require tight books'), noting the usual slippage magnitude (20-50bp), and clarifying that min_kelly does not apply to partition arbs. These insights go beyond the schema's field descriptions.

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

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

The description opens with a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the verb, resource, and outcome. It also distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing the Pipeworx data disagreement rather than generic arbitrage scanning.

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 its intended use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear context for when to use it. However, it does not explicitly name alternative sibling tools or provide when-not-to-use guidance, so it misses the top tier.

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, but the description adds substantial behavioral context: limits on history depth (60-day TTL, snapshot start), the fact that decay is computed from daily closes (not intraday), and the explanation that gaps in snapshot_dates mean 'nobody scanned that day'. This goes well beyond the annotations and provides critical operational transparency.

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

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

The description is dense but extremely well-structured, with clear sections for the core purpose, arguments, response format, and limits. Every sentence contributes value—no filler. It front-loads the core question and then provides necessary detail in a structured way. This is a model of conciseness for a complex 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?

Despite having no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) and key fields (trend, decay_pp_per_day, lifespan_days). It also covers data caveats (TTL, snapshot gaps, slippage adjustment). This is complete enough for an agent to invoke the tool and interpret results without external knowledge.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the parameters (days, window) with defaults and max values, but does not add new meaning beyond what the schema provides. The RESPONSE section provides context on how parameters affect output, but that is more about output behavior than parameter semantics. Thus a 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This is a specific verb+resource description that distinguishes it from siblings like polymarket_edges, which likely provides fresh edge scans, by focusing on historical persistence and decay.

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 context: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)'. This clearly implies when to use the tool (to assess edge age/decay before trading). However, it does not explicitly name alternatives or list when-not-to-use scenarios, so it stops short of a full 5.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), identifies thin legs, reports max_fillable_usd and forced_directional_risk, and warns about partial basket fills. This gives the agent a concrete model of what the tool inspects and what risks it flags.

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?

Though long, the description is carefully structured with uppercase mode labels (SINGLE-MARKET, BASKET), a clear progression from purpose to parameters to outputs to usage timing. Every sentence adds a distinct piece of information, and the first sentence immediately states the core function. The density is justified by the tool's complexity and high-stakes financial context.

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 enumerate return values; it does so comprehensively (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers both modes, parameter defaults, and rationale for use versus siblings. For a complex financial tool with no output schema, this is complete.

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

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

The input schema already describes all 4 parameters (100% coverage), but the description goes further. It clarifies the distinct semantics of `size_usd` in single-market mode (spend vs target proceeds) versus basket mode (settlement notional per leg), explains the default side auto-selection in basket mode, and explicitly ties `market` to single-market and `event` to basket mode. This is far beyond baseline schema repetition.

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-noun purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than edge discovery, and it explains the two modes (single-market vs basket) with concrete examples.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names sibling tools and explains why (theoretical overround on thin books is not capturable, partial fills convert arb into directional risk), giving clear when-to-use and why-not-to-skip guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing behavioral traits: the two-mode dispatch, compatibility_warning conditions (matched_pairs:0 vs skipped_cross_type), temporal_alignment semantics, skipped_cross_type/subtype counters, and a real-world caveat about pre-mapped topics. 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 lengthy but structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence contributes necessary operational detail. The caveat at the end is essential for correct interpretation, so the length is justified.

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 shoulders the burden of explaining return values. It covers leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skipped_cross counters, plus failure modes. This is comprehensive for a complex cross-venue 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 already documents all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds mode semantics (pre-mapped shortcuts auto-fetch events, explicit params override the mapped side) and clarifies the macro-shortcut list, enriching the 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 opening line clearly defines the tool as a cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and bet-shape equivalence checking.

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 explains two usage modes (topic shortcuts vs explicit pairings) and provides critical caveats, such as 'pre-mapped ≠ tradeable' and when compatibility_warning fires. However, it does not explicitly name alternative tools for related tasks, only implying 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 already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds useful behavioral context: it randomly selects from the full archive and skips #404, which is not evident from annotations.

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

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

The description is a single sentence that front-loads the core action. It lists return fields which are partially redundant with the output schema, but the length is still reasonable and no word is wasted.

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 no-parameter tool with rich annotations and an output schema, the description is sufficiently complete. It covers what the tool does, its scope, and a notable behavioral exception (skips #404).

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?

There are zero parameters, and the schema coverage is 100%, so the baseline is 4. The description adds no parameter info, which is appropriate since there are none to explain.

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

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

The description clearly states the action (fetch) and resource (randomly selected XKCD comic from the full archive), with a specific scope (skips #404). This distinguishes it from likely siblings like get_comic and get_latest by emphasizing randomness.

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 usage for random comic retrieval and provides context (full archive, skips #404) but does not explicitly contrast with alternatives. No exclusions or when-not-to-use guidance is given, but the intent is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations, such as scoping to a user identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior of listing all keys when the key argument is omitted. This contextual information is not present in the annotations.

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

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

The description is concise and front-loaded with the primary action. Every sentence adds unique value: purpose, usage examples, scoping, and sibling relationships. There is no redundancy or unnecessary detail.

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

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

The tool has a single optional parameter and no output schema, and the description covers both execution modes (retrieve a value or list all keys). It also explains the data source (remember) and scoping, making the tool's behavior predictable. Minor omissions like error handling are not critical for this simple memory lookup.

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

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

The schema already provides a description for the 'key' parameter with 100% coverage, explaining that omitting it lists all keys. The description enriches this by giving examples of what keys might contain (target ticker, address, research notes) and why they are saved, adding 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 dual function: retrieving a previously saved value or listing all keys. It explicitly names companion tools 'remember' and 'forget', distinguishing it from siblings. Concrete examples of stored context make the purpose unmistakable.

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

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

The description explicitly tells agents when to use the tool: to look up context stored earlier without re-deriving it. It also advises pairing with 'remember' to save and 'forget' to delete, providing clear guidance on alternatives. The lack of an explicit 'when not to use' is minor given the clear use case.

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 that mark_read:true flags events as read, affecting future calls—a side-effecting behavior. This directly contradicts the readOnlyHint=true annotation, which implies no state mutation. The idempotentHint remains compatible, but the read-only hint is undermined, making this an annotation contradiction.

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

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

Three focused sentences, each earning its place: purpose and return format, filtering and read-state behavior, and alternative HTTP access. No redundancy, front-loaded with the core action, and perfectly sized for the tool's complexity.

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

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

The description covers the return payload shape, filter semantics, mark_read side effect, and alternative access method—essential for a tool with no output schema. It doesn't mention unread_only or limit defaults, but the schema already documents those, so the description is adequately complete for a read-oriented 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?

With 100% schema description coverage, the schema already documents all parameters. The description adds value by giving a concrete type example, clarifying that since takes an ISO timestamp, and explaining the consequence of mark_read (next call shows only newer events). This goes beyond the schema's basic parameter descriptions.

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

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

The description opens with a specific verb-resource pair ('Pull fired events from your subscription feed') and enumerates the return payload (source, citation_uri, raw event payload), making its purpose unmistakable. It distinguishes itself from siblings like list_subscriptions (which lists subscriptions) and recent_changes by focusing on fired events from the user's subscription feed.

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 practical usage context: filtering by type with a concrete example ('sec_8k') and since as an ISO timestamp, explaining mark_read's effect for incremental reads, and noting that polling works fine while pointing to an HTTP endpoint for scripts/dashboards. It lacks explicit comparisons to sibling tools but gives clear when-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, but the description goes far beyond them: it details fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO sunset soft-fail, and the structured return format with citation URIs. This is rich behavioral context not inferable from annotations.

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

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

The description is well-structured and front-loaded with examples, then explains mechanisms, parameter details, return shape, and the alternative tool. Every sentence provides useful information without redundancy or fluff.

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

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

With no output schema, the description adequately explains the return value (changes[] grouped by source, total_changes, citation URIs) and source fallbacks. It could optionally mention potential limitations like result caps or error handling, but the key aspects are covered. The distinction from entity_profile closes the loop.

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 description only restates the `since` parameter format already present in the schema (ISO date or relative shorthand). It does not add new semantic meaning for parameters; 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 begins with concrete example queries and states the core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also explicitly distinguishes from the sibling tool entity_profile, 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?

It provides clear when-to-use guidance via example queries and explicitly says 'Use entity_profile instead when you want the static profile.' Additionally, it explains fallback behavior (GDELT preferred, GNews when rate-limited) and source behavior (USPTO soft-fails), giving the agent context on when to rely on this tool.

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

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

The annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: storage as a key-value pair scoped by identifier, and persistence semantics (persistent for authenticated users, 24-hour retention for anonymous). This goes beyond the structured annotations and shows no contradiction.

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

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

The description is four sentences, each serving a distinct purpose: purpose, usage timing, storage/retention, and companion tools. No unnecessary words or repetition. Front-loaded with the primary action.

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 key-value store with no output schema, the description covers purpose, usage, persistence, and complementary operations. It also explains the scoped and TTL behavior, which is crucial for the agent. No gaps for the tool's complexity.

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

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

The input schema fully describes both parameters with 100% coverage, so baseline is 3. The description's reference to 'key-value pair' and examples of values aligns with the schema but adds no new parameter-specific semantics. The scoping detail is a behavioral trait, not parameter meaning.

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

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

The description clearly states a specific verb ('Save') and resource ('data the agent will need to reuse later'), and explicitly distinguishes itself from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.' Examples like 'a resolved ticker, a target address' further clarify its purpose.

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

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

It explicitly states when to use the tool: 'Use when you discover something worth carrying forward...' and provides concrete scenarios. It also names complementary tools (recall, forget), giving the agent guidance on alternatives. No explicit exclusions, but the guidance is 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?

Despite already having strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral context: identifiers are source-labelled, unresolved identifiers are explicitly listed under `unresolved`, LEI/FIGI enrichment degrades gracefully if external sources are unavailable, and the internal cascading lookup behavior is revealed. No contradiction with annotations.

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

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

The description is longer than average but every sentence earns its place: examples, supported types, identifier sources, graceful degradation, and efficiency gains. It is well-structured with clear sections and a front-loaded example-driven opening. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior), the description covers the essential aspects an agent needs: what it does, when to use it, what inputs are accepted, what outputs are produced, and how edge cases are handled. No output schema exists, but the description sufficiently explains return semantics.

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 fully, but the description goes far beyond by explaining what each type returns (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and accepted input formats (ticker, CIK, or name for company). It also clarifies the `unresolved` field semantics, adding meaning that the schema alone doesn't provide.

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

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

The description is highly specific: it resolves user-spoken names to canonical/official identifiers, with examples of queries ('What's the ticker for…'). It distinguishes itself from siblings by noting that other tools require these identifiers as input, and explicitly states 'Use FIRST whenever you have a name but need an ID.' Supported types and outputs are clearly enumerated.

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

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

The description provides clear usage context: 'Use FIRST whenever you have a name but need an ID.' It also mentions that each call replaces 2-3 manual lookups, implying this is an efficient entry point. It doesn't explicitly name alternatives, but the context is strong enough that an agent would know when to invoke it.

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

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

With strong annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: it probes via ai_visibility_check, ranks by score, and returns a structured list. It does not mention potential rate limits or that multiple network calls may be slow, but the annotation coverage lowers the burden.

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, all substantive: function, mechanism, and output. Front-loaded with the main purpose, no redundant filler.

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

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

Despite no output schema, the description specifies the return format ('ranked list with score, confidence, signal density'). Combined with comprehensive schema and annotations, the tool's behavior and constraints are fully documented for an agent to invoke it correctly.

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

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

Schema covers 100% of parameters with detailed descriptions, including the 2-8 entity constraint and the first-entity-as-subject rule. The description does not add new parameter semantics beyond the schema, 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 it from single-entity tools like ai_visibility_check. It also states the ranking and output, making the tool's function unmistakable.

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

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

The description explicitly provides a use case ('competitive AI-marketing audits') and a concrete prompting example. It implies this tool is for multi-entity comparison rather than single checks, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral details: it is a composite call that fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s with sources_failed listing timeouts. This goes beyond what annotations provide, making failure modes transparent.

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

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

The description is relatively long but every sentence serves a purpose: purpose, usage triggers, output details, ecosystem scope, and failure behavior are all packed in. It is front-loaded with the core value proposition and then expands into necessary operational details. Slightly dense but not wasteful.

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 (composite of two external services) and the absence of an output schema, the description does an excellent job of explaining the return values (summary block with specific fields, per-advisory detail, links, alternative versions) and edge cases (partial failures, latency, non-npm ecosystems). This makes the tool fully understandable without further documentation.

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

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

Schema description coverage is 100%, so both parameters (package, version) are already well-documented in the schema. The description adds no extra parameter-level detail beyond what the schema states, but it does elaborate on output semantics, which is relevant for understanding what the tool returns. Since schema carries the parameter burden, a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It lists specific output fields (license, advisories, bundle size, etc.) and differentiates from sibling tools like scan_competitor_ai_presence by focusing on package evaluation for npm projects.

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 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', effectively naming an alternative path 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification—context that goes well beyond the annotations.

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

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

The description is three dense sentences, front-loaded with the core purpose, followed by usage guidance, pairing, and technical constraints. Every sentence adds essential information without wasteful repetition, making it concise and well structured.

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

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

No output schema exists, but the description explains the return format (top-N passages with character offsets and similarity scores) and the truncation behavior. Given the tool's moderate complexity and strong annotations, this fully equips an agent to use it correctly.

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

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

Schema coverage is 100%, and each parameter already has detailed descriptions and examples. The tool description doesn't add significant parameter-level meaning beyond what the schema provides; it mentions returned passages with offsets and scores but not new parameter semantics. 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 states 'Semantic search INSIDE a fetched record' with a specific verb and resource, clearly distinguishing it from sibling tools. It explicitly mentions pairing with ask_pipeworx_grounded and emphasizes operating on already-fetched text, making its unique role 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?

It explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context and returns only relevant passages. It also names an alternative/pairing tool (ask_pipeworx_grounded), satisfying the guideline requirements.

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 important behaviors beyond annotations: requires OAuth account (anonymous/BYO cannot persist), phone verification for SMS, 10/day cap, webhook auto-disable after 10 failures, and the one-time return of webhook signing secret. This adds significant context not present in the annotations.

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

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

The description is dense yet well-structured, starting with the core action, then requirements, supported types, and delivery channels. It is somewhat long but every sentence contributes meaningful detail without fluff.

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

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

Given the tool's complexity (multiple subscription types and delivery options), the description covers requirements, examples, limitations (SMS cap, webhook auto-disable), and retrieval methods. It also mentions the return value, which is essential since there is no output schema.

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

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

The schema already provides detailed parameter descriptions with examples, so the baseline is 3. The description adds extra meaning by explaining item code semantics (e.g., items:['5.02'] = officer change) and clarifying SMS verification and webhook behavior, which are not fully captured in the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and enumerates supported subscription types.

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

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

It provides explicit context on when to use the tool, including required OAuth account, supported subscription types with examples, and delivery channel options. It mentions how to retrieve feed alerts via recent_alerts or a direct GET URL, but does not explicitly state when NOT to use 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 read-only/idempotent/non-destructive. The description adds behavioral context: it's the onboarding entry point, draws from a live catalog of thousands of tools, and returns example questions with tool+arg shape. 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 a single dense paragraph, but every sentence carries information. It front-loads the question patterns and compresses the return format, usage, and examples. Slightly long but not wasteful.

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 describing what the return contains (category-bucketed example questions with exact tool+argument shape). It covers purpose, usage, parameter behavior, and when to use. Entirely complete for this tool.

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

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

Schema covers 'topic' at 100%, but the description adds value with concrete examples ('finance', 'pharma', 'betting') and clarifies that omitting gives a cross-category spread. This goes beyond the schema's basic description.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and identifies it as the onboarding entry point. This specific verb+resource+behavior distinguishes it from siblings like discover_tools and 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and names alternatives (ask_pipeworx, entity_profile, compare_entities). This provides clear when-to-use guidance and context.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral context: ownership enforcement and the fact that the row is deactivated, not deleted, preserving historical events. This helps set expectations about 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?

The description is two sentences, with the primary action front-loaded. Every sentence adds value: the first states the operation, the second provides ownership and non-destructive behavior details. No filler or redundancy.

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

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

For a single-parameter mutation with no output schema, the description covers the key aspects: the operation, the ownership limitation, and the soft-delete effect. It could mention return behavior, but the simplicity of the tool makes the description sufficiently complete.

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

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

Schema coverage is 100% for the single 'id' parameter, which already specifies it's a subscription uuid. The description does not add new parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action and the use of an id.

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 usage for cancelling subscriptions but does not explicitly state when to use this tool over alternatives. It does provide a relevant constraint ('you can only cancel your own subscriptions'), but no direct comparison to other tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial behavioral context: the natural-language query patterns, the fast-path vs. grounded-pipeline routing, the exact verdict enum, the presence of pipeworx:// citations, and crucially the semantic distinction between could_not_verify (verification did not happen, with verification_error detail, never evidence) and unsupported (no source found). This goes far beyond the structured annotations.

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

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

The description is a single dense paragraph, but it is front-loaded with query patterns and usage context, and every sentence adds value—especially the caller-facing caveats about could_not_verify and unsupported. It is longer than strictly necessary, but complexity of the tool justifies the length; a bulleted verdict list would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: verdict values, actual value with citation, reasoning, verification_error details, and the unsupported vs. could_not_verify distinction. It also covers routing, tolerance semantics, and tool replacement value, making it complete for this 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?

Schema coverage is 100% for the two parameters, so the baseline is 3. The description adds meaningful semantics on top: examples for the claim parameter, and for tolerance_pct it explains override behavior, default derivation ('implied by wording, capped at 5'), and a concrete use case ('set 1–2 for hallucination detection'). This enriches the schema without fully compensating for the absence of an output schema, but it is strong.

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 the verb 'validate' and a list of natural-language query patterns ('fact check', 'verify the claim that…', 'true or false'), making it unmistakably a claim-verification tool. It further distinguishes itself from siblings by specifying the two routing paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for all else) and by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use: whenever the agent needs to check whether something a user said is factually correct. It also gives routing guidance for company-financial vs. other factual claims. However, it does not explicitly name alternative sibling tools or provide exclusion criteria (e.g., when to use ask_pipeworx_grounded instead), so it stops short of full alternative differentiation.

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