Corporate Apology

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: default model (Workers AI Llama-3.3-70b free), Anthropic BYO-key with direct payment, and the per-model return structure. 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 three sentences, front-loaded with the primary purpose, followed by operational details (default/cost) and return format. Every sentence adds value with no filler, making it concise and well-structured.

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

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

Given there is no output schema, the description compensates by specifying return fields: {score, confidence, signals, raw_response} + a combined view. It covers use cases and key behavior. Missing details like error handling or rate limits, but for a read-only tool with strong annotations, it is reasonably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that omitting models uses the free default, and that _apiKey is passed through to Anthropic with the user paying directly. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool's action: 'Probe one or more LLMs for what they know about a business / brand / product / topic' and score visibility 0-100 per model. It uses a specific verb ('probe') and resource ('LLMs'), and the unique output (visibility score) distinguishes it from siblings like ask_pipeworx or entity_profile, though it does not explicitly name alternatives.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear when-to-use context, but it does not explicitly state when not to use this tool or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by explaining the routing behavior, the citation URIs, and the 'one fast call' performance expectation. It doesn't disclose potential failure modes or rate limits, but it goes beyond annotations with concrete behavioral details.

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 front-loaded with the key directive and logically organized (use cases → examples → alternatives). Every section serves a purpose, though the list of domains is somewhat exhaustive. It earns a 4 for being dense and well-structured without being needlessly verbose.

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

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

Given the tool's complexity (router over thousands of sources), the description covers its function, output format, citation behavior, relationship to siblings, and even notes that it works on every tier. There's no output schema, but the description adequately describes the return value. This is a complete picture for an agent.

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

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

Schema description coverage is 100% with aliases, and the description adds meaningful examples and a semantic scope ('what is', 'look up', 'current') that clarifies what should be passed as the question parameter. This is above the baseline 3 because it offers concrete guidance on parameter content.

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: to answer factual questions by routing them to one of 5,529 tools across 1,455 verified sources and returning structured answers with citations. It uses a specific verb (routes/returns) and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides example query types. It also states when to step up to alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part fan-out), making the usage boundaries clear.

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

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

The description discloses that this is an experimental beta with live candidate routing improvements, currently matching ask_pipeworx exactly due to no active candidate, and that it is a full working router with no fallback. These details go well beyond the readOnlyHint and idempotentHint annotations, providing valuable operational context.

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

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

The description is four sentences long, with each sentence delivering a distinct piece of information: definition, current state, usage guidance, and functional assurance. It is well-structured and front-loaded, with 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?

The description, combined with a schema that fully documents parameters and annotations that cover safety and side effects, gives a complete picture: what it does, when to use it, its experimental nature, and its current status. Referencing ask_pipeworx for response shape is sufficient since that sibling tool is available to the agent.

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

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

The input schema provides 100% coverage with all six parameters described, including alias explanations for 'question'. The description adds no further parameter semantics beyond the redundant 'same arguments' reference, 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 identifies this as a beta version of ask_pipeworx, a universal router with 5,529 tools and identical arguments/response shape. It distinguishes itself from the stable ask_pipeworx sibling by explicitly labeling it as the experimental edge.

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 to use it like ask_pipeworx when wanting the newest routing and notes that results are compared against the stable router. It names the alternative (ask_pipeworx) but does not explicitly state scenarios where one should avoid the beta version, so clear context without full exclusion.

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

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

The description richly discloses behavior beyond annotations: it extracts answers 'using ONLY what the tool result contains,' returns evidence as a verbatim quote, and defines five specific refusal reasons. Annotations (readOnlyHint, openWorldHint) already cover safety, but the description adds grounding guarantees, cost implications, and error semantics. There is no contradiction with annotations.

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

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

The description is long but every sentence carries functional value: purpose, mechanism, return shape, refusal modes, usage, and cost comparison. The specific numbers (5,529 tools, 1455 sources) are slightly extraneous but add context. It is front-loaded with the core purpose and remains structured, though a touch denser than necessary.

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

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

With no output schema, the description fully specifies the return structure for both success and refusal cases, including all refusal_reason values. It also explains the routing mechanism, high-stakes applicability, and extra LLM call cost. Given the tool's complexity, the description is remarkably complete.

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

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

Schema description coverage is 100% (all parameters like 'question' and its aliases are described in the schema). The description does not add new parameter-level semantics beyond the schema's 'natural language' note. Per the rubric, a baseline of 3 applies when schema covers the parameters fully, and the description provides no further enrichment.

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

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

The description opens with a clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly names the resource (ask_pipeworx) and differentiates from the sibling 'ask_pipeworx' by describing the grounded extraction mechanism. This is more than a vague verb+resource; it provides a precise scope and method.

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 whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' due to cost. This directly addresses when to use this tool vs its sibling.

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

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

Even with annotations declaring read-only/non-destructive/idempotent, the description adds extensive behavioral detail: resolver confidence levels, alternative match suggestions, parent-event extraction, news fallback flags, low-confidence short-circuit behavior, wide-spread illiquidity notices, and cancellation-rule risk. It far exceeds what annotations alone convey and contradicts nothing.

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

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

The description is extremely long and dense, organized into CAPS-labeled sections that aid scanning but contain far more detail than typical for a tool description. It is front-loaded with purpose and usage, but many implementation specifics (e.g., cancellation rule parsing, news retry fields) could live in supporting docs or an output schema. Every section earns its place, but overall it is not 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?

There is no output schema, yet the description covers response shapes (market, analysis, evidence), the resolver contract, parent-event extraction, news field fallbacks, safety short-circuiting, and cancellation-rule risk. This is a complex tool with high behavioral surface area, and the description leaves almost no critical operating detail undocumented.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete input examples (slug, URL, question text), classifier values, and fan-out examples that help agents choose the right market input. It doesn't add much beyond the schema for depth/include_raw, but the practical guidance and accepted-form clarification push it 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 specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It adds concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and enumerates classifiers and fan-out examples, making its scope distinct from sibling Polymarket 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 gives explicit when-to-use scenarios and shows blocking behavior for low-confidence/closed markets. It does not explicitly name sibling alternatives or state when not to use this tool, but the use-case list plus the resolver contract provides clear contextual 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 indicate read-only, idempotent, non-destructive. The description adds specific behavioral details: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs in the response. No contradiction.

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

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

The description is dense with information and front-loaded with trigger phrases. Every sentence adds value, though the length and heavy use of uppercase might be slightly overwhelming; a bit more structure could improve readability.

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 adequately describes return format (paired data + citation URIs), sorting behavior, and data source coverage. It also handles edge cases like off-calendar fiscal years, making the tool's behavior fully predictable.

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

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

Schema covers parameters, but description goes further by specifying what metrics are pulled for each type: company (10-K revenue, net income, cash, long-term debt) and drug (FAERS counts, approval counts, trial counts). Also clarifies array limits and examples.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and includes user-phrase examples. It clearly distinguishes from sequential lookups and sibling tools like entity_profile by focusing on multi-entity comparison.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists concrete trigger phrases, giving the agent clear conditions for when to invoke 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable context by specifying that it 'returns ready-to-use apology text', clarifying that no real-world action is taken. It also discloses that sincerity controls tone, which is not obvious from annotations. This goes beyond what annotations provide, justifying a 4.

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

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

The description is concise at two sentences, immediately states the core action and output, and avoids redundant phrases. Every word contributes to understanding the tool's purpose and key parameter.

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 5 parameters, 1 required, and an output schema, the description covers the core purpose and sincerity control but omits the role of medium, audience, and company. Since these parameters affect the apology (e.g., audience might change tone), the description is not fully complete. Annotations and output schema help, but there is a noticeable gap.

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

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

With only 40% schema description coverage, the description must compensate. It explicitly explains the sincerity parameter ('performative', 'genuine', 'defensive') and its role in controlling tone, adding meaning beyond the enum values. However, medium, audience, and company are not explained, and their enums/descriptions in the schema are minimal, so the description does not fully compensate for the low coverage.

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

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

The description clearly states the tool's function: generating corporate apology statements for a specific offense. It also specifies the key input (sincerity level) and the output (ready-to-use apology text), making the purpose unambiguous. This is distinct from all sibling tools, which focus on research or data 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?

The description implies usage: use this when you need an apology statement and want to control its tone via sincerity. However, it does not explicitly provide when-not-to-use guidance or mention alternatives. The examples in the schema partially fill this gap, but the description itself lacks explicit exclusion criteria.

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 substantial behavioral context beyond the annotations: account requirements, latency expectations (15-60s, up to ~90s), non-open-web nature, gap recovery behavior across depth levels, contradictions[] scan, hop fields, fetchable citation_uri, and semantic excerpting. This is far richer than the readOnly/idempotent hints.

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 front-loaded with the most critical info (account requirement and alternative). Every sentence earns its place, covering use cases, exclusions, timing, and output structure. Slight verbosity exists but is justified by the tool's complexity. Not maximally concise, but structured effectively.

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

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

Given the tool's complexity, no output schema, and only two parameters, the description thoroughly covers return format (findings packet with evidence, confidence, source, gaps), depth behavior, citation_uri resolvability, excerpting strategy, and performance expectations. The agent can fully understand invocation and output interpretation.

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 describes both parameters. The description adds practical nuance: depth:'thorough' requires a paid plan, depth:'standard' adds gap-recovery hop, and depth:'quick' implies faster single-hop. This exceeds the baseline 3 by providing operational implications not in the schema.

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

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

The description states a specific action and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It clearly distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups. Examples of use cases further solidify purpose.

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

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

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also mentions account/plan prerequisites and when deeper depth levels are needed, giving clear alternatives.

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

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

Annotations already declare readOnly and idempotent. The description adds valuable behavior: returns top-N relevant tools with names, descriptions, full schemas, and curated examples, and notes results are 'ready to call directly, no second schema lookup needed.' This enriches the agent's expectation of the output 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 front-loaded with purpose and includes useful operational guidance (return format, direct callability, call-first advice). The domain list is a bit long but serves as a concrete scope indicator. No redundant filler.

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

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

Despite no output schema, the description fully explains the return value (tools with names, descriptions, schemas, examples) and how to use them. The parameter aliases are covered by schema, and the tool's discovery/selection role is clear. Complete for its purpose.

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 all aliases are documented with descriptions and examples. The description itself doesn't add new parameter semantics beyond restating the natural-language query concept, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by being the meta-search/discovery tool, listing supported domains and emphasizing it returns tools with schemas ready to call.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also enumerates covered domains, giving clear context for applicability.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive. The description adds specific behaviors: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; details return structure; notes USPTO PatentsView API sunset and soft-fail; GDELT→GNews fallback. 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 dense but organized with semicolons and a clear list of return fields. It may be long, but each clause adds needed operational detail (e.g., specific CIK format, filing URI scheme, sort order).

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

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

With no output schema, the description compensates by listing every return field: CIK, company_name, recent_filings URIs, fundamentals fields, patents status, news fallback, LEI. It also covers parameter constraints and edge cases, making it self-sufficient.

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

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

Schema already documents type and value with 100% coverage. Description reinforces with concrete examples (AAPL, 0000320193) and adds constraint that names are unsupported, which aligns with schema's value description.

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

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

The description opens with user-phrase examples and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (entity profile) and distinguishes it from single-pack lookups, plus references resolve_entity for name inputs.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a when-not: 'names not supported (use resolve_entity first).' This gives clear guidance on alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's mention of 'Delete' is consistent but adds little beyond annotations. The description adds the context of clearing sensitive data and pairing with other tools, but does not disclose additional behavior such as what happens if the key is missing.

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

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

The description is three sentences, front-loaded with the action. Every sentence contributes value: purpose, usage, and related tools. There is no fluff or repetition.

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

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

For a simple one-parameter deletion tool with no output schema, the description covers purpose, usage, and pairing. The presence of annotations (destructive, idempotent) fills the safety profile. Minor gap: no mention of return value or error behavior, but that is less critical for this tool.

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

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

Schema description coverage is 100%: the 'key' parameter is described as 'Memory key to delete'. The description does not add extra parameter details beyond the schema, but it does reinforce the meaning by saying 'by key' and providing an example in the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It explicitly distinguishes from sibling tools like remember and recall by indicating deletion as the action, and provides context about clearing sensitive 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?

The description gives explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but does not explicitly state when not to use it or name an alternative tool for retrieval.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and notes the output is a 'single text blob ready to drop at site-root/llms.txt'. This gives useful behavioral context without contradicting any annotations.

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

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

Three sentences with zero filler: the first states the core purpose, the second explains the process, and the third lists use cases. The most important information is front-loaded, making it easy for an agent to quickly determine relevance.

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 params, no output schema), the description is complete. It explains the return format ('single text blob ready to drop at site-root/llms.txt') and the overall behavior. The annotations cover safety aspects, so nothing major 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?

The schema already provides 100% parameter descriptions, so the baseline is 3. The description reinforces the 'url' parameter with 'for any URL' but does not add details about 'max_links' or default values beyond what the schema documents. No extra semantic value is provided.

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 generates a production-ready llms.txt file for any URL, with explicit reference to AI crawlers and the standard markdown format. It distinguishes itself from sibling tools by focusing on the specific llms.txt generation task rather than broader AI visibility checks or research.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') giving clear context for when to use the tool. However, it does not explicitly mention alternatives or exclusions, though the 'competitor audit' use case hints at overlap with sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds valuable context by specifying the caller scope and detailing the exact response fields, which is especially important given there is no output schema. 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 two sentences, immediately stating the purpose, then the return value, then the use case. Every sentence earns its place with no redundancy or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It covers the operation, the caller scope, the returned fields, and a practical use case, providing sufficient context for an agent to invoke it correctly.

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

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

The input schema already provides 100% coverage for the single optional parameter include_inactive, with a clear description. The tool description does not add extra semantics beyond the schema, which is adequate but not exceptional.

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 lists the caller's active subscriptions, using the specific verb 'List' with a precise resource and scope. It also enumerates the returned fields, making the tool's function unambiguous and distinct from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly says to use this tool to review current monitoring before adding more subscriptions or to find an id to cancel. It gives clear usage context, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations provide no positive hints (all false), so the description carries the full burden. It discloses the claim_token return-and-follow-up workflow, rate limiting ('5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and processing expectations ('team reads digests daily'). This is rich behavioral context beyond what annotations convey.

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

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

Though longer than typical descriptions, every sentence earns its place: purpose, usage categories, exclusion, identification heuristic, content guideline, claim_token workflow, processing expectation, rate limit, and quota note. It is dense, front-loaded with purpose, and contains no redundant or filler text for a tool with this complexity.

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

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

The description is complete given the tool's complexity: it covers the full lifecycle (submitting feedback, receiving a claim_token, later checking resolution), constraints (rate limit, quota), and proper scope. No output schema exists, but the description compensates by explaining the claim_token return and its use. The nested context object is adequately covered by the schema.

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

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

Schema coverage is 100%, so parameters are already well described. The description adds extra semantic value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by stipulating message content ('don't paste the end-user's prompt'). These details go beyond the schema descriptions, though the schema already carries the core meaning.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies this as a feedback channel for the Pipeworx tool connection, distinguishing it from sibling tools like 'ask_pipeworx' or 'deep_research' by enumerating exact feedback categories (bug, feature/data_gap, praise).

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

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

Provides explicit when-to-use guidance: uses cases for bug, feature/data_gap, and praise. It also gives an exclusion rule: 'ONLY for tools served by this Pipeworx connection' and instructs to file with another MCP server if the tool is not Pipeworx. It even offers a disambiguation heuristic ('Not sure? Pipeworx tool names are the ones this connection lists.'), which is excellent for an AI agent.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context: it's self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h, which helps the agent understand staleness. 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 well-organized and front-loaded with the core purpose, followed by structured use cases and caveats. Every sentence adds value, and the format is easy to scan.

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

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

Despite having no output schema, the description explains what the tool returns (top tools, top packs, total call volume) and the data shape (pack, tool, count). It also covers caching and data source, making it complete for a simple one-param 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?

The schema already describes the single window parameter with enum values and guidance on short vs long windows (100% coverage). The description reiterates the window options but doesn't add new semantic detail beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's function: showing what other AI agents are calling on Pipeworx, returning top tools, top packs, and call volume over a window. This distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregated trending usage.

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 three explicit use cases for when to use the tool, such as discovering hot data sources and confirming canonical choices. However, it doesn't mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

The description extensively discloses internal logic and edge cases beyond the annotations: the semantic anchor (Jaccard similarity), placeholder filtering, partition_check sum deviations, and the fill-check behavior against live CLOB depth. It explains when signals should be ignored (realizable_edge_pp ≤ 0) and clarifies the response structure. This goes well beyond the read-only and idempotent hints, and does not contradict the annotations.

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

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

The description is dense and long, but every sentence provides operational detail or a caveat. It is front-loaded with the main purpose and then methodically covers modes, filters, and response format. It could be tightened with formatting (e.g., bullets) but is not wasteful 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?

Given the tool's multi-mode complexity and lack of an output schema, the description is remarkably complete. It defines all three invocation patterns, explains the response fields (opportunities, partition_check, fill_check), includes trading guidance, and names the sibling for custom sizing. No critical context appears 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?

While the schema describes both parameters, the description adds substantial meaning: it provides example values, explains the difference between event and topic modes, and details how each mode processes data. It even names the fill-check tool for sizing, enriching the parameter semantics beyond the schema's 100% coverage.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) and gives concrete examples, making the purpose unmistakable and differentiating it from siblings like polymarket_fill_risk 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?

Explicit guidance is provided for when to use each mode: 'event (recommended for a specific market)', 'topic (for cross-event scanning)', and 'Call with NO args for a trending_scan.' It also directs users to polymarket_fill_risk for custom sizing, clearly stating an alternative tool. Additionally, it warns against trading when fill check shows realizable_edge_pp ≤ 0, offering practical usage caveats.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces this with 'Cached 1h' and non-destructive scanning language. It adds rich behavioral detail: response top-level structure, diagnostics for empty segments, the Fed exclusion reasoning, and a 24h-move warning. 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 excessively long, containing deep model-family formulas (e.g., per-sport α values, gate thresholds from 'Run 8') that are unlikely to change invocation behavior. It is front-loaded with the core purpose, but the extensive jargon and repetitive enumeration of output keys make it hard to scan. A tighter version would retain the key behaviors.

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 the return structure (by_segment, fed_candidates, _diagnostics) and the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), so callers know what to expect. It also covers caching, filter behavior, and edge cases (empty segments) comprehensively. Given the tool's complexity (9 knobs, 3 segments), the description 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?

With 100% schema description coverage, baseline is 3; the prose goes beyond by explaining cross-parameter semantics, e.g., why min_kelly doesn't filter partition opportunities and how min_liquidity/max_spread_pp act as tradeable-edge filters. It also clarifies slippage_pp's subtraction from raw edge and the per-leg Kelly logic, adding 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 opens with a specific verb+resource ('Scan top Polymarket markets') and states the goal ('return opportunities where Pipeworx data disagrees with market price'). It clearly differentiates from siblings by describing the three model family segments and the 'without paging hundreds of markets' use case.

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 targets the 'what should I bet on today' use case, making it clear this is for opportunity discovery. It gives filtering knobs (min_liquidity, max_spread_pp) but does not contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so there's no exclusion 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral details: the 60-day snapshot TTL, gaps in snapshot_dates, the use of daily closes (not intraday), and the signed nature of edge_pp_net. This enriches the agent's understanding of data freshness and interpretation significantly.

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

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

The description is long but every sentence carries meaningful information. It is well-structured with clear labels (Args, RESPONSE, LIMITS), front-loaded with the core query, and avoids fluff. The detail is justified given the tool's complexity and lack of an output 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?

Despite no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), including field meanings and limitations. It covers history depth, data gaps, and computational basis, making it self-sufficient for an agent to understand expected 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%, providing baseline 3. The description adds value by explaining 'days' as a lookback and 'window' as a snapshot family, and by linking window to the polymarket_edges context. It clarifies semantics beyond the schema's structural 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 clearly states what the tool does: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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 context for when to use the tool, e.g., comparing a fresh wide edge vs. a 3-week-old wide edge, and explains the relationship to polymarket_edges snapshots. It does not explicitly name alternative tools or state when not to use it, but the purpose is clear enough to infer appropriate usage.

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 goes far beyond the annotations (readOnly, non-destructive, idempotent) by detailing the internal behavior: 'walks the ladder', returns specific metrics like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and explains risk scenarios such as partial basket fills converting an arb into an unhedged directional position. It also names output features like thin_legs and forced_directional_risk. No contradictions with annotations.

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

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

The description is a dense, long paragraph but each sentence earns its place. It is organized by mode (single-market vs basket) and lists concrete outputs. While not impeccably concise, the length is justified by the tool's complexity and the absence of an output schema; restructuring into bullets would improve scanability but is not a major flaw.

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

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

This is a highly complex tool with two modes and no output schema, so the description must carry the burden of explaining return values and edge cases. It does so thoroughly: enumerates outputs for both modes, explains settlement notional, identifies thin_legs and forced_directional_risk, and warns about partial fill risks. Given the schema/annotations provide limited context, this description is exceptionally 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%, but the description adds essential context beyond the schema's field descriptions. It explains the dual interpretation of size_usd (max spend vs target proceeds for single-market; settlement notional for basket), clarifies the difference between market slug and event slug, and details the side parameter's defaults and behavior in both modes. This enriches the schema meaning significantly.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly positions itself as a pre-trade check for polymarket_arbitrage and polymarket_edges tools, setting it apart from siblings.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies the two modes (market vs event) and when each is appropriate, including the default behavior for basket mode. No alternatives are left ambiguous.

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?

Given strong annotations (readOnlyHint=true, idempotentHint=true), the description adds significant behavioral context: it explains compatibility warnings, temporal alignment, and skipped cross-type counters. This is far beyond the annotations and helps the agent understand edge cases and failure modes.

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 densely informative, with clear sections for modes, response, and safety fields. It front-loads the core purpose and uses uppercase labels for key concepts. Some redundancy exists (repeats the warning about pre-mapped topics), but overall structure is strong.

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

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

Without an output schema, the description compensates by detailing the response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers both usage modes, safety conditions, and how to interpret results, making it highly complete for a 3-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%, but the description enriches parameters by listing the exact topic shortcuts and explaining how kalshi_event_ticker/polymarket_event_slug override the mapped sides. It also clarifies the response structure, which helps infer parameter usage.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifically identifying the resource (cross-venue spread) and scope. It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on comparing the same event across two venues.

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 describes two usage modes (topic shortcuts and explicit ticker/slug), and provides guidance on when the tool is reliable vs not (e.g., compatibility_warning, temporal_alignment). While it doesn't name alternatives, it implies usage context well and cautions that pre-mapped topics often aren't tradeable.

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 readOnly, idempotent, and non-destructive behavior. The description adds extra behavioral context beyond that: scoping to 'anonymous IP, BYO key hash, or account ID' and the listing behavior when key is omitted. This goes beyond the structured fields, though it doesn't cover edge cases like missing keys.

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

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

The description is three sentences long, front-loaded with the primary action. Every sentence earns its place: definition of behavior, usage context, and relationship to siblings. There is no redundant or filler content.

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 low complexity (one optional parameter, no output schema), the description covers everything needed: what it retrieves, how to list, scoping, and how it fits with remember/forget. It is complete for an agent to invoke correctly without further assumptions.

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 'key' parameter, so baseline is 3. The description adds value by providing concrete examples of keys ('user's target ticker, an address, prior research notes') and explicitly linking parameter omission to listing all keys. This enriches the parameter's meaning beyond the schema's short description.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb and names the resource (saved values/keys), and explicitly contrasts itself with siblings remember and forget, leaving no ambiguity about its role.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also differentiates from alternatives by saying 'Pair with remember to save, forget to delete,' giving 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 declare readOnlyHint=true, but the description explicitly states that setting mark_read:true flags events as read and makes the next call show only newer ones. This is a clear state-changing behavior, directly contradicting the read-only annotation. This is an annotation contradiction, forcing a score of 1 despite otherwise transparent disclosures.

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, front-loaded paragraph. It begins with the main purpose, then covers filtering, mark_read behavior, polling, and an alternative access method. It is slightly longer than necessary but each sentence provides useful information without major fluff.

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

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

For a read-oriented tool with five optional parameters and no output schema, the description covers what is returned (source, citation_uri, payload), filtering options, mark_read state effects, and even an HTTP mirror. It omits some edge details like limit specifics, but those are covered in the schema. The main gap is that the mark_read side effect is not reconciled with the readOnlyHint annotation.

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 all parameters are documented. The description adds extra value by giving a concrete filter example ('sec_8k'), explaining the effect of mark_read, and referencing ISO timestamps for since. This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed,' and specifies what each event carries (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts with read-state tracking.

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 concrete usage context: filters by type and/or since, mark_read for stateful polling, and notes that polling works fine. It also names an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly mention when not to use this tool versus sibling tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, but the description adds substantial context beyond these: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView API sunset, and returns structured changes grouped by source with citation URIs. It also mentions 'ONE parallel call' and the exact failure mode for GNews, which is valuable operational knowledge.

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

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

The description is dense but efficient, packing multiple pieces of essential information into one paragraph. It opens with user-intent phrases to aid pattern matching, then covers sources, parameters, output, and the alternative tool. No filler or redundant content is present, though the length may be slightly high for a simple tool; it earns a 4 rather than 5.

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

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

The tool is complex (multiple data sources, fallbacks, date parsing, no output schema), and the description covers all necessary operational details: source list, fallback conditions, date format support, return structure (changes[], total_changes, citation URIs), and limitations (USPTO soft-fail). This is sufficient for an agent to select and invoke the tool correctly without guessing.

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

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

Although schema covers all three parameters, the description enriches them: 'since' accepts ISO or relative shorthand with examples ('7d', '30d', '3m', '1y'), 'value' accepts ticker or zero-padded CIK with concrete examples, and 'type' only supports 'company'. This exceeds the schema by providing format examples and recommended usage, reducing ambiguity for the 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?

Description uses specific verbs: 'change feed for a company in the last N days/weeks/months' and provides concrete user intents ('What's new with X', 'updates on Acme'). It explicitly distinguishes from sibling entity_profile by stating when to use that instead, so it is not confused with similar 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?

Description gives clear when-to-use criteria via example queries and typical monitoring window ('Use "30d" or "1m" for typical monitoring'). It also names the alternative tool (entity_profile) and states when it is preferred ('when you want the static profile regardless of window'). Fallback behavior for data sources is described, helping the agent decide when this tool is appropriate.

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

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

The description adds valuable behavioral context beyond annotations: memory is stored as key-value pairs scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain memory for 24 hours. This goes well beyond what readOnlyHint/idempotentHint provide and does not contradict any annotation.

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 that are front-loaded with purpose, then usage scenarios, then persistence details. No redundant words or fluff; every sentence 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 simple two-parameter tool with no output schema, the description is complete: it covers what to store, when to use it, storage scoping, persistence behavior, and companion tools. No important operational detail 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?

The schema already documents both parameters with examples and descriptions at 100% coverage. The description's examples (resolved ticker, target address) align with schema examples but add no new syntax or format details, 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 opens with 'Save data the agent will need to reuse later', which clearly states the action (save) and resource (data to reuse). It distinguishes the tool from siblings like recall and forget by specifying cross-conversation/session persistence and providing concrete examples (ticker, address, preference).

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

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

It explicitly says 'Use when you discover something worth carrying forward' and lists example scenarios. The final sentence names complementary tools ('Pair with recall to retrieve later, forget to delete'), giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds substantial context: graceful degradation of LEI/FIGI enrichment, explicit disclosure of unresolved identifiers, labeling of source provenance, and internal cascading across endpoints. This goes well beyond the annotation baseline.

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

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

The description is lengthy but densely packed with valuable details like supported entity types, resolution behavior, and graceful degradation. It is front-loaded with natural-language examples that aid comprehension, though it could be trimmed slightly without losing core information.

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

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

Despite lacking an output schema, the description thoroughly explains expected outputs, edge cases (unresolved identifiers), unavailable-source behavior, and internal cascading. This is comprehensive for a lookup tool with only two parameters and strong annotations.

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

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

Input schema covers 100% of parameters with clear descriptions and examples. The description reinforces these with inline examples like 'AAPL' and '0000320193' but does not add significant new semantic detail beyond the schema's own parameter descriptions.

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

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

The description clearly states it resolves user-spoken names to canonical/official identifiers required by other tools, with specific verbs like 'resolve', 'look up', and 'find'. It distinguishes itself from siblings like entity_profile and compare_entities by framing it as the first-step lookup tool.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID', providing clear usage context. It doesn't explicitly list when not to use it or name alternatives, but the instruction strongly implies the workflow.

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

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

While annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints, the description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and enriches the agent's understanding.

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

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

The description is three sentences, front-loaded with the core purpose, then a behavioral explanation, then a use case and return format. Every sentence contributes information without redundancy, making it highly concise and scannable.

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

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

Given the tool's complexity (multiple entities, optional models and API key, no output schema), the description covers the main behavioral aspects and return fields. It leaves minor gaps like the exact meaning of 'signal density' or score scale, but these are secondary and do not hinder correct selection or invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by explaining that the first entry in 'entities' is treated as the subject and the rest as competitors, and that 'context' is a shared disambiguation string applied to every probe. This extra context justifies a score above baseline.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from the sibling ai_visibility_check by stating it probes each entity with that tool and ranks the results, making its multi-entity comparison scope explicit.

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

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

It provides a concrete use case for competitive AI-marketing audits and an illustrative question ('does Claude know about us as well as our competitors?'), giving clear context. However, it does not explicitly name alternatives or state when not to use this tool in favor of ai_visibility_check or compare_entities.

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 (readOnly, idempotent), the description discloses partial failure behavior, the 5-30s first-measurement latency, and the sources_failed field. No contradiction with annotations; it adds valuable operational context.

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

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

The description is a single dense paragraph but every sentence contributes critical use-case, output field, or limitation information. It is appropriately sized for the tool's complexity, though a bit of structuring could improve scanability.

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 enumerates the exact summary fields, per-advisory details, links, alternative versions, and failure behavior. It covers both the composite nature and edge cases, making it complete for the tool's scope.

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

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

Schema coverage is 100%, and the schema already describes both parameters (package name and version default). The description does not add additional parameter-level meaning beyond the schema, so it receives the 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 is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It identifies the specific verb (scan), resource (dependency), and expected outputs, distinguishing it from unrelated sibling tools.

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

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

It explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and provides an exclusion: NPM only, with PyPI/Maven/etc. falling under deps.dev:version directly. This gives clear when-to-use and alternative guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals how results are returned (top-N passages with character offsets and similarity scores), the technical approach (BGE-base-en embeddings + cosine over 500-char overlapping windows), and the input cap (200K chars, truncated and flagged). This is substantial behavioral disclosure that the annotations do not convey.

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

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

The description is exactly three sentences, front-loaded with the primary purpose. Each sentence adds distinct information: definition, use case/benefit, and technical details. There is no redundant or filler wording; every phrase 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?

With no output schema, the description covers the return type (passages with offsets and scores), the input constraints (max chars and truncation behavior), and the integration with a sibling tool. It provides enough context for an agent to decide when and how to invoke the tool without additional documentation.

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

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

Schema coverage is 100% and each parameter has a description. The tool description adds value by offering concrete examples for 'query' ('supply-chain risk', 'fiscal year 2024 revenue'), clarifying that 'text' is a previously fetched document (e.g., SEC 10-K body), and noting the char cap. This goes beyond the schema's basic descriptions, though the schema already carries the core constraints.

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

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

The description clearly defines the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search,' the resource 'fetched record,' and the mechanism (semantic). It distinguishes from siblings by emphasizing 'already pulled' text and explicitly pairing with ask_pipeworx_grounded, making its niche unambiguous.

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

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

The description explicitly states when to use it: 'Use when the record is too big to cram into the prompt.' It also provides a concrete alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear contextual guidance without needing to list negatives.

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, the description adds substantial behavioral details: OAuth requirement, returned subscription ID, delivery channels, SMS verification and daily cap, webhook auto-disable after 10 failures, and one-time signing secret. It clearly explains side effects and operational constraints without contradicting the annotations.

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

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

The description is long but well-structured: it starts with the core purpose, then details supported types and delivery channels. Each sentence contributes useful information for a complex tool with nested parameters. Slightly verbose but appropriate for the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return value, authentication prerequisites, all subscription types, delivery options, and constraints. It provides enough information to correctly invoke the tool without ambiguity.

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 input schema already provides detailed parameter descriptions with examples. The description repeats these examples and only adds marginal extra info like the return value and feed pull method. Thus, it adds limited value beyond the structured schema.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It explicitly differentiates from siblings like list_subscriptions and unsubscribe by focusing on the creation of a subscription.

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 this tool (for proactive monitoring) and excludes anonymous/BYO users by requiring a Pipeworx OAuth account. It also implies an alternative by mentioning the feed can be pulled via recent_alerts, but it does not explicitly name alternative tools for given 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavior beyond annotations: it returns category-bucketed examples with tool/argument shapes, and mentions the optional topic parameter affects focus. 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 front-loaded with natural language example queries, which is useful. It is somewhat long, but each part serves a purpose: examples, return value description, calling pattern, and when to use. Minor redundancy with the schema 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?

For a tool with no output schema, the description explains what is returned (category-bucketed questions with tool/argument shapes), how to call it with and without parameters, and the specific use case. It also mentions the live catalog and meta-tools, making the context complete enough for an agent.

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

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

The input schema already provides 100% coverage of the 'topic' parameter with a list of values and 'omit for cross-category spread'. The description adds examples like 'finance', 'pharma', 'betting' but these are redundant with the schema, providing marginal additional 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 identifies suggest_questions as an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. This specific verb+resource combination distinguishes it from siblings like discover_tools and ask_pipeworx.

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

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

The description 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', providing a clear starting point. It does not name alternative tools, but the 'FIRST' emphasis implies when to select this over others.

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

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

The description adds valuable behavioral context beyond the annotations: ownership is enforced, and the row is deactivated (not deleted) to preserve historical events. This goes beyond the safety profile already provided by annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value. It is concise and well-structured without redundant words.

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

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

For a simple tool with one fully documented parameter, strong annotations, and no complex return values, the description is complete. It explains the ownership constraint and the soft-delete behavior, and references 'recent_alerts' to tie into the ecosystem, making it sufficient for an agent to use correctly.

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

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

The input schema fully documents the single parameter ('id') with a description ('Subscription id (uuid) returned by subscribe'), so schema coverage is 100%. The description adds little beyond the schema, only reinforcing 'by id', which does not significantly enhance parameter understanding beyond the baseline.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions), and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by being the inverse operation. It is specific and unambiguous.

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

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

The description gives clear context on when to use the tool (to cancel your own subscription, with ownership enforcement) and clarifies that it deactivates rather than deletes, which prevents misuse. However, it does not explicitly name alternatives or state when not to use it, but the context is sufficient for a simple tool.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent) by detailing the exact verdict enum, the pipeline for financial vs. other claims, the semantics of could_not_verify and unsupported (including verification_error{stage,detail}), and that it returns verbatim evidence with pipeworx:// citations. This is critical behavioral context not present in the schema or annotations.

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

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

The description is long but well-structured, starting with trigger phrases, then pipeline explanation, then verdict semantics, and a caller warning. Every sentence adds meaningful information; however, it could be slightly tightened by using bullet points or risk overwhelming the agent with a dense paragraph.

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

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

With no output schema, the description fully covers return values (verdict, actual value, citation, reasoning), error semantics, and routing logic. It also explains the tool's position relative to sequential alternatives. This is comprehensive for a tool of this complexity, making it highly usable without needing to read the underlying implementation.

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

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

The input schema already has 100% coverage with detailed descriptions for both parameters. The tool description adds value by explaining that tolerance_pct overrides the wording-implied tolerance, specifies a default cap at 5, and suggests 1–2 for hallucination detection—information not in the schema. This goes beyond the baseline of 3.

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

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

The description opens with concrete trigger phrases ("Is it true that…", "fact check", "verify the claim") and explicitly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes this from the sibling research tools by noting it replaces 4–6 sequential calls and synthesizes the verdict in one step.

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 clearly says "Use whenever the agent needs to check whether something a user said is factually correct" and even partitions financial claims vs. other claims with different handling paths. It does not explicitly name alternatives like ask_pipeworx_grounded or deep_research and when not to use them, but the guidance is strong enough to steer an agent correctly.

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