archive

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

Annotations already cover read-only, idempotent, open-world, non-destructive. The description adds valuable context: default model is free, Anthropic requires a user-supplied key with direct payment, and it returns per-model plus combined views. This goes beyond the structured hints without contradicting them.

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

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

Three sentences cover purpose, configuration, output format, and use cases. Front-loaded with the main action, no filler, 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?

Given moderate complexity (4 params, no output schema) and read-only nature, the description is sufficient: it names output fields ('score, confidence, signals, raw_response'), combined view, and supported models. Could mention what 'signals' contains or response size, but not critical for invocations.

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 description need not re-explain params. It adds extra semantics: explains the default model behavior for 'models', clarifies that '_apiKey' is passed straight through for Anthropic, and notes cost implications. This enriches schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model. The verb 'probe' plus 'score visibility' is specific and resource-oriented, and the mention of per-model output distinguishes it from siblings like scan_competitor_ai_presence.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies configuration choices (default Workers AI vs. BYO Anthropic key). No direct exclusions or named alternatives, but the context is clear and actionable.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals that it routes to 5,529 tools, fills arguments, returns stable citations, works on every tier, and makes a single fast call. It also discloses its behavior for breaking news, adding useful operational context without contradiction.

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

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

The description is longer than average but well-structured, starting with a strong directive, then explanation, examples, and alternatives. Each sentence earns its place, though some redundancy exists (e.g., 'default entry point' repeated). Overall, it is information-dense and effectively front-loaded.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete: it states the domain coverage, examples, return format, tier availability, and when to escalate to sibling tools. It covers essentially all the context an agent needs 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 schema has 100% coverage for all parameters, including aliases for 'question'. The description does not add extra parameter-level meaning beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: routes questions to a large set of sources, fills arguments, and returns structured answers with citation URIs. It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research and positioning itself as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for a wide range of factual queries, provides trigger phrases like 'what is' and 'look up', and gives step-up guidance: use ask_pipeworx_grounded for verbatim evidence and deep_research for multi-part questions. Also clarifies when it's still appropriate for breaking news.

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, open-world, idempotent, and non-destructive. The description adds crucial context about being the experimental edge with live candidate routing improvements, the current inactive status, and that it is a full working router, not a fallback. 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?

Four sentences convey the beta status, current equivalence, usage, and experimental nature. Some redundancy in the final sentence ('this IS a full working router') slightly pads it, but overall it is efficient and front-loaded.

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

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

Given the router's complexity (5,529 tools), the description covers what it is, how it differs from the stable version, current state, and response shape. No output schema exists, but mentioning identical response shape provides sufficient context for 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?

All six parameters have 100% schema coverage with descriptions for each alias. The description only says 'same arguments' as ask_pipeworx, adding no 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, same arguments, and same response shape. It explicitly positions it relative to the stable ask_pipeworx, making the purpose unmistakable.

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

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

It states 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router, giving explicit guidance on when to choose this variant. It also notes that when no candidate is active, it behaves identically to ask_pipeworx, further clarifying 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behaviors: extraction is limited to tool results, return shape includes verbatim evidence, and refusal reasons are enumerated. It also mentions the extra LLM call overhead. 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 information-dense but well-structured, with each sentence delivering distinct value: purpose, mechanism, output format, use cases, and cost trade-off. No redundancy, and front-loaded with the key value proposition.

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

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

Given the tool's complexity, the description thoroughly covers output structure (success and refusal), failure reasons, cost implications, and use cases. Even without an output schema, the return format is fully specified, making the tool's behavior 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?

The schema fully documents all six parameters as aliases for the question, with 100% coverage. The description adds no additional parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with a specific mechanism (grounded extraction from tool results) and output format. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-based answers and explicit refusals.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and contrasts with ask_pipeworx for casual lookups due to extra LLM call cost. This makes the choice between siblings unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond by detailing resolver match confidence, status codes for low-confidence/closed markets, parallel fan-out behavior, GDELT fallback mechanisms, illiquid spread warnings, and cancellation-rule parsing. This is extensive behavioral disclosure that helps agents anticipate edge cases.

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-organized with capitalized section labels (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, etc.). It is front-loaded with purpose and usage, and each section adds non-redundant operational details. The length is justified by the tool's complexity, though it is not as tight as a two-sentence ideal.

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

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

With no output schema, the description carries the full responsibility of explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, resolver match metadata, parent_event structure, news fallback fields, status codes, and cancellation rules. It also addresses edge cases like closed/dead markets and wide spreads, making it remarkably complete for a complex tool.

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

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

Schema coverage is 100% for all three parameters, giving baseline 3. The description adds meaningful context beyond the schema: it gives concrete slug/URL examples for 'market', clarifies the default for 'depth' (thorough), and explains the trade-off of 'include_raw' (response size vs. full upstream payload), which helps agents choose correctly.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data') and delineates the supported input forms (slug, URL, question text). It explicitly differentiates from siblings by stating intended use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), making the tool's role unmistakable.

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

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

The description provides clear when-to-use triggers via 'Use for' phrases and gives illustrative fan-out examples for various bet categories. However, it does not explicitly name alternative sibling tools or discuss when not to use this tool, so it falls short of the top anchor's explicit when/when-not/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?

The description goes far beyond the annotations by disclosing what data is pulled for each type (10-K revenue/net income/cash/debt for companies; FAERS counts, FDA approvals, trials for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and the inclusion of pipeworx:// citation URIs. These behaviors are not present in the annotations, adding substantial value.

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

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

The description is dense with valuable information: trigger phrases, use cases, data sources, fiscal-year handling, sorting, and output format. While it is long, every clause contributes practical guidance, and the most critical info (comparison action, preference over sequential lookups) is front-loaded.

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

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

With no output schema, the description compensates by specifying that it returns paired data with per-entity citation URIs and sorted by primary metric. It also conveys the parallel-call efficiency and the input constraints (2–5 entities). Despite its complexity, it provides a complete enough picture for an agent to select and invoke the tool correctly.

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

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

Schema covers both parameters 100% with descriptions and examples. The description enriches semantics by explaining that type='company' triggers SEC financial data extraction and type='drug' triggers adverse-event/trial data, and by detailing the expected data fields for each. This goes beyond the structural schema to help the agent understand the meaning of the parameter values.

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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses a specific verb (compare) and resource (entities), and distinguishes itself from single-entity lookups by emphasizing "ALWAYS PREFER over sequential single-pack lookups."

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

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

The description provides explicit when-to-use guidance, including trigger phrases like "which is bigger / better" and "rank these companies," and explicitly says to always prefer it over sequential lookups when comparing entities. It also contrasts with the alternative (8–15 sequential lookups), making the decision context clear.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, but the description adds extensive behavioral context: account and paid-plan requirements, parallel routing across 5,529 tools, gap[] handling ('never invented'), contradictions[] scan, citation_uri fetchability guarantee, semantic excerpting, and expected latency. This is a model of transparency with no contradiction to annotations.

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

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

The description is a single dense run-on paragraph containing a high volume of valuable information. While every sentence adds some useful detail, the lack of any structure (bullets, headers, or line breaks) makes it harder for an agent to parse efficiently. It could be more concise and better organized without losing substance.

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 thoroughly explaining the return envelope (findings packet: verbatim evidence, confidence, source, fetched_at, citation), the gap[]/contradictions[] behavior, hop field, citation_uri resolvability, and operational expectations (account tiers, latency, excerpting). It is exceptionally complete for the tool's complexity.

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

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

Schema coverage is 100% and the schema already describes both parameters in detail, including depth's hop behavior. The description's parameter-related content largely restates this information (e.g., 'standard' re-angles gaps, 'thorough' chases leads). It adds only minor contextual framing like 'multi-step questions resolve in one call,' so it meets the baseline but doesn't significantly surpass it.

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

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

The description clearly defines deep_research as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with specific actions (decomposes, routes, returns). It distinguishes itself from sibling ask_pipeworx and explicitly states it is NOT open-web search, making its purpose unmistakable.

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

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

Guidance is explicit and complete: it names when to use (broad/multi-part questions over structured data), when to use alternatives (ask_pipeworx for single lookups or breaking/colloquial news), and even covers signed-in/plan prerequisites. This exceeds simple context by giving actionable 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, idempotent, and non-destructive. The description adds valuable behavior beyond annotations: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and states that results are ready to call directly with no second schema lookup. 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 the core purpose ('Find tools...') and provides useful context about return format and when to call first. The domain list is somewhat long but serves a practical purpose for a discovery tool. Each sentence contributes value, though it could be slightly tightened.

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

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

Given the tool's simplicity (one required string parameter), the description is complete. There is no output schema, but the description explicitly covers the return format: top-N tools with names, descriptions, and full input schemas. It also notes 'no second schema lookup needed,' covering an important behavioral aspect. Nothing critical is missing.

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

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

Schema description coverage is 100%, with all parameters (query, q, task, limit, search, description) fully documented, including aliases. The description mentions 'top-N' but the limit parameter is already in schema. It adds no additional parameter meaning beyond what the schema provides, so 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 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes this tool from siblings by focusing on tool discovery rather than data search, and lists concrete domains (SEC filings, FDA drugs, etc.). This is a fully specified purpose that leaves no ambiguity.

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 'Call this FIRST when you have many tools available' and 'Use when you need to browse, search, look up, or discover what tools exist.' This gives clear when-to-use context. However, it doesn't explicitly name alternatives or state when NOT to use it, 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 read-only/idempotent/destructive hints, but the description goes far beyond: it details the parallel fan-out across sources, enumerates return fields (filings, fundamentals, patents, news, LEI), mentions patent API sunset with soft-fail, and discloses fallback behavior. 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 long but densely packed with unique information: examples, fan-out behavior, specific return fields, and input constraints. Every sentence earns its place, and the structure is front-loaded with user intents, making it efficient for an agent 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?

Even without an output schema, the description fully enumerates what will be returned (CIK, filings with URIs, fundamentals, patents, news mentions, LEI) and includes limitations (patent soft-fail, names not supported). It is self-contained for an agent to judge appropriateness and invoke correctly.

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

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

Schema coverage is 100% and both the schema and description already explain the ticker/CIK format and the 'company' type. The description merely repeats this information without adding new parameter-level semantics, so baseline 3 applies.

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

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

The description uses a specific verb+resource combination ('full cross-source profile of a US public company') and provides concrete example queries. It distinguishes itself from sibling tools by explicitly preferring this over chaining single-pack lookups, making the purpose unmistakable.

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

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

The description states when to use it ('when the user asks for a holistic view') and when not to ('names not supported'), with an explicit alternative (use resolve_entity first for names). This is clear, actionable guidance for an agent deciding between tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is known. The description adds context about clearing sensitive data and that the memory was previously stored, but does not disclose additional behaviors like irreversibility or error handling. With annotations present, this is acceptable but not rich.

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

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

Two sentences, front-loaded with the action and followed by usage guidance. Every word earns its place.

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

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

This is a simple tool with one parameter, no output schema, and strong annotations. The description covers purpose, usage timing, and relationship to paired tools. Given the low complexity, it is complete enough.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description only repeats that deletion is by key, adding no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by positioning as the deletion counterpart.

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 use cases: when context is stale, the task is done, or to clear sensitive data. It also mentions pairing with remember and recall, though it does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds useful context beyond annotations by explaining the fetch-extract-emit workflow and the output format ('single text blob'), which helps set expectations about behavior without contradicting the structured data.

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

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

The description is concise and front-loaded, with the main purpose in the first sentence. The process and use-case list are efficient and add value without redundancy, though the 'Useful for' list could arguably be trimmed slightly.

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 read-only tool with no output schema, the description covers the core purpose, process, output format, and typical use cases. It does not mention edge cases or error handling, but these are not critical for this type of tool, and the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' adequately described. The tool description adds minor context (e.g., 'for any URL', 'key links') but does not significantly improve parameter meaning beyond what the schema already provides.

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 generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It describes the process (fetches page, extracts title/description/key links, emits standard format) and distinguishes itself from sibling tools by focusing on the llms.txt output standard.

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

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

The description provides clear, explicit use cases: getting a client's site indexed, drafting for your own project, and auditing competitor visibility. It does not name alternative tools explicitly or state when not to use it, but the context is strong enough for an agent to select it appropriately.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds useful context by specifying the tool returns title, creator, date, format, size, and access details, going beyond the annotation info.

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 concise sentences, front-loaded with the action and resource. Every word adds value, with no redundancy.

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

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

For a simple read-only tool with one fully documented parameter and an output schema, the description covers all essential behavior. It is complete and sufficient for the agent to select and invoke correctly.

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

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

The schema fully describes the single 'id' parameter with examples and 100% coverage. The description adds no further semantic detail, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Get full metadata for an archived item by identifier.' This specific verb+resource scope distinguishes it from sibling tools like search or list_files.

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

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

The description clearly implies usage when an identifier is available, but it does not explicitly name alternatives or exclusions. It provides clear context (by identifier) without explicit when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it notes the tool is keyless, that download URLs are constructed rather than directly served, and clarifies the scope as archive.org items, not Wayback snapshots. This gives the agent a better understanding of what to expect.

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 exceptionally concise: two sentences plus a parenthetical. It front-loads the core action and resource, then provides essential usage hints and a scope clarification. Every statement earns its place without unnecessary detail.

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

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

The tool is simple, and the description covers the action, input, output fields, prerequisites, and limitations. The schema covers parameters and defaults, so nothing critical is missing. No output schema exists, but the description sufficiently explains what the tool returns.

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

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

Schema coverage is 100%, with both 'id' and 'limit' fully described in the input schema, so the baseline is 3. The description reinforces the 'id' parameter but does not add additional meaning beyond the schema for 'limit' or return behavior. It neither enhances nor detracts from the schema's clarity.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: downloadable files for an archive.org item by identifier. It also lists the return fields (name, format, size, constructed download_url) and explicitly distinguishes from Wayback snapshots, setting it apart from sibling tools like wayback_check.

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 gives explicit when-to-use guidance: 'Use search / get_metadata first to find an identifier.' It also states what it is not for ('not Wayback snapshots') and that it is keyless, indicating no authentication setup is needed. This is clear and actionable.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping the result to 'the caller's' subscriptions, which is not captured in the annotations. No contradictions found.

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

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

The description is two sentences, front-loaded with the purpose, and every sentence earns its place. The first sentence states what it does, the second lists return fields and gives use cases. No redundancy or fluff.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description is complete: it covers purpose, return fields, and usage guidance. The annotations provide the safety profile, so the description doesn't need extra behavioral detail. It enables an agent to decide when to call it and what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not mention the 'include_inactive' parameter, but the schema already fully documents it. The description's mention of 'active subscriptions' implicitly aligns with the default false, but adds no new parameter-specific knowledge.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It also distinguishes itself from sibling tools like subscribe and unsubscribe by specifying it returns existing subscriptions, and it enumerates the returned fields, making the purpose unambiguous.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool (before subscribing, when needing to cancel) without explicitly naming alternatives. It lacks a direct 'when not to use' statement, but the use cases are sufficiently clear.

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

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

Annotations provide no behavioral hints (all false), so the description carries the full burden. It discloses the claim_token round-trip workflow, rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and what happens after filing ('team reads digests daily and signal directly affects roadmap'). It also scopes the tool to this Pipeworx connection, adding critical contextual transparency.

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

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

The description is longer than average but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers when to use, exclusions, claim_token handling, and operational details (rate limit, cost). There is no fluff or redundancy; the length is justified by the tool's complexity.

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

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

The tool has four parameters, a nested context object, and no output schema, so the description must explain the full context. It does so thoroughly: it explains the feedback types, the claim_token read-back mechanism, the scope restriction, and the daily digest/roadmap impact. It even advises on message content. Nothing critical is missing for an agent to invoke this 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?

Despite 100% schema coverage, the description adds substantial semantic value: it explains the claim_token pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and maps type categories to usage scenarios. This goes well beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling research tools by defining the feedback scope (bug, feature/data_gap, praise) and explicitly excludes feedback about other servers. This leaves no ambiguity about the tool's 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?

Provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' and offers a fallback for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists'). This is ideal usage guidance.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds non-obvious context: the data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on window. This goes beyond the annotations and enriches the agent's mental model.

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

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

The description is well-structured: a clear lead sentence, a list of use cases, and a final line about data source/caching. It is slightly longer than necessary, but every sentence adds relevant information and there is no fluff.

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

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

For a simple tool with one optional parameter and rich annotations, the description is fully complete: it specifies output contents (top tools, top packs, volume, and (pack, tool, count) tuples), gives concrete use cases, explains caching behavior, and clarifies privacy/aggregation. An output schema is unnecessary here.

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

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

The schema covers the window parameter fully with enum values and descriptions for hot vs steady-state meaning (100% coverage). The description adds a useful extra detail that the cache TTL depends on the chosen window, providing additional semantic 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 immediately states what the tool returns ('top tools, top packs, and total call volume'), uses a specific verb ('returns'), and frames the resource as 'what other AI agents are calling on Pipeworx right now.' This clearly distinguishes it from siblings like discover_tools by emphasizing trending aggregate 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 (discovering hot data sources, confirming canonical tools, checking alignment), making the 'when to use' context clear. However, it does not mention when not to use it or name alternative sibling tools, so it stops 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?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses algorithmic details (Jaccard similarity threshold, placeholder filter, partition_check deviation >3pp), output structure, fill-check behavior (theoretical vs realizable edge at 1000 shares/leg), and a non-obvious caveat that realizable_edge_pp ≤ 0 indicates book depth is insufficient. This is rich behavioral 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 dense but well-structured with clear mode markers and bolded section labels. It is longer than typical, but every sentence carries operational value. A small reduction in verbosity (e.g., merging the FILL CHECK details) could tighten it, but it remains readable and front-loaded with purpose.

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

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

Given no output schema, the description introduces the response shape, including opportunities[] fields and partition_check structure, and explains edge-case behavior. It covers all three modes, the placeholder filter, similarity anchor, and fill-check semantics, making it sufficient to use the tool correctly without external 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?

Although schema coverage is 100%, the description adds substantial meaning: 'event' expects a slug or full URL, 'topic' is a seed question, and it explains what happens in each mode. It also clarifies that 'event' walks child markets and computes a partition_check, while 'topic' flattens related events—something the schema does not convey.

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

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

The first sentence states the exact purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It differentiates three invocation modes (no args, event, topic) and explicitly recommends event for specific markets, distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also gives a fill-check rule ('do not trade it') and points to polymarket_fill_risk for custom sizing, making alternatives 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?

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: internal segmentation into three model families, precise edge calculation (net of slippage, Kelly capping at 0.25), the 24h-move warning, and a 'why is this empty' diagnostics section. It also discloses caching behavior ('Cached 1h at the KV level keyed on all knobs') and limitations (Fed signal unreliability), going well beyond what annotations alone convey.

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

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

The description is long and dense with technical jargon, but it is well-structured: purpose, model families, response segments, knobs, caveats, diagnostics, and caching. Every sentence adds information for a complex tool with nine knobs and multiple output segments. It could be slightly more streamlined, but the density is justified by the tool's complexity; it front-loads the core purpose before diving into detail.

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

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

With no output schema, the description carries the full burden of explaining the response shape, and it does so thoroughly: top-level by_segment structure, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also explains the meaning of edge fields (edge_pp_net, kelly_fraction, market.liquidity) and the 24h-move warning. This is complete enough for an agent to know what to expect and how to interpret results.

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

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

The input schema has 100% parameter descriptions, so the baseline is 3. The description adds conceptual value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their interplay (e.g., min_partition_leg_kelly is needed because partition arbs return kelly_fraction_half=0 at the parent level). This extra layer clarifies why and when to adjust knobs, going beyond the schema's per-parameter definitions.

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

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

The description opens with a specific verb-resource pair ('Scan top Polymarket markets') and a clear outcome ('return opportunities where Pipeworx data disagrees with market price'). It narrows the scope to 'what should I bet on today' and explicitly avoids paging hundreds of markets, distinguishing its intent from broad list tools. This is more specific than many sibling tools, giving a clear sense of what this tool uniquely does.

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

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

The description gives a strong use case ('Built for "what should I bet on today"') and provides operational guidance on knobs like min_liquidity and max_spread_pp ('drop opportunities where edge isn't realizable'), and notes the Fed signal caveat ('excluded from ranking — 1m-T vs EFFR signal is unreliable...'). However, it does not explicitly contrast this tool with sibling alternatives (e.g., polymarket_edge_tracker or polymarket_fill_risk), so the when-not-to-use guidance is implicit rather than explicit.

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, idempotentHint, and non-destructive behavior, and the description aligns with these while adding substantial context: snapshot write conditions, data gaps, TTL limits, and that decay is computed from daily closes. This goes well beyond annotations and enriches behavioral understanding.

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

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

The description is dense but well-structured: purpose, args, response breakdown, and limitations are clearly separated. Every sentence contributes essential information, 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?

Given the tool's complexity and lack of output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their semantics, including edge trends and decay calculations. It also covers limitations and data-gap behavior, making it complete 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 already covers both parameters with descriptions, but the description adds domain-specific meaning: days controls lookback with defaults and max, window selects the snapshot family and default, and explains that window relates to polymarket_edges window families. This adds semantic value beyond the schema.

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

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

The description clearly states a specific function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from the sibling polymarket_edges by focusing on time-series tracking and answers a concrete question ('how long has this edge existed and is it shrinking?').

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

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

The description provides clear context for when to use the tool: to distinguish fresh vs. old edges, explicitly contrasting their trade significance. It does not name alternative tools explicitly but implies it complements polymarket_edges by adding temporal depth, which is sufficient 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?

Even though annotations already declare readOnly, idempotent, and non-destructive, the description adds crucial behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and warns that partial basket fills convert an arb into unhedged directional risk—the dominant loss mode. This goes well beyond the annotation 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 dense but extremely efficient. It front-loads the core purpose, then uses structured sections (SINGLE-MARKET, BASKET) and imperative guidance. Every sentence adds unique information—no filler—making the length justified by the tool's complexity.

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

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

With no output schema, the description fully enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, ...). It also covers prerequisites, defaults, and practical risk context, giving an AI agent everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds significant semantic nuance: it explains mode-dependent interpretations of `size_usd` (max spend vs target proceeds vs settlement notional), side defaults and auto-detection for baskets, and clarifies the `market` vs `event` parameter distinction. This enhances what the schema alone provides.

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 itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, and explains both single-market and basket modes.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on it, citing thin-book overround and partial-fill risks, making alternatives and exclusions clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: how compatibility_warning fires under two distinct conditions, the temporal_alignment check, skipped_cross_type/subtype counters, and the caveat that most pre-mapped topics return warnings. This goes well beyond the annotations.

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

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

The description is long but well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, and the length is justified by the complexity of the tool. Slightly verbose for a typical tool description, but not padded.

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

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

Despite lacking an output schema, the description covers the response structure (leg-by-leg prices, top_spreads_pp), safety fields with their meanings, and edge cases like temporal misalignment and non-equivalent bet shapes. This is sufficient for an agent to understand when and how to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three optional parameters, but the description enriches them significantly. It explains that `topic` auto-fetches the matching event on each venue and that explicit `kalshi_event_ticker` and `polymarket_event_slug` override the mapped side, clarifying the interplay between the two modes.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing specifically on this cross-venue comparison and names two operational modes (topic shortcuts and explicit pairings).

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 usage context: when to use topic shortcuts vs custom ticker/slug, and explains that real spreads are rare and pre-mapped topics may not be tradeable. It does not name direct alternatives like 'use polymarket_arbitrage for same-venue comparisons', but the exclusions for meaningful spreads (compatibility_warning, temporal_alignment) are clearly spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond that: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and supports two distinct behaviors (retrieve value vs. list all keys when key omitted). It doesn't contradict annotations; the added scoping information enriches the transparency.

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

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

The description is three sentences with no filler. The first sentence states the core action, the second explains the use case, and the third clarifies scoping and sibling relationships. It is front-loaded and every sentence adds value.

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

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

This is a simple tool with one optional parameter and no output schema, so the description carries the full explanatory burden. It covers purpose, usage, scoping, and alternatives. The inclusion of examples and pairing with remember/forget makes it complete for agent decision-making.

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

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

Schema description coverage is 100% for the single 'key' parameter, so the baseline is 3. The description adds meaning by explaining that omitting the key triggers list-all-keys behavior, which is not fully evident from the schema alone. It also gives examples of key values ('target ticker', 'address', 'research notes'), helping the agent understand what kind of data to store.

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: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly differentiates from siblings like remember and forget by naming them and explaining the relationship. The examples (target ticker, address, research notes) concretize the tool's role as a memory lookup.

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 when to use this tool: 'Use to look up context the agent stored earlier — without re-deriving it from scratch.' It also provides direct alternatives via 'Pair with remember to save, forget to delete,' guiding the agent to the correct sibling for related operations. This is clear usage guidance.

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

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

Annotations already declare the operation read-only, non-destructive, and idempotent, so the bar is lower. The description adds valuable context beyond that: mark_read:true has a side effect of flagging events read, and polling is safe. It does not mention rate limits or auth, but the key behavioral nuances are disclosed.

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

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

The description is a compact paragraph of about 60 words, front-loaded with the main action, and every sentence adds specific value: return payload contents, filtering options, mark_read behavior, and polling/alternative access. No redundancy or fluff.

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

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

Despite lacking an output schema, the description thoroughly explains what each returned alert contains (source, citation_uri, raw payload), covers filtering and pagination (limit), and addresses mark_read and unread_only behavior. It is sufficiently complete for an agent to invoke the tool correctly without further clarification.

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 covers 100% of parameters, giving a baseline of 3. The description enhances this by providing a concrete example for type ('sec_8k'), explicitly explaining the ISO timestamp for since, and clarifying the side effect of mark_read. This goes beyond the schema's dry 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 starts with a specific verb and resource ('Pull fired events from your subscription feed'), clearly distinguishing it from subscription management siblings like subscribe/unsubscribe. It also explains what the returned alerts contain, making the tool's purpose unmistakable.

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

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

The description implies when to use the tool (to fetch recent alerts) and offers a concrete alternative for scripts/dashboards (the GET endpoint), but it does not explicitly say when not to use it or compare it to other sibling tools. The mention of polling and mark_read also provides practical usage context.

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

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

Annotations already establish readOnly/idempotent behavior, but the description adds substantial context: parallel fan-out, source-specific behavior (SEC, GDELT/GNews priority, USPTO soft-fail due to API sunset), and 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 dense but well-organized, starting with example use cases and then explaining mechanics. Every sentence adds value, though it could be tightened slightly without losing information.

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

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

Given the tool's complexity (multiple data sources, fallbacks, time handling, return format), the description covers all key aspects: what it returns, how to specify time, source behavior, and when to use an alternative. No output schema exists, but return structure is described sufficiently.

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 all parameters with descriptions, so baseline is high. The description adds practical nuance for since (ISO vs relative shorthand, examples, typical monitoring recommendation) and clarifies value can be ticker or CIK. This goes beyond schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, fanning out to SEC, news, and patent sources. It uses specific verbs and resources and explicitly differentiates from the sibling tool entity_profile by contrasting windowed changes vs static profiles.

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

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

Provides concrete example queries that indicate when to use it, and explicitly directs users to entity_profile for static profile needs. It also explains fallback behavior (GDELT→GNews) and gives parameter guidance like 'Use 30d or 1m for typical monitoring.'

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 discloses key behavioral details: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain memory for 24 hours. This adds meaningful context about data lifetime and scoping that annotations (readOnlyHint, idempotentHint, destructiveHint) 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 four sentences, each earning its place: purpose, use case, persistence, and related tools. It is front-loaded with the main action and wastes no 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 2-parameter write tool with no output schema, the description covers purpose, usage, persistence, scoping, TTL, and sibling relationships. It is fully self-contained and leaves no major questions unanswered.

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 provides examples for key and value. The description reinforces these examples ('resolved ticker, target address...') but adds no new parameter-specific semantics beyond what the schema already states, so 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 starts with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly states the tool's function (storing key-value pairs) and distinguishes it from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 ('when you discover something worth carrying forward — a resolved ticker, a target address, a user preference, a research subject') and mentions complementary tools recall and forget, giving clear guidance on when and how to use this tool.

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

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

Despite annotations already declaring read-only, non-destructive behavior, the description adds valuable behavioral detail: cascading internal lookups, graceful degradation when LEI/FIGI sources are unavailable, explicit labeling of sources for each identifier, and disclosure that unresolved identifiers are stated under `unresolved`. This fully informs the agent about 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 dense but well-organized, starting with practical query examples, then a 'USE FIRST' directive, followed by supported types and behavior. It packs substantial information into a compact space, though it is somewhat run-on and could benefit from bullet points for the supported types section.

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 entity types, multiple identifiers, source labeling, fallback behavior) and the absence of an output schema, the description provides comprehensive context. It covers what identifiers are returned for each type, how failures are handled, and the fact that each call replaces several manual lookups, leaving no major gaps.

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

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

The schema already provides 100% coverage with detailed descriptions and examples for both `type` and `value`. The tool description largely repeats this information (e.g., 'accepts ticker, CIK, or company name') and adds output-oriented context rather than new parameter semantics. Thus it does little 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 explicitly states the tool resolves a user-spoken name to canonical/official identifiers required by other tools, with clear examples ('What's the ticker for…'). It distinguishes from siblings by specifying 'Use FIRST whenever you have a name but need an ID' and enumerating supported entity types (company, drug).

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 FIRST whenever you have a name but need an ID') and describes supported input forms per entity type. However, it does not explicitly mention when not to use the tool or name alternative sibling tools (e.g., entity_profile), so it falls short of full exclusionary guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes beyond these by disclosing the probing process (calls ai_visibility_check per entity), the ranking logic, and the return structure (ranked list with score, confidence, signal density). This adds behavioral detail not encoded in the annotations, though it does not cover potential call limits or external dependencies.

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 core purpose, and every sentence adds value: function, process, use case, and output. There is no redundancy or filler, making it highly 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?

For a tool with no output schema, the description adequately explains the return values (ranked list with score, confidence, signal density). It also covers the use case and the probing workflow. It does not mention the optional models or _apiKey parameters, but those are fully documented in the schema, and the description covers the essential behavior and outputs.

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

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

Schema description coverage is 100%, so the schema already documents all parameter meanings. The description adds minimal extra semantics: it clarifies that entities include 'your brand + N competitors' and mentions 'probes each entity', but these largely echo the schema's 'First entry treated as the subject' and the parameter descriptions. No substantial added value beyond the schema.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side. It specifies the action ('Compare'), the resource ('AI visibility across multiple entities'), and distinguishes it from the sibling tool ai_visibility_check by emphasizing the multi-entity comparative nature ('your brand + N competitors', 'ranks by score').

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 includes a concrete use case ('competitive AI-marketing audits') and explains the workflow ('Probes each entity with ai_visibility_check'). It does not explicitly name alternatives, but the phrase 'side-by-side' and 'multiple entities' implies when this tool is appropriate versus the single-entity sibling, providing clear context without formal exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveHint. The description adds behavioral details beyond those: partial failure degradation, bundlephobia's first measurement taking 5-30s, sources_failed indicating timeouts while other data still returns. It also discloses the return summary block fields, making behavior predictable without contradicting annotations.

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

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

The description is well-structured: starts with the core purpose, then usage triggers, return format, ecosystem scope, and failure behavior. Though it's longer than a simple tool description, each sentence adds distinct value and the format is front-loaded. No filler or redundancy.

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

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

Despite having no output schema, the description enumerates the exact summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) plus per-advisory detail and alternative versions. It covers edge cases like timeouts and partial failures, and specifies the ecosystem limitation. For a composite tool with two external sources, this 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 coverage is 100%, so both 'package' and 'version' are already documented. The description adds meaning by stating the 'package' param expects npm package names and mentions scoped packages are accepted. It also clarifies version defaults to latest when omitted, echoing the schema but reinforcing the semantic. Since the baseline for high schema coverage is 3, the added param context raises it to 4.

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

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

The description clearly states a specific composite action: 'should I add this npm package to my project' check, listing the two data sources and what each contributes. It distinguishes itself from siblings like validate_claim and scan_competitor_ai_presence by explicitly scoping to npm dependency evaluation with license/advisory/version/bundle information.

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 trigger phrases: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', steering users to an alternative path. This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no behavioral traits beyond what annotations and schema provide—it only restates the search mechanism ('by keyword') and return fields, both of which are already in the input schema and output schema. No mention of rate limits, pagination, or result variability.

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

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

The description is two sentences, front-loaded with the primary verb and resource, and every word contributes meaning. 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?

Given the tool's simplicity, rich annotations, complete parameter schema, and presence of an output schema, the description fully covers the tool's scope and return content. It is complete and self-sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for both 'query' and 'limit'. The description does not add any additional parameter meaning beyond the schema, so it meets 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 uses the specific verb 'search', names the resource 'Internet Archive', and enumerates the content types (texts, audio, video, software) and returned fields (titles, identifiers, descriptions, media types). This clearly distinguishes it from sibling tools like 'search_within' or general search 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 provides clear context for use: keyword searching across Internet Archive media types. It does not explicitly name alternatives or exclusions, but the scope is unambiguous. Sibling tools like 'search_within' exist but are not referenced, which keeps this at a 4 rather than a 5.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior, but the description adds substantial context: character offsets, similarity scores, BGE-base-en embeddings over 500-char windows, and a 200K char cap with truncation flag. This goes well beyond the structured fields and enables the agent to anticipate output and limits.

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

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

The description is front-loaded with the core purpose, and every sentence earns its place: usage, when-to-use, companion tool, and technical details. It is dense but not verbose, with no filler.

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

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

Even without an output schema, the description clearly specifies the return format (passages with offsets and similarity scores), covers the 200K char cap and truncation behavior, and explains how it integrates with ask_pipeworx_grounded. For a moderately complex tool, this is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real-world examples for text (SEC 10-K, article, tool result) and clarifies the relationship between the text and query parameters, which is slightly beyond the schema's individual parameter descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly identifying the verb (semantic search) and resource (records already fetched). It distinguishes itself from siblings like 'search' and 'ask_pipeworx_grounded' by emphasizing it operates on existing text and returns passages with offsets and scores.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also pairs with ask_pipeworx_grounded, giving a concrete complementary workflow and an alternative to using the whole document.

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 the tool mutates state (readOnlyHint=false) and is idempotent. The description adds useful behavioral context: the OAuth requirement, the always-on feed, SMS verification and the 10/day cap, and that the function returns a new subscription id. It does not contradict any annotation and discloses more than the structured fields alone.

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

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

The description is information-dense and front-loaded with the core purpose, followed by auth requirements, supported types, and delivery channels. It avoids fluff but partially duplicates examples already present in the schema, making it slightly longer than strictly necessary.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is reasonably complete: it explains the return value, auth prerequisites, three of the five subscription types, and delivery channel constraints. Webhook details and the remaining two types are covered by the input schema, so the overall definition is 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?

Since schema coverage is 100%, this dimension is evaluated from a baseline of 3. The description adds meaning beyond the schema by interpreting item codes (e.g., 'items:["5.02"] = officer change'), clarifying polymarket_edge as cross-venue mispricings, and explaining fred_series as new FRED observations. These enrich the parameter examples already present in the schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and explicitly states 'Returns the new subscription id.' This is a specific verb+resource pair that clearly distinguishes the tool from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides clear context: it requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It also explains the supported subscription types and delivery channels, including a pointer to recent_alerts for pulling from the always-on feed. However, it does not explicitly contrast this tool with alternatives such as list_subscriptions or unsubscribe.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it draws from a live catalog, returns category-bucketed examples, and includes exact tool+argument shapes. This goes beyond what annotations provide, though it doesn't discuss limits or error behavior.

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

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

The description is a single dense paragraph but front-loaded with example queries and clearly organized. It packs a lot of useful information, though the list of example phrasings could be slightly trimmed without losing meaning. Overall, it earns its length.

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

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

Given there is no output schema, the description thoroughly explains what is returned (category-bucketed example questions with exact tool+argument shapes), when to use it, and how to parameterize. It fully defines the tool's scope and output, making it complete for an onboarding tool.

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

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

Schema coverage is 100% for the single optional topic parameter, which lists valid focus areas. The description reinforces this with examples ('finance', 'pharma', 'betting') and explains focusing, so it adds a little value, but the schema already carries the semantic weight.

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 this is the onboarding entry point for an agent to discover what Pipeworx can do, returning category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('suggest', 'returns', 'call') and differentiates from siblings like ask_pipeworx by explicitly mentioning it teaches how to call meta-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?

Explicitly directs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and clarifies how to focus with the topic parameter. It also implicitly distinguishes from alternatives by naming the meta-tools one would learn to call, and notes that omitting arguments gives the full spread.

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 (write operation, idempotent, non-destructive), the description adds valuable behavioral detail: ownership is enforced, and the row is deactivated not deleted, preserving historical events via recent_alerts. 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?

Three sentences, each with distinct purpose: action, ownership constraint, and side-effect behavior. No wasted words; front-loaded with the primary action.

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

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

Despite having no output schema and only one parameter, the description fully covers what happens on cancellation, the ownership restriction, and the relationship to recent_alerts. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the parameter description explains id as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter semantics beyond referencing 'by id,' so the baseline 3 applies.

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

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

The description starts with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from sibling tools like subscribe and list_subscriptions. The scope is precise: by id, with ownership enforcement.

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

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

It provides clear context: use this to cancel a subscription by id, with the constraint that only your own subscriptions can be cancelled. It doesn't explicitly mention alternatives or when not to use, but the sibling list and description make the use case obvious.

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, idempotent). It discloses critical behavior: the dual processing paths, the exact verdict set, the inclusion of evidence citations, and most importantly the semantic distinction between 'could_not_verify' (verification failed, must not be used as evidence) and 'unsupported' (no source coverage). This is essential for correct agent interpretation.

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

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

The description is long but information-dense. It front-loads user-facing phrasings, then moves to usage, behavior, return values, and caveats. Each sentence adds value, though the final sentence about replacing 4-6 calls could be considered a bonus rather than necessary. The structure is logical, and the caveat about 'could_not_verify' is explicitly highlighted.

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 specifies the return object (verdict, value with citation, reasoning) and explains the error semantics. It covers input, routing logic, and both claim types. With only 2 parameters and rich annotations, the description leaves no important gaps for an agent to invoke and interpret the tool correctly.

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

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

The schema already covers both parameters with examples and descriptions, but the description adds key operational nuance: tolerance_pct overrides the tolerance implied by the claim wording, recommends 1-2 for hallucination detection, and notes the default cap of 5. This enriches the schema's static 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 identifies the tool as a claim verification tool with specific verbs: 'fact check', 'verify the claim', 'confirm or refute'. It distinguishes itself from sibling tools by focusing on natural-language claims and explicitly stating it replaces 4-6 sequential calls, which sets it apart from general search or research tools.

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

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

The description explicitly states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct'. It also differentiates between company-financial claims (routed to SEC EDGAR/XBRL) and other claims (grounded pipeline), providing clear context for both. It doesn't name alternative tools or give explicit 'when not to use' exclusions, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description adds that it returns capture dates and a direct link to the archived version, which is useful behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes return value information without unnecessary 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 tool with one parameter and an output schema, the description adequately covers the purpose and return value. It does not discuss edge cases like missing snapshots, but the output schema likely covers that. Overall, it is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% description coverage for the single 'url' parameter, including an example. The description does not add additional parameter semantics beyond what the schema already states, so a baseline score of 3 is appropriate.

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

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

The description uses specific verbs 'check' and 'retrieve' with a clear resource (URL archive snapshot). It also indicates what the tool returns (capture dates and direct link). This clearly distinguishes it from the listed sibling tools, none of which appear to focus on web archive lookups.

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

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

The description implies usage for when a user wants to see if a URL has been archived and obtain the closest snapshot. It does not explicitly mention alternatives or exclusions, but the context is clear. Since no sibling tool offers this capability, the selection is straightforward.

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