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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds important behavioral context beyond that: it routes to sub-tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. This gives the agent a realistic expectation of how the tool behaves and what its output looks like.

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

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

The description is front-loaded with the most important instruction, but it is longer than needed and repeats the same preference-over-web-search message multiple times. The final fragment 'Also, for [??]' is incomplete and provides no usable guidance, which is a structural defect.

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 single required parameter, rich annotations, and no output schema, the description covers the essential bases: what the tool does, when to use it, what sources it uses, and what kind of output to expect. The main gap is not explaining how to choose among sibling tools like deep_research or ask_pipeworx_grounded, but the 'START HERE' guidance mitigates that.

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

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

The schema already documents the single semantic parameter 'question' and all aliases with 100% coverage. The description adds useful example questions and trigger phrasing, but it does not add meaningful parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly explains that this tool routes a natural-language question to one of many verified source tools and returns a structured answer with stable citation URIs. It differentiates itself from web search, but it does not explicitly distinguish itself from sibling Pipeworx variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual/authoritative data, use trigger phrases like 'what is', 'look up', 'find', and 'current', and use web search instead for questions requiring current real-world awareness. It even says 'START HERE for most questions' and 'When in doubt, start here', making routing decisions 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that this is an experimental edge with no fallback, that candidates are enabled live only when under test, and that no candidate is currently active (last retired 2026-07-26), so behavior currently matches ask_pipeworx exactly. This gives the agent an accurate safety and freshness picture.

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

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

The description is front-loaded with the core 'beta/identical router' statement and keeps the experimental status, current candidate state, and no-fallback caveat in tight, purposeful sentences. Minor redundancy exists between 'identical' and 'currently matches ask_pipeworx exactly', but every sentence contributes useful information.

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

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

Given the single required question parameter, rich annotations, and a clear pointer that the response shape matches ask_pipeworx, the description provides enough context for invocation. The absence of an output schema is mitigated by the 'same response shape as ask_pipeworx' statement, though the actual response format is not spelled out.

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

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

The schema already documents all six parameters at 100% coverage. The description adds only that the arguments are identical to ask_pipeworx, which is useful context but does not add new meaning beyond the input schema's alias definitions.

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 is a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape, differentiated from the stable tool by candidate routing improvements. This is a specific, meaningful purpose that clearly distinguishes it from its sibling ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly names the alternative (ask_pipeworx) and provides the condition: use this when you want the newest routing, with results compared against the stable router. It lacks an explicit when-not-to-use statement, but the 'newest routing' condition and 'stable router' comparison make the intended use 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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the full success return contract ({answer, evidence, confidence, source, fetched_at}), the five explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the 'uses ONLY what the tool result contains' extraction constraint, and the extra LLM call cost. No contradiction with annotations — the readOnlyHint is consistent with a read-and-answer operation.

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?

Purpose is front-loaded in the first sentence, and the flow is logical: purpose, mechanism, return contract, refusal behavior, use cases, cost tradeoff. Every sentence carries information, but the '5,798 across 1517 sources' detail and the full refusal enum make it denser than strictly necessary for routing decisions.

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

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

Since there is no output schema, the description correctly carries the full burden of documenting return values, and it does so exhaustively for both the success and refusal paths. Combined with the usage guidance and cost note, nothing an agent needs to select or invoke this tool correctly is missing.

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

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

Schema description coverage is 100%: the schema fully documents the single 'question' parameter and all five aliases (query, q, prompt, text, input). The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' naming a specific mode (grounded answering), an explicit verb (extracts the answer), and the routing resource (5,798 tools across 1517 sources). It also distinguishes itself from its closest sibling, ask_pipeworx, by the grounded-extraction behavior and refusal mechanism, so an agent can tell them apart without opening schemas.

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?

Gives explicit when-to-use guidance — 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples (financial verdicts, legal claims, medical lookups) — and explicit when-not-to-use guidance: 'prefer ask_pipeworx for casual lookups.' The alternative is named and the selecting condition 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?

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 readOnly/openWorld/idempotent, and the description adds substantial context beyond them: account/paid-plan requirements, parallel decomposition across 5,798 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), the gaps[] honesty guarantee ('never invented'), contradictions[] on standard/thorough, semantic excerpting rather than head-truncation, and latency expectations (15-60s, up to ~90s for thorough). No contradiction with annotations.

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

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

The description is long (~280 words) but densely packed with distinct value: critical routing info (account required, alternative tool) is front-loaded, followed by scope, behavior, return format, and latency. Minor deduction for re-explaining depth semantics that the input schema already covers in its enum descriptions — some redundancy, though defensible given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does thoroughly: findings packet fields, gaps[], contradictions[], hop field, citation_uri resolvability, and excerpting behavior. It also covers prerequisites (account/tier), the not-signed-in fallback, latency, and error semantics (gaps for unanswered facets). Little an agent needs to invoke or evaluate results is missing.

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

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

Schema coverage is 100% and the schema's depth enum is already well-documented (hop counts, gap-recovery, contradictions scan). The description adds value beyond the schema by tying depth to cost ('thorough' needs a paid plan), explaining hop mechanics in prose ('re-angles unanswered gaps', 'chases the best leads'), and framing the latency difference per depth. Slightly redundant with the schema, hence not a 5.

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

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

The description states a specific verb (decomposes, routes, returns) and resource ('1517 STRUCTURED data sources' across SEC, FRED/BLS, FDA, USPTO, etc.), and explicitly differentiates from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx.' Concrete examples ('compare X and Y's regulatory + financial exposure') further pin down what the tool is for.

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 ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'), and a named alternative with a concrete condition ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). Even the depth choice is tied to use case (multi-step questions resolve in one call with standard/thorough).

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?

With annotations already marking readOnly/openWorld/idempotent, the description adds meaningful behavioral context: it fans out across multiple sources, reports sources_used/sources_failed, treats empty sections as real no-data, resolves names via SEC EDGAR, and soft-fails when USPTO API is sunset. 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 dense and long, but the key directive and examples are front-loaded before the source/return enumeration. It is not as crisp as it could be—one very long run-on sentence carries most of the detail—yet every clause adds operational information, so it earns its length.

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

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

There is no output schema, so the description carries the full burden of explaining return values; it does so by listing each result section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and explaining sources_used/sources_failed. For a multi-source tool, this is complete enough to call 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 the schema already documents both parameters. The description adds value by explaining that type accepts 'company' or 'ticker' interchangeably, that value can be a ticker, zero-padded CIK, or name, and that names resolve via SEC EDGAR's match—beyond the bare schema definitions.

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 then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company) and enumerates the sources and returned sections, making the tool's purpose unmistakable and clearly distinct from narrow single-source lookups.

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

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

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and it clarifies edge cases (private companies return resolved:false, FDA section can be empty, patents soft-fail). This is concrete when-to-use guidance with expected behavior under different inputs.

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?

The annotations already mark the tool read-only, open-world, idempotent, and non-destructive, and the description goes far beyond them. It discloses compatibility warnings, per-entry flags, skipped unclassified legs, gross vs net spreads, and the Kalshi fee caveat. There is no contradiction with the annotations; the open-world framing matches the 'pre-mapped ≠ tradeable' warning.

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

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

The description is long, but it earns its length because there is no output schema to document the response. It is front-loaded with the core purpose, then organizes detailed caveats under clear headers like SAFETY FIELDS and response descriptions, making the density navigable rather than rambling.

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 of cross-venue matching and the absence of an output schema, the description is unusually complete. It explains response fields, compatibility codes, temporal alignment semantics, skipped counter categories, fee handling, and the meaning of unverified pairings. An agent has enough information to call the tool correctly and interpret its warnings.

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

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

The input schema already covers all 3 parameters at 100%, so the baseline is met. The description adds genuine value by explaining the two operating modes, enumerating the exact topic shortcuts, and clarifying that both modes run the same token-overlap matcher with the same safety disclosures. This goes beyond the schema but is not quite exhaustive on parameter syntax and edge-case behavior.

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

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

The opening sentence names the exact function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly establishes the comparison being made and distinguishes this tool from single-venue or other polymarket-focused siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description clearly explains when to use the tool and how to choose between the `topic` mode and the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode. It also gives strong practical guidance that pre-mapped topics are not automatically tradeable. However, it never explicitly names alternative sibling tools or states when another tool should be preferred, stopping just short of a 5.

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

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

Annotations 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 annotations, the description discloses meaningful behavior: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via `figi_candidates`, explicit `unresolved` fields rather than omission, per-identifier source labeling, and internal cascading lookups. Nothing in the description contradicts the read-only, idempotent, non-destructive 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 front-loaded with examples and a clear directive, and every included detail serves the tool's complexity. It loses a point because of the long parenthetical chains and some repeated identifier-source detail that could be tightened or bulleted.

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

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

For a tool with no output schema, the description is remarkably complete: it documents input forms, return fields (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), ambiguity behavior, unresolved-ID behavior, supported sources, and failure mode. An agent has sufficient context to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description substantially exceeds it by adding accepted formats (ticker, CIK, ISIN, brand/generic name), the exact instruction to pass only the entity name for bonds, and a warning against including the full noun phrase. It also explains what each `type` returns, making the parameters fully actionable.

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 an explicit mission: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It supports exactly two entity types (company and drug), lists the identifiers returned, and the "Use FIRST whenever you have a name but need an ID" line clearly distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description provides an explicit trigger condition: "Use FIRST whenever you have a name but need an ID," along with multiple example phrasings. It does not name alternative tools explicitly or state when not to use it, but the role in the workflow is made 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 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.