Postscript

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds: it passes the API key straight through to Anthropic (no storage), returns per-model {score, confidence, signals, raw_response} plus a combined view. No contradictions with annotations.

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

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

The description is a compact paragraph with key information front-loaded. Each sentence adds value: purpose, default behavior, API key cost implication, return structure, and use cases. Could be slightly more structured (e.g., bullet list of return fields) but overall efficient.

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

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

Given no output schema, the description compensates by listing return fields: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also explains the optional API key and default model. Missing details like rate limits or a list of all supported models, but sufficient for most use cases.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond the schema: e.g., 'Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic (BYO key — you pay Anthropic directly for those calls).' This clarifies the optional _apiKey parameter's cost implications.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility'. This distinguishes it from siblings like 'scan_competitor_ai_presence'.

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

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

The description provides context on when to use: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and optional API key for Anthropic, implying when to include that parameter. However, it does not explicitly mention when not to use or compare with specific sibling tools.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: it routes across thousands of tools, returns cited structured answers, and works on every tier with one fast call. It does not contradict annotations, though it omits details like error handling or rate limits.

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

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

The description is well-structured and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). It uses clear sections for examples and escalations, but it is somewhat long and includes redundant phrasing that could be tightened.

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

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

Given the absence of an output schema, the description compensates by explaining the return format (structured answer with pipeworx:// citations) and providing extensive context on scope, triggers, and alternatives. It does not fully specify response contents, but overall it is sufficiently complete for an agent to select and invoke the tool.

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

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

The schema documents the question parameter and all its aliases, achieving 100% coverage. The description does not add any parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: it routes factual questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

The description gives explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases and examples. It also states when NOT to use it by pointing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that candidate routing improvements are 'enabled live whenever one is under test,' that no candidate is currently active, and that it 'currently matches ask_pipeworx exactly.' It also clarifies 'Falls back to nothing — this IS a full working router,' which addresses potential concerns about reliability. This adds meaningful behavioral context without contradicting annotations.

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

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

The description is three sentences, with the main point front-loaded. It packs a lot of information efficiently without being overly verbose. The density is a slight negative, but every sentence earns its place by explaining the beta nature, current state, and usage guidance.

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

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

Given that there is no output schema, the description still communicates the response shape by referencing 'same response shape' as ask_pipeworx. It covers the tool's purpose, current state, experimental nature, and usage. For a routing tool with these annotations, this is complete enough for 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?

The schema covers all six parameters (question plus five aliases) with descriptions, so the baseline is 3. The description says 'same arguments' but does not add further semantic detail beyond what the schema already provides. It neither enhances nor reduces parameter understanding.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with 'identical universal router' and 'same 5,529 tools, same arguments, same response shape.' It explicitly distinguishes it from the stable ask_pipeworx by describing it as 'the experimental edge' and mentioning candidate routing improvements. This gives a specific verb+resource and differentiates from the sibling ask_pipeworx.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use directive. It also notes that results are compared against the stable router 'to decide what merges,' implying this is for testing new routing. It does not explicitly state when not to use it, but the context is sufficient for selection.

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

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

Annotations already mark it read-only, open-world, and idempotent; the description goes far beyond by detailing the exact return contract, refusal_reason enum, evidence behavior, and the extra LLM call cost. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: definition, mechanism, return/refusal contract, usage context, and cost comparison. It is front-loaded with the core value proposition and remains highly 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?

With no output schema, the description compensates by fully specifying the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal cases. Combined with annotations and parameter schema, the agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100% with alias descriptions, so the baseline is 3. The description adds no parameter-specific meaning beyond mentioning that the tool 'fills arguments' internally, which is not actionable; the schema already covers the single required question parameter and its aliases.

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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly contrasts with ask_pipeworx by explaining it 'EXTRACTS the answer using ONLY what the tool result contains,' making the tool's distinct role unmistakable.

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

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

The description provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and directly names the alternative for casual uses ('prefer ask_pipeworx for casual lookups') along with the cost trade-off. This fully equips the agent to choose correctly.

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 extensively documents behavioral traits beyond annotations, including market resolution, classification, fan-out logic, low-confidence handling, closed market detection, wide spread warnings, cancellation rule parsing, and safety mechanisms. No contradiction with annotations (readOnlyHint=true, non-destructive).

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

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

The description is verbose but well-structured with logical sections (classifiers, fan-out examples, response shapes, etc.). Every sentence adds value for such a complex tool. Minor deduction for length; still appropriate given the tool's sophistication.

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 thoroughly explains the response structure (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields) and covers edge cases (low confidence, closed markets, wide spreads, cancellation rules). Complete for agent decision-making.

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

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

Schema coverage is 100%, yet the description adds significant value by explaining the 'depth' parameter (quick vs. thorough with trade-offs), 'include_raw' (summarized vs. full payloads), and 'market' (three input formats with examples). This goes beyond the schema's descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with explicit input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on general research rather than specific calculations.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y') and includes many examples of when to use. It does not explicitly state when not to use or directly compare to alternatives among siblings, but the usage guidance is clear and practical.

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 provides extensive behavioral context beyond annotations: details on data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, etc.), handling of fiscal year variations, sorting by primary metric, and return format including citation URIs. No contradiction with annotations.

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

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

The description is somewhat long but front-loaded with example triggers. Every sentence adds value, though some repetition could be trimmed. Overall well-structured and clear.

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

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

Despite lacking an output schema, the description adequately explains what is returned (paired data, citation URIs) and the behavior for different entity types. It covers most of the information an agent would need to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the meaning of each type ('company' vs 'drug') and what data is fetched, which is not fully captured in the schema descriptions.

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

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

The description uses clear verbs like 'compare' and specifies the resource as '2–5 companies or drugs'. It provides example queries and explicitly states 'side-by-side comparison... in ONE parallel call', which distinguishes it from sibling tools like entity_profile.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. However, it does not explicitly list alternative tools or cases where this tool should not be used, which is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: account/payment requirements, parallel routing to 5,529 tools, gaps[] and contradictions[] fields, citation fetchability guarantees, semantic excerpting, and time expectations (15-90s). It does not contradict annotations and enriches what the agent knows about the tool's side effects and limitations.

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?

Every sentence earns its place: auth, alternative tools, core mechanism, depth semantics, news limitation, citation guarantee, hop fields, contradictions, excerpting, and timing. The description is long but densely packed with non-redundant, decision-relevant information, front-loaded with the critical account requirement and tool-selection guidance.

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

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

Given the tool's complexity (no output schema but rich return packet), the description covers all essential contextual aspects: what it returns (verbatim evidence, confidence, source, fetched_at, citation, gaps), when it's appropriate, limitations (not for open-web or current news), depth behaviors, and expected latency. There are no critical missing details.

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

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

Schema coverage is 100% for both parameters, but the description adds significant meaning beyond the schema: defines quick/standard/thorough in terms of facet count and hop behavior, explains 'broad/multi-part is fine', clarifies gap recovery and contradictions scans, and ties timeouts to depth levels. This goes well beyond the baseline 3 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources in ONE call' and explains it decomposes questions, routes to tools, and returns a findings packet. It explicitly distinguishes from siblings like ask_pipeworx ('If you are not signed in, use ask_pipeworx instead') and for current news ('prefer ask_pipeworx'). This goes beyond vague purpose and fully differentiates the tool.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and three distinct exclusion cases: not signed in → ask_pipeworx; single lookup → ask_pipeworx; breaking/current news → ask_pipeworx. It also explains depth-level usage with 'second-hop iteration' and 'gap recovery', making the agent's selection decision well-informed.

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. The description adds that results include names, descriptions, and full input schemas ready to call, and that it returns top-N relevant tools. 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 slightly long but well-structured: purpose first, then usage guidance, then domain list, then return details. Every sentence adds value.

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

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

No output schema exists, but the description explains the return format (tool names, descriptions, schemas). It covers the key aspects needed for an agent to use the tool effectively.

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 already describes parameters. The description mentions the query parameter accepts natural language descriptions and aliases, but adds minimal new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb and resource, and lists concrete domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific actions.

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

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

Explicit guidance is provided: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies when not to (when a specific tool is already known).

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds important behavioral context: patents section soft-fails due to USPTO API sunset in May 2025, and the tool makes a parallel call. This complements the annotations without contradiction.

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

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

The description is front-loaded with example queries and purpose. It is somewhat lengthy but well-structured, with each part serving a purpose. Could be slightly trimmed (e.g., detailed return list), but overall effective.

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 100% schema coverage, annotations present, and no output schema, the description provides a thorough overview of what the tool returns (cik, filings, fundamentals, patents, news, LEI) and its limitations. It covers all necessary context for 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%, so baseline is 3. The description adds meaning by explaining that value can be ticker or CIK, providing examples ('AAPL', '0000320193'), and clarifying that names are not supported. This enhances parameter understanding beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It lists specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It also distinguishes from sibling tools like compare_entities and resolve_entity by noting that names are not supported.

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 advises: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use (if only have a name, use resolve_entity first) and provides example queries that trigger the 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?

Description aligns with annotations (destructiveHint=true). Adds context about usage but does not contradict annotations. Some side effects not mentioned but acceptable given 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?

Two concise sentences: first states action, second provides usage guidance. No unnecessary words.

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

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

Complete for a 1-parameter destructive tool with full schema coverage and usage guidelines.

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 parameter 'key'. Description adds minimal extra 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 it deletes a memory by key, and distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task completion, clearing sensitive data. Also mentions pairing with remember and recall.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it fetches, extracts, and emits markdown, plus the output format. No contradictions, and it provides useful behavioral context beyond annotations.

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

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

Three sentences with front-loaded main purpose. Every sentence adds value: what it does, how it works, and when to use it. No waste.

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

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

Covers input, process, and output format ('single text blob'). No output schema, so the description compensates with output details. Lacks error handling or performance notes, but adequate for a simple read-only 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 the description closely mirrors the schema for both parameters (url and max_links). It adds 'Full URL' and 'or a specific landing page' for url, but no significant extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states it generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts, emits). It clearly distinguishes from sibling tools like 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 lists explicit use cases (client indexing, own project drafting, competitor auditing). It lacks negative guidance (when not to use) and alternatives, but the provided contexts are clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by specifying that it returns only active subscriptions by default, which is a behavioral detail beyond annotations. It also lists the fields returned, aiding in understanding the response.

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

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

Two concise sentences with no wasted words. The first sentence states the primary action and output, the second provides usage guidance. Structure is front-loaded and efficient.

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

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

Given the tool's simplicity, the description covers its purpose, usage, return values, and default behavior. No output schema exists, but the fields are described. The description is complete for an AI agent to understand 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?

Schema coverage is 100% with a clear description for the single optional parameter 'include_inactive'. The description does not elaborate on the parameter beyond the schema, but it implicitly sets context by mentioning 'active subscriptions'. At baseline 3, no significant added value.

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

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

The description clearly states the verb 'List' and the resource 'active subscriptions', specifying the caller's scope. It lists the returned fields, making the purpose unambiguous. Additionally, it distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

Provides explicit guidance on when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly helps the agent decide between this tool and alternatives like 'subscribe' or 'unsubscribe'.

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 low-value annotations (all false), the description discloses substantial behavioral context: filing without an account returns a claim_token for later status checks, the token can be passed back to read resolution, rate-limited to 5 per identifier per day, free, and the team reads digests daily. No annotation contradiction exists; annotations agree that this is not read-only or idempotent.

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

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

The description is dense but every sentence earns its place: purpose, usage criteria, exclusions, token flow, rate limits, and cost are all covered without redundancy. It is front-loaded with the core action and then expands into necessary operational details.

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

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

This tool has no output schema, but the description fully compensates: it explains the return token, how to use it, the feedback categories, the required specificity for the message, and operational constraints. For an agent deciding whether and how to invoke this tool, the description provides complete contextual coverage.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains the claim_token workflow (filing vs. checking), instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and clarifies the 'other' type. These additions justify one point above baseline.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It defines four distinct feedback categories (bug, feature, data_gap, praise) and differentiates from sibling tools by explicitly scoping to tools served by this Pipeworx connection.

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

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

The description gives explicit when-to-use guidance ('Use when a tool returns wrong/stale data (bug)...'), when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'), and provides a disambiguation heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary usage guidance.

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

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

Annotations already declare read-only and idempotent behavior. The description adds extra context: derived from CF analytics-engine, no PII, caching between 5min-1h, self-aggregating signal. 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 concise with three main sentences and a bullet list of use cases. No unnecessary words, front-loaded with purpose.

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

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

Despite no output schema, the description explains the return type (top tools, packs, call volume) and additional context (no PII, caching). Sufficient for a simple 1-parameter 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 a clear enum and description. The description adds value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, enhancing parameter understanding.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, with a specific verb and resource. It distinguishes itself from siblings by focusing on trending data.

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

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

Explicit use cases are provided (discovering hot data sources, confirming canonical tools, alignment checking) and window choice guidance is given. However, it does not explicitly state when not to use the 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint true. The description adds critical behavioral traits: it uses live CLOB depth for fill checks, imposes a Jaccard similarity threshold (0.30) for cross-event pairs, filters placeholder partitions, and warns when realizable edge is non-positive. This provides substantial context beyond annotations.

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

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

The description is overly long and dense, lacking clear structure like bullet points or sections. It contains detailed implementation notes (e.g., Jaccard threshold, placeholder filter, fill check) that could be summarized or formatted more efficiently. A more concise front-loaded summary would improve usability.

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 complexity (2 optional params, no output schema), the description compensates well by detailing the response structure (opportunities[], partition_check) and fill check behavior. It covers semantic anchor, partition filter, and usage modes. It could be improved by explicitly stating the return type and edge cases like no opportunities found.

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 has 100% coverage with descriptions for both parameters. The tool description adds significant meaning beyond the schema: for 'event' it explains that it walks child markets and performs date-axis/threshold-axis checks and partition_check; for 'topic' it explains cross-event scanning and similarity filtering. This enhances understanding.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) and specifies the resource (Polymarket). This is specific and differentiated from sibling tools like polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: no args for trending scan, 'event' for a specific market (with example slugs), and 'topic' for cross-event scanning (with seed question examples). It also mentions alternative tool 'polymarket_fill_risk' for custom sizing. However, it does not explicitly exclude other scenarios or contrast with sibling tools like polymarket_edges.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description goes far beyond by detailing the three model families, edge calculation (net of slippage, Kelly caps), caching behavior (1h KV-level keyed on knobs), diagnostic output, and the 24h-move warning. 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 comprehensive but somewhat lengthy. It is well-structured with clear sections (segments, diagnostics, knobs) and front-loads the purpose. While every sentence adds information, minor redundancy (e.g., repeating 'default' values) could be trimmed.

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 complexity (9 parameters, no output schema), the description fully compensates by describing the response shape (by_segment, diagnostics, opportunity fields), caching, and the categorical filters. It leaves no major gaps about input/output behavior.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the rationale behind each parameter (e.g., slippage_pp: 'zero fees but bid/ask depth eats 20-50bp'), linking parameters to segments (min_partition_leg_kelly for partition arbs), and grouping them as 'tradeable-edge knobs'. This enriches understanding beyond the schema.

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

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

The description clearly states the tool 'scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price'. It explicitly targets 'what should I bet on today', distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx disagreement signal.

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

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

The description provides strong contextual guidance: it is built for daily edge discovery without paging hundreds of markets. It explains the three segments and when each is relevant (e.g., structural arbitrage for mutually-exclusive events). It does not explicitly list alternatives, but the sibling tool names imply other specialized tools (e.g., fill risk).

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: data sourced from daily snapshots with 60-day TTL, decay computed from daily closes of edge_pp_net (slippage-adjusted), not intraday. It details response structure (tracked, expired, snapshot_dates) and limitations (snapshots only on cache-miss). This goes well beyond annotations.

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

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

The description is fairly long but well-structured: purpose first, then arg info, then response fields, then limitations. It is front-loaded with the key question it answers. Every sentence adds value, though a slight reduction in verbosity could be beneficial.

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 thoroughly explains the return value fields (tracked, expired, snapshot_dates, including subfields like trend, decay_pp_per_day, lifespan_days). It covers limitations and parameter meanings. For a complex tool, this is complete.

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

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

Schema coverage is 100%, with both parameters (days, window) well-described in the schema. The description reinforces defaults (14 days, 1wk) and provides context (lookback clamp 2-30, snapshot family). This adds marginal value beyond the schema, warranting a baseline 3.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on analysis over time rather than raw snapshots.

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 explains when to use the tool (for evaluating edge longevity and decay) and implies alternatives (e.g., polymarket_edges for raw data). However, it does not explicitly state when not to use it or mention all alternatives, though the context 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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context about being a read-only check, not executing trades, and explains return fields and risks (thin legs, forced directional risk). No contradiction with annotations.

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

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

The description is somewhat lengthy but every sentence adds value. It front-loads the main purpose and then details modes and return fields. Could be slightly more structured, but it is well-organized with clear sections (SINGLE-MARKET, BASKET).

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 modes, many return fields), the description provides complete context: when to use, what parameters mean, what outputs to expect, and risks. Schema coverage is 100% and annotations are present, but the description adds enough to make it self-contained.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning beyond schema: explains the difference between single-market and basket modes for market/event parameters, default side logic for basket, and interpretation of size_usd (spend vs target proceeds vs settlement notional).

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 does a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verb 'check' and resource 'edge'. It distinguishes between single-market and basket modes, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by its focus on fill risk.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use guidance. It also explains why (theoretical overround not capturable, partial fills create directional risk) and offers alternatives implicitly.

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?

Description discloses return fields (raw probabilities, matched spreads, compatibility_warning, temporal_alignment, skip counters) beyond annotations. Explains behavior for non-matching cases (e.g., skipped_cross_type) and temporal alignment. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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

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

Well-structured with sections for modes, response, safety fields. Every sentence adds value, though slightly verbose. Could tighten some phrases without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. Covers return fields, safety warnings, temporal alignment, and edge cases like mismatched bet shapes. Provides sufficient context for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%. Description adds meaning by explaining the interaction between topic and explicit parameters (override logic), and enumerates the 10 pre-mapped topics. This supplements the schema's property descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers) and differentiates from sibling tools by focusing on cross-venue comparison.

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

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

Provides explicit guidance on when to use (finding real spreads) and when not to (when bet shapes are non-equivalent). Warns that most pre-mapped topics are not tradeable, managing expectations effectively.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about returned fields (text, status, configuration), which is helpful given no output schema, but does not disclose additional behavioral traits beyond what annotations cover.

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

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

Single, focused sentence that front-loads the action and resource, with no wasted words. Every part of the description adds value.

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

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

Given no output schema, the description specifies return fields (text, status, configuration). For a simple read operation with good annotations, this is largely complete, though missing mention of potential error cases (e.g., nonexistent keyword).

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 descriptions for both parameters are clear and sufficient (e.g., '_apiKey: Postscript Private API token (Bearer).', 'keyword_id: Postscript keyword ID.'). The tool description does not add further parameter-level meaning, so baseline 3 applies.

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

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

The description explicitly states the action ('Get'), the resource ('a single SMS keyword by its ID'), and the return fields ('keyword text, status, and configuration'). It clearly distinguishes from sibling tools like postscript_list_keywords.

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 retrieving details of a specific keyword but does not provide when-not-to-use guidance or mention alternative tools like postscript_list_keywords for listing multiple keywords.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by listing the specific fields returned (phone, email, status, etc.), which is not in the annotations. No contradictions found.

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

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

The description is a single, efficient sentence that immediately states the purpose and what is returned. Every word earns its place; no filler or redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema, good annotations), the description covers the core functionality and return values. Could optionally mention error behavior for invalid IDs, but not essential for a straightforward read operation.

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

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

Schema coverage is 100%, so the schema already fully describes both parameters (_apiKey and subscriber_id). The description does not add any additional parameter semantics beyond that. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get') and resource ('single SMS subscriber by Postscript subscriber ID'), and explicitly lists the returned fields (phone number, email, etc.). This distinguishes it from sibling tools like postscript_list_subscribers (which lists multiple) and postscript_get_keyword (which gets a keyword).

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 does not provide guidance on when to use this tool versus alternatives (e.g., postscript_list_subscribers), nor does it specify when not to use it or any prerequisites. The context signals show siblings but no explicit usage direction.

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, destructiveHint=false. Description adds meaningful context: explains what keywords are and what the tool returns (IDs, text, subscription settings). No contradictions. Missing potential information about pagination or limits.

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

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

Extremely concise and efficient: 27 words in two sentences. First sentence states action, second explains keywords and return value. No filler or redundancy.

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

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

Given rich annotations and simple parameter, the description covers the tool's purpose and output. Could mention if pagination exists or if the list is exhaustive, but overall sufficient for a listing tool.

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

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

Schema coverage is 100% and the schema description already clarifies the _apiKey parameter. The tool description adds no additional meaning or context beyond what is in the input schema.

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

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

Description clearly states the action (List) and resource (active SMS keywords for the shop), explains what keywords are, and specifies the return data (keyword IDs, text, settings). It distinguishes from sibling tools like postscript_get_keyword by implying a list vs singular retrieval.

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?

No explicit guidance on when to use this tool versus alternatives like postscript_get_keyword. The description implies it's for listing all active keywords, but does not exclude single keyword retrieval or provide usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds the pagination return format, which is useful context, but does not disclose rate limits or authentication details beyond schema.

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

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

Two sentences with zero waste. The first sentence states the core purpose and supported filters; the second explains pagination mechanics. Every word earns its place.

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

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

For a tool with 11 parameters and no output schema, the description covers resource, filtering, sorting, and pagination adequately. It lacks error handling or edge-case details but is sufficient for common use.

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

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

Schema coverage is 100%, so parameters are well-described. The description adds meaning by explaining page-based pagination and sort pattern (e.g., 'created_at__desc'), which complements the schema without redundancy.

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

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

The description clearly states 'List SMS subscribers for a Postscript (Shopify) shop,' specifying the verb and resource. It distinguishes from siblings like postscript_get_subscriber (single retrieval) and postscript_list_keywords (different resource).

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 explains filtering, sorting, and pagination usage ('pass page to walk results'). It implies when to use (listing vs single retrieval) but does not explicitly exclude alternatives or provide when-not scenarios.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by clarifying the scoping ('Scoped to your identifier'), the two modes (retrieve key vs list all), and the pairing with related tools. 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 two sentences, front-loaded with the primary action, and every sentence adds value. No wasted words.

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

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

For a read-only retrieval tool with one optional parameter and no output schema, the description fully covers purpose, usage, scope, and relationship to sibling tools. It is sufficient for the agent to understand and invoke correctly.

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

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

Schema coverage is 100% and the schema description already states 'omit to list all keys'. The description adds minimal new meaning beyond the schema, merely restating the behavior and adding usage context, which does not significantly enhance parameter understanding.

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

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

The description uses a specific verb ('Retrieve' or 'list'), identifies the resource ('value previously saved via remember' or 'all saved keys'), and clearly distinguishes from sibling tools like 'remember' and 'forget' by naming them. It also provides concrete use case examples ('target ticker, address, research notes').

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

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

The description states when to use the tool ('to look up context the agent stored earlier') and pairs it with 'remember' and 'forget' for context. However, it does not explicitly state when not to use it nor compare directly to siblings beyond naming.

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

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

The description adds significant behavioral context beyond annotations: explains return fields (source, citation_uri, raw payload), mark_read side effect for tracking read status, and the alternative access method. No contradiction with annotations (readOnlyHint=true is consistent with a read operation that may mark items read).

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 four-sentence paragraph, front-loaded with the core purpose. Each sentence adds essential information: purpose, return fields, filtering, and mark_read/alternative access. No unnecessary words.

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

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

The description is complete for a read-only list tool with optional parameters. It explains return fields, filtering, mark_read behavior, and polling. No output schema exists, but the description adequately covers what the agent needs to know.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples (e.g., filter by type 'sec_8k') and explaining the behavioral impact of mark_read on subsequent calls, which enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the resource (alerts from subscription feed) and the action (pull/return), distinguishing it from sibling tools like ask_pipeworx which are Q&A oriented.

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: filtering by type and since, polling behavior, and an alternative REST endpoint for scripts/dashboards. However, it does not explicitly exclude this tool in favor of specific siblings 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?

Description details parallel fan-out to SEC EDGAR, GDELT→GNews fallback (with conditions), and USPTO soft-fail. Annotations already indicate readOnlyHint and idempotentHint, so description adds additional behavioral context beyond annotations.

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

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

Description is long but well-structured with front-loaded examples and logical flow. However, some redundancy could be trimmed (e.g., repeating 'parallel call').

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 complexity (multiple sources, fallbacks, soft-fails), description provides sufficient detail on return structure and limitations. No output schema, but description adequately covers return format.

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

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

Schema coverage is 100%, so parameters are fully documented. Description does not add significant meaning beyond schema, but baseline is 3.

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

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

Description clearly defines the tool as a change feed for companies over a recent window, listing specific data sources and providing example queries. It explicitly distinguishes from sibling tool entity_profile, which provides static profiles.

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

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

Description provides clear context on when to use (e.g., 'latest on Y') and points to entity_profile as an alternative for static profiles. However, it doesn't explicitly state exclusions or when not to use 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?

Adds details beyond annotations: memory is key-value scoped by identifier, persistence differences (authenticated vs anonymous). No contradictions with annotations. Could mention whether overwriting is allowed but implied by idempotentHint.

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

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

Four sentences, no fluff. Purpose front-loaded, followed by usage guidance, behavioral details, and pairing. Every sentence adds value.

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

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

For a simple tool with 2 parameters and no output schema, the description covers all important aspects: purpose, when-to-use, storage semantics, scope, retention, and related tools. Complete enough.

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

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

Schema already describes both parameters with 100% coverage and clear examples. Description adds little beyond stating 'key-value pair' and examples, which are already in the schema. Baseline score.

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: 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes itself from siblings recall and forget by specifying the action and pairing context.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, providing clear usage context and alternatives.

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

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

Beyond the readOnly and idempotent annotations, the description discloses graceful degradation of LEI/FIGI enrichment, explicit `unresolved` reporting, source attribution for each identifier, and internal cascading of multiple lookup endpoints. This significantly enriches behavioral understanding.

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 detailed but well-structured, with front-loaded examples and a clear purpose statement. The SUPPORTED TYPES section is necessary for two entity kinds, making the length appropriate, though slightly verbose.

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 explaining what identifiers are returned for each type, how unresolved identifiers are handled, and how degradation works. It fully covers input, output, failure modes, and performance expectations.

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

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

Schema coverage is 100% and already includes examples. The description adds per-type return semantics (company vs drug) and clarifies accepted input formats, slightly exceeding the schema's baseline.

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

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

The description opens with concrete user phrasings and states the exact function: resolving a user-spoken name to canonical/official identifiers. It explicitly differentiates from siblings by saying 'Use FIRST whenever you have a name but need 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?

Clear when-to-use guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also mentions it replaces 2-3 manual lookups. No explicit when-not-to-use or alternative names are provided, but the context is unambiguous.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized. No contradictions; all disclosed behaviors are consistent 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 concise (three sentences), front-loaded with purpose, and includes all necessary information without extraneous details. Every sentence adds value.

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

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

Despite no output schema, the description explains return values (ranked list with score, confidence, signal density). It covers entity range (2-8) in schema, mentions probing mechanism, and gives examples. For a tool of moderate complexity with rich annotations and 100% schema coverage, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value beyond schema: it explains that the first entity is treated as the 'subject' for narrative, and clarifies the context parameter's role in disambiguating common names. 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 clearly states the verb 'compare' and resource 'AI visibility across multiple entities', specifying that it probes each entity with ai_visibility_check and returns a ranked list. This differentiates it from siblings like ai_visibility_check (single entity) and compare_entities (likely more general).

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 an explicit use case ('competitive AI-marketing audits') and mentions it is useful for comparing multiple entities. However, it does not explicitly state when not to use it (e.g., for single entity analysis) or contrast with sibling tools like compare_entities, which could lead to confusion.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds key behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This goes beyond annotations.

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

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

The description is well-structured and front-loaded with the core purpose. However, it is somewhat lengthy despite being informative. Every sentence adds value, but slight trimming could improve conciseness.

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

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

Despite no output schema, the description enumerates all return fields (summary block, advisories, links, alternative versions) and explains partial failure behavior. Combined with annotations, this is fully complete for an agent to understand what to expect.

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 description adds useful details: scoped packages are accepted, version defaults to latest. This enriches the schema's documentation.

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

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

The description clearly states it is a composite check for npm packages, fanning out across deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying it's NPM-only, which differentiates from other scanning tools.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and clarifies that other ecosystems fall under a different tool. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already show readOnlyHint=true, idempotentHint=true, etc. Description adds significant detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output includes offsets for verification. 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?

Front-loaded with the core purpose, then explains usage context, technical details, and pairing. Every sentence adds value, though the paragraph could be broken into two for easier scanning. Efficient but not perfectly concise.

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

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

No output schema, but description fully explains return values (top-N passages with offsets and scores), embedding model, windowing strategy, character cap and truncation behavior. Also explains integration with ask_pipeworx_grounded. Covers all needed context for a semantic search tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the text max length and provides query examples, but adds little beyond the schema descriptions. It meets the baseline but doesn't significantly exceed it.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record' with specific examples like SEC 10-K. It uses a strong verb-resource combination and distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on internal search within already-fetched text.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and 'saves context, returns only the passages that matter'. Mentions pairing with ask_pipeworx_grounded, though it doesn't explicitly state when not to use or list alternatives beyond that.

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

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

The description adds significant behavioral context beyond annotations: OAuth requirement, type-specific param structures, delivery channel details, and rate limits. However, the idempotentHint=true annotation contradicts the description's implication that each call creates a new unique subscription (returns new ID), creating an inconsistency. Annotations already cover read/destructive safety, so transparency is adequate but marred by 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 well-structured with front-loaded purpose, then prerequisites, type details, and delivery options. It uses bullets and examples effectively. It is somewhat lengthy but each sentence earns its place given the complexity. Minor redundancy could be trimmed (e.g., repeated SMS cap in both description and parameter description), but overall efficient.

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

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

Given the tool's complexity (3 parameters, nested objects, 5 enum types, multiple delivery channels with behavioral details) and the absence of an output schema, the description is remarkably complete. It explains the return value (subscription ID), prerequisites, type-specific filters, delivery methods with limitations, and even error recovery (auto-disable for webhook). No critical gaps are apparent.

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% description coverage, and the tool description goes far beyond the schema by providing concrete examples for each subscription type (e.g., items:["5.02"] for sec_8k), complete delivery channel options with format requirements and constraints, and clear guidance on required versus optional fields. This adds substantial meaning for an agent.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It uses a specific verb ('Create') and resource ('subscription'), and the presence of sibling tools like 'list_subscriptions' and 'unsubscribe' helps distinguish it from related actions.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account, exclusion of anonymous/BYO), lists supported subscription types with examples, details delivery channels with operational constraints (e.g., 10/day SMS cap, webhook auto-disable), and implies when to use compared to siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: returns dynamic content drawn from a live catalog, and specifies output structure (category-bucketed with tool+argument shapes). This goes beyond annotations 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 verbose with multiple examples and a parenthetical list of categories, but every sentence earns its place. Front-loaded with example queries. Could be slightly tighter, but the richness aids an AI agent's understanding.

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

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

Given the tool has only one optional parameter, no output schema, and read-only/idempotent annotations, the description is highly complete. It covers purpose, usage, parameter details, output format, and relationship to other tools (meta-tools). No gaps.

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

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

Schema coverage is 100% (has description for the single optional parameter 'topic'). The description adds further meaning by listing the exact focus areas (finance, pharma, etc.) and clarifying that omitting the parameter yields a cross-category spread. This adds significant 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 states the tool is an onboarding entry point for an agent that just connected, listing synonyms ('what can I ask Pipeworx', 'getting started') and describing the output (category-bucketed example questions with exact tool+argument shape). It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its role as the first use to learn what Pipeworx can do.

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

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

Explicitly 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'. Also guides when to use the topic parameter for focus vs. omitting for full spread. No explicit 'when not to use', but the positive guidance is clear and covers the main use cases.

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

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

Beyond annotations (which indicate idempotent, non-destructive write), the description adds key context: ownership enforcement and soft-deactivation behavior ('deactivated not deleted'). No contradiction with annotations.

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

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

Three concise sentences with front-loaded action. Every sentence adds essential information 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?

Given one required param and no output schema, the description fully covers usage context, behavioral constraints, and data implications. No gaps.

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

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

The schema already describes the single parameter 'id' with full coverage. The description's mention of 'by id' adds little value. Baseline 3 is appropriate.

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

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

The description clearly states the action ('cancel a subscription by id') and the resource ('subscription'), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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?

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), providing context for when to use. However, it lacks explicit guidance on when not to use or direct mention of 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the two processing paths, the exact verdict values returned, and the critical semantics of 'could_not_verify' (i.e., the check did not happen, carries verification_error, and must not be interpreted as evidence). This is exactly the kind of behavioral nuance an agent needs to correctly interpret results and avoid misleading users.

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

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

The description is compact but information-dense. Every sentence serves a purpose: trigger language, when to use, pipeline logic, return values, special verdict cautions, and a note on efficiency. It is well-structured with a clear flow from purpose to usage to output semantics, and avoids redundancy with the annotations or schema.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains what the tool does, when to use it, how it behaves (two paths), what it returns (verdicts, citations, reasoning), and how to interpret edge cases (could_not_verify vs unsupported). An agent would be well-equipped to invoke this tool and correctly interpret its results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-specific detail beyond what the schema already provides. It gives useful examples for the 'claim' parameter and explains tolerance implications indirectly through verdict definitions, but it does not elaborate on tolerance_pct outside of the schema. The schema carries the primary burden here.

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 rich set of natural-language trigger phrases and clearly states the tool performs claim verification against authoritative sources. It explicitly differentiates itself from a generic search/lookup tool by describing the two distinct verification pipelines (SEC EDGAR/XBRL for company-financial claims, and a grounded pipeline for all other factual claims) and by noting it replaces 4–6 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?

The description gives a clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing behavior for different claim types. However, it does not explicitly mention when not to use this tool or name specific alternative tools (e.g., deep_research, ask_pipeworx_grounded) that might be more appropriate for open-ended research rather than discrete fact-checking.

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