Timestamp

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

Annotations already indicate read-only and idempotent behavior. The description adds context: it probes LLMs, returns per-model scores with confidence/signals, and explains data flow for Anthropic (BYO key). No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. It could be slightly more structured (e.g., bullet points for use cases), but it is efficient and clear.

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

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

Despite lacking an output schema, the description explains the return format (per-model objects with score, confidence, signals, raw_response, and combined view). It covers all necessary aspects: action, parameters, return, and use cases.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond schema: default model, purpose of _apiKey, context for disambiguation. This provides extra guidance for correct invocation.

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 entity knowledge and scores visibility 0-100 per model. It specifies the default model and optional Anthropic integration, and distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use this tool or compare it directly to alternatives. Some guidance on exclusion is missing.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: it routes internally across many tools, fills arguments, returns structured answers with stable citation URIs, and covers live news via news-feed packs. It does not discuss failure modes or latency, but that is minor for this tool.

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 'PREFER OVER WEB SEARCH' and a dense list of covered domains. Examples and sibling routing guidance are useful, and nearly every clause contributes. It is long, but the length is justified by the scope; there is minor redundancy with 'even if web search could also answer it' after the opening sentence.

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 one-parameter tool with no output schema, the description is complete: it covers domains, trigger phrases, examples, return behavior, citation format, and explicit alternatives. An agent has everything needed 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 coverage is 100%, and the schema already documents the single 'question' parameter plus all aliases. The description provides example questions, but these mostly reinforce the schema examples rather than adding new parameter-level meaning. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it routes factual questions to one of 5,767 tools across 1,506 verified sources, fills arguments, and returns answer with citation URIs. It also distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell this is the general entry point.

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

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

The description explicitly says to prefer this over web search, lists trigger phrases like 'what is', 'look up', 'find', and 'current', and gives six concrete example questions. It also names when to use ask_pipeworx_grounded and deep_research instead, making the selection criteria clear.

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

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

Goes well beyond the annotations by disclosing the experimental state ('no candidate is active right now, retired on 2026-07-26'), that behavior currently matches ask_pipeworx exactly, that results feed merge decisions, and crucially that 'falls back to nothing — this IS a full working router.' This prevents the common misassumption that a beta tool is a non-functional stub.

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 dense sentences, each earning its place: identity, current state, usage directive, and a fallback clarification. The parenthetical '(same 5,767 tools, same arguments, same response shape)' is compact and informative. Slightly long for a simple tool, but the experimental nuance justifies the length.

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

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

Complete for the core decision of whether to call this vs ask_pipeworx: it covers current routing state, the absence of active candidates, comparison behavior, and the no-fallback guarantee. Return values are handled via 'same response shape' referencing the stable sibling; an agent unfamiliar with ask_pipeworx would still lack concrete response details, but that shared context is a reasonable assumption given the sibling list.

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 of 3 applies: the schema already documents 'question' and its four aliases (q, text, input, prompt). The description adds only the contextual note that arguments are identical to ask_pipeworx, which confirms rather than extends schema semantics. (Minor note: context signals report 6 parameters but the schema shows 5.)

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

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

The description states exactly what the tool is: a beta version of ask_pipeworx, an identical universal router covering 5,767 tools with the same arguments and response shape. It clearly differentiates from its stable sibling ask_pipeworx and the grounded variant, so an agent can tell them apart immediately.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and frames results as being compared against the stable router. It names the alternative and the selection condition, though it does not state an explicit when-not (e.g., 'for production stability use ask_pipeworx').

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 by disclosing the full success return shape, the refusal contract with enumerated refusal_reason values, the verbatim evidence requirement, and the extra LLM call cost. This adds substantial behavioral context without contradicting the readOnly/idempotent 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 each clause earns its place: purpose, routing behavior, result/refusal format, usage conditions, and alternative preference. Key constraints are front-loaded and no schema content is redundantly repeated.

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 fully compensates by specifying the exact success and refusal response shapes. It also covers grounding source behavior, high-stakes suitability, and cost/alternative tradeoff, so an agent has everything needed to invoke it correctly.

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

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

The input schema has 100% description coverage and already documents the question parameter and its aliases. The tool description does not add new parameter-level semantics beyond noting that routing fills arguments, so the baseline score 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 identifies a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and clearly distinguishes it from the sibling ask_pipeworx by explaining that it extracts answers only from the tool result. This makes the tool's role and scope immediately clear.

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

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

It explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use it ('prefer ask_pipeworx for casual lookups'). It also names the alternative and the cost tradeoff, leaving no ambiguity.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond, detailing fan-out logic, response shapes, resolver contract, parent event extractor, news fallback mechanisms, safety short-circuits, cancellation rule parsing, and blocking paths. 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 lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each sentence adds necessary detail; no redundancy. The length is justified by the tool's complexity, but a slightly more condensed version could achieve clarity with fewer words.

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

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

Given no output schema and high complexity (multiple fan-out sources, resolver logic, safety checks, edge cases), the description comprehensively covers return structure (result.market, result.analysis, result.evidence), blocking paths, and resolution-rule risk. It also explains parent_event extraction and news error handling, leaving no critical 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?

With 100% schema coverage, the description adds significant value: explains depth enum ('quick' vs 'thorough'), market parameter accepts three types (slug, URL, question text), and include_raw parameter describes the trade-off (summarized vs full payloads) and when to pass true. Examples further clarify.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' with clear input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes itself from siblings by detailing the comprehensive fan-out and classification mechanism.

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

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

The description provides explicit usage cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes extensive fan-out examples for different bet types and safety checks (low-confidence, closed markets, wide spreads), guiding the agent on when and how to use the tool effectively.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: it explains data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. 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 efficient, front-loaded with example queries, and structured to quickly convey purpose and usage. It could be slightly trimmed (e.g., the fiscal year detail is useful but slightly verbose), but every sentence adds value. 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?

Given no output schema, the description adequately explains return values: paired data with citation URIs and sorted results. It covers both entity types comprehensively, including edge cases (off-calendar fiscal years). The tool is fully documented for an agent to use correctly.

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

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

Input schema covers both parameters with descriptions (type enum and values array with min/max). The description enhances this by clarifying the semantics: type='company' pulls financials with ticker/CIK examples, type='drug' pulls safety/trial data with drug name examples. It also explains the array constraints (2–5 items) and acceptable formats.

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 it performs side-by-side comparison of 2–5 entities (companies or drugs) using specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It distinguishes itself from sequential single-pack lookups, making the tool's purpose clear and unique.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example query patterns (e.g., 'X vs Y', 'which is bigger') and clarifies the behavior for 'largest' queries via sorting. This strongly helps the agent decide when to invoke this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context beyond those annotations: account and paid-plan requirements, explicit gaps[] with 'never invented', contradictions[] scanning, citation_uri fetchability semantics, semantic excerpting of large records, and expected latency. 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 information-dense and front-loads critical usage constraints, but it is long and contains a garbled output paragraph ('re-angled angles to answer a data-gap?') that undermines clarity. Some depth semantics are repeated from the schema, adding mild redundancy. Still, most sentences earn their place for a tool this complex.

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 return-format burden and does so well: it documents findings packet fields, gaps[], contradictions[], citation_uri, hop field, excerpting, and latency. The malformed output paragraph slightly obscures the second-packet behavior, but the overall picture is nearly complete for an agent to call 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%, but the description enriches both parameters. It explains depth's behavioral consequences in concrete terms ('quick=3 facets, single hop', 'standard=default; adds gap-recovery + contradictions[] scan', 'thorough=6 facets, paid') and clarifies that question accepts broad natural-language multi-part input and that decomposition is intentional. This goes well beyond the schema descriptions.

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

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

The description clearly identifies a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call — this is NOT open-web search.' It explains what the tool does internally (decompose, route, return findings packet) and distinguishes it from ask_pipeworx by scope. The 'Best for broad/multi-part questions' sentence further solidifies the purpose and differentiates it from siblings.

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

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

Usage guidance is explicit: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'For a single lookup use ask_pipeworx instead.' It also says the tool excels at broad/multi-part questions over structured data, giving an agent clear selection criteria versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is a useful behavioral trait. 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?

Two sentences: first states purpose and domains, second explains return value and usage guidance. Every sentence is substantive with no fluff. Front-loaded with key verb and resource.

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

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

No output schema, but description sufficiently explains what is returned (top-N tools, names, descriptions, full schemas with examples). It covers the input parameters, return format, and use case. Slight gap: does not mention if results include tool IDs or how to invoke them, but 'ready to call' implies schemas are sufficient.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds context about the query parameter accepting natural language and lists aliases (task, q, description, search). It enhances semantic understanding beyond the schema.

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

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

The description explicitly states the tool finds tools by describing the data or task, lists many domains, and explains it returns ready-to-call tools with schemas. This is unique among siblings (e.g., search_within, ask_pipeworx), which are not about tool discovery.

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 explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells when to use it and implies when not (if you already know 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?

The annotations only declare the safety profile (readOnly, idempotent, non-destructive); the description goes far beyond by disclosing operational behavior: the full source fan-out, the GDELT→GNews fallback, the USPTO PatentsView "soft-fails until reactivated" condition, and the key semantic that "an empty section is a real 'no data', not a bug." It also reveals resolution behavior (resolved_from/resolved_to, resolved:false with a notes line for private companies). No annotation contradiction exists.

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

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

The description is long, but the tool is complex (multi-source fan-out, no output schema) and every sentence carries information — there is no filler or fluff. It is front-loaded with example intents and the one-call value proposition before diving into sources and return fields. The structural weakness is that it is one dense, run-on paragraph with very long sentences; bullets or line breaks would improve scannability, though the signal density is appropriate for an agent.

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

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

There is no output schema, so the description carries the full burden of explaining return values — and it does: cik/company_name/resolved_*, recent_filings (up to 5 with pipeworx URIs), fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash), and sources_used/sources_failed with the meaning of empty sections. Edge cases (private companies, USPTO soft-fail, news fallback) are all covered, so an agent has no ambiguity that would require trial and error.

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% (both type and value are documented with examples), so the baseline is 3. The description adds meaning beyond the schema: explicit value formats ("AAPL", "0000320193", "Moderna"), the note that names resolve via SEC EDGAR company-name match, and the output consequences of resolution. The type-equivalence statement is redundant with the schema, but the resolution behavior genuinely extends parameter understanding.

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

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

The description opens with concrete user intents ("Tell me about X" / "research Acme" / "brief me on Tesla") and then states the essence precisely: "full cross-source profile of a US public company in ONE parallel call." It names the resource (US public company), the action (compose a cross-source profile), and the mechanism (parallel fan-out), and it differentiates from the chained-lookup alternative. An agent can immediately tell what this tool is for.

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

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

Routing guidance is explicit: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view" names the triggering condition, the preferred behavior, and the discouraged alternative in one sentence. The description also states which input shapes are accepted (ticker, zero-padded CIK, company name) and that private companies are handled gracefully rather than erroring, so the agent knows when this tool still applies.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about why to use the tool (e.g., clear sensitive data) without contradicting annotations. It does not elaborate on irreversibility, but the destructive hint covers that.

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

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

Two concise sentences: first states purpose, second provides usage guidelines and sibling context. No wasted words, 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 simple tool (one param, full schema coverage, annotations), the description covers what it does, when to use it, and related tools. It doesn't describe return value, but for a delete operation that is acceptable.

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

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

Input schema has 100% coverage with a clear description 'Memory key to delete'. The tool description does not add additional semantic information beyond the schema, 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?

Description clearly states 'Delete a previously stored memory by key', which is a specific verb+resource. It distinguishes from siblings like remember and recall by specifying the action of deletion.

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

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

Explicit usage conditions provided: 'Use when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with remember and recall, giving clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: auto-detection of seconds vs milliseconds by magnitude, override with 'unit', and the keyless/offline nature, which enhances understanding beyond annotations.

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

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

Three concise sentences front-load the core action and constraints. No redundant information; every sentence serves a purpose. Highly efficient.

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

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

The tool is simple with no output schema. The description covers input, auto-detection, and offline nature. However, the output format is only vaguely described as 'ISO-8601 UTC date + human forms' – could be more explicit about the exact return structure, but overall adequate for a straightforward conversion.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra meaning by explaining the auto-detection logic and override capability, complementing the schema without repeating it.

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

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

The description clearly states 'Convert a Unix timestamp to an ISO-8601 UTC date + human forms.' This specifies the verb (convert) and the resource (Unix timestamp to date/time), and distinguishes it from siblings like 'to_timestamp' (reverse) and 'relative_time' (relative time).

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 with 'Keyless, offline' suggesting it can be used without keys or network, but it does not explicitly state when to use over alternatives like 'to_timestamp' or 'relative_time'. Some context is provided but no direct when/when-not 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 indicate readOnly, idempotent, and not destructive. The description adds process details (fetches page, extracts title/description/links, emits markdown) that go beyond annotations without contradicting them.

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

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

The description is concise (~3 sentences), front-loaded with purpose, then process, then use cases. Every sentence 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?

Given only 2 parameters, no output schema, and thorough annotations, the description covers input, process, output format, and use cases sufficiently. The output is described as 'a single text blob ready to drop at site-root/llms.txt'.

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 parameters. The description mentions url and max_links implicitly but does not add new semantics 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 explicitly states 'Generate a production-ready llms.txt file' with a specific verb and resource, and differentiates from siblings like 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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

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

The description lists three explicit use cases (client site indexing, personal drafting, competitor auditing), providing good context. However, it does not mention when not to use this tool or suggest alternatives like scan_competitor_ai_presence.

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

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

Description adds details like returning specific fields and defaulting to active subscriptions, complementing annotations that already mark it as read-only, idempotent, and non-destructive; no contradiction.

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

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

Two concise sentences: first states purpose and return fields, second provides usage rationale; no wasted words.

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

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

For a simple list tool with rich annotations and no output schema, the description adequately covers purpose, return fields, and usage context; it is complete for effective agent use.

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

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

Schema coverage is 100% and the only parameter has a description in the schema; the tool description does not add parameter details beyond what the schema provides, meeting the baseline.

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

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

Clearly states verb 'List', resource 'subscriptions', scope 'caller's active', and lists returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool before adding more subscriptions or to find an id to cancel, providing clear usage context; no explicit alternatives but implied by sibling tools.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. Description adds valuable detail about output formats (ISO-8601, Unix timestamps). 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?

Single sentence with all essential information, no unnecessary words. Extremely concise 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?

No output schema, but description adequately explains return values (ISO-8601 and Unix timestamps). Minor gap: exact structure not specified, but acceptable for a simple 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?

No parameters. Schema coverage 100% is trivially true. Baseline for 0 parameters is 4; description adds no parameter info but doesn't need to.

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 returns current UTC time in ISO-8601 and Unix timestamp formats, distinguishing it from sibling conversion tools like 'from_timestamp' and 'to_timestamp'.

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 use when needing current time in specific formats, but lacks explicit when-not or alternatives. Context from siblings makes it clear, so still 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?

Discloses rate limiting ('5 per identifier per day'), no tool-call quota impact, return of a claim_token, and daily digest review. This goes beyond the annotations, which only set hints like readOnlyHint=false, giving the agent essential behavioral expectations.

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?

Although long, every sentence adds distinct value—scope, exclusions, message guidance, claim_token protocol, rate limits, and quota note. The structure front-loads the primary purpose and then layers use-case specifics, making it efficient for an agent to parse.

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

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

With no output schema, the description compensates by explaining what filing returns (claim_token) and how to read replies later. It covers all necessary context: what to report, how to report, exclusions, rate limits, and quota, making it fully self-sufficient.

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

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

The schema already documents all four parameters (100% coverage), and the description adds important usage context: how to pass claim_token back to read status, and guidance to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This elevates the parameter documentation 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?

Clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback about Pipeworx tools, with explicit scope limitation to tools served by this connection.

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

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

Provides explicit when-to-use conditions (bug, feature/data_gap, praise) and when-not-to-use (tools from other MCP servers, directing users to file with that server instead). Names the alternatives indirectly by exclusion, making the decision process 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 readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: caching behavior, data source (CF analytics-engine), and no PII.

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

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

Three focused sentences with no waste. Front-loaded with purpose, then usage contexts, then behavioral notes. Each sentence earns its place.

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

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

For a read-only info tool with no output schema, the description fully explains return content (top tools, packs, call volume), caching, and data source. No gaps given 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 description adds meaning beyond enum values: '24h surfaces what's hot right now; 7d/30d show steady-state demand'.

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

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

Clearly states it returns 'top tools, top packs, and total call volume' with time windows. Unambiguous verb and resource, distinct from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Explicitly describes three specific use cases and explains window trade-offs. Does not include when NOT to use, but guidance is clear enough for appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral context: the monotonicity checks, partition_sum logic, fill check against CLOB depth, semantic anchor, and partition filter. It fully discloses how results are generated and interpreted, far exceeding annotation coverage.

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

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

The description is well-structured, starting with the core purpose, then explaining modes, followed by details on semantic anchor, partition filter, and response format. It is dense but not verbose; every sentence adds value. The use of bold and structure aids readability.

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

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

Given the tool's complexity (multiple modes, fill check, semantic anchor, partition filter, no output schema), the description covers all necessary aspects: what it returns, how to interpret results, and when to avoid trades. It also references a sibling tool for deeper risk analysis, ensuring completeness.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning beyond the schema by explaining that 'event' accepts a Polymarket event slug or full URL, and 'topic' is a seed question for cross-event search. It also clarifies that no args triggers a trending scan, which the schema doesn't indicate. This enhances understanding.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three call modes (no args, event, topic) and explains each. However, it does not explicitly differentiate from sibling tools like polymarket_edges, which might overlap in function, and the uniqueness is implied rather than stated.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for per-event check, topic for cross-event scanning. It also advises when not to trade (realizable_edge_pp ≤ 0) and mentions using polymarket_fill_risk for custom sizing. This is comprehensive 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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant behavioral details: caching at 1h, diagnostic output like _diagnostics showing why segments are empty, tradeable-edge knobs affecting results, and segment-specific logic. 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 lengthy (multiple paragraphs) and includes detailed algorithmic explanations that are not essential for tool invocation. While front-loaded with purpose, it could be streamlined to focus on usage and key behaviors.

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

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

Despite no output schema, the description thoroughly explains return structure (by_segment, fed_candidates, _diagnostics), edge metrics (edge_pp_net, kelly_fraction), caching policy, and how knobs affect results. For a complex tool with 9 parameters, 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 provides additional context for some parameters (e.g., slippage_pp explains typical Polymarket spreads), but does not thoroughly enhance understanding of all 9 parameters 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on discovery without paging hundreds of markets.

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

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

The description provides context for when to use the tool (discovery) and mentions tradeable-edge knobs for filtering, but does not explicitly contrast with sibling tools or specify when not to use it. No exclusions or alternatives are named, leaving room for ambiguity.

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

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

Adds substantial behavioral detail beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). Discloses that it reads snapshots, computes time-series, provides trend/decay metrics, notes snapshot gaps, 60-day TTL bound, and that decay is based on daily closes, not intraday. No contradiction with annotations.

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

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

Front-loaded with key question, then details response structure, then limits. Well-organized but somewhat verbose; every sentence earns its place. Could be slightly tightened, but overall efficient.

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

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

Given two optional parameters, no output schema, and rich annotations, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) and their fields, plus limitations (TTL, snapshot gaps). Very 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% (both parameters described in schema). Description adds value by clarifying defaults (14 days, 1wk), clamp range (2-30), and window choices, thus providing meaning beyond the schema. However, the schema already covers the basics, so the added value is moderate.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Answers a specific question about how long an edge has existed and whether it is shrinking. Distinguishes from sibling tool polymarket_edges by focusing on time-series analysis rather than just snapshot data.

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

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

Explains when to use: to understand edge longevity, with example contrasting a fresh edge vs. a 3-week-old edge. Provides context but does not explicitly state when not to use or suggest alternative tools, though the context is sufficient for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it walks the order book, returns fill details and a verdict (clean|degraded|cannot_fill), and explains that it is a pre-trade validation, not execution. 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 detailed but well-structured with capital-letter cues for modes (SINGLE-MARKET, BASKET) and key warnings. It front-loads the purpose and usage guidance. Slightly dense but 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 the tool's complexity (two modes, 4 parameters, no output schema), the description thoroughly explains both modes, all return fields, and actionable usage context. It compensates for the lack of output schema by describing outputs like top_of_book, vwap_fill_price, verdict, etc.

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

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

Input schema has 100% coverage with descriptions, but the description adds mode-specific meaning (e.g., size_usd interpretation for single-market vs basket), defaults, and constraints (clamp 10–1,000,000). This enriches understanding beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between two modes (single-market and basket) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, which are trade execution signals.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains the risk of partial basket fills converting arb to unhedged directional position, providing clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true and no destructive effects, but the description goes far beyond that: it discloses fee treatment, gross spreads, unresolved matching, compatibility_codes, skipped legs, and the limitation that pre-mapped topics are often not tradeable. This is exceptionally transparent.

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

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

The description is long but densely packed and well-labeled, with mode, response, safety, fee, and limitation sections. It is not concise in raw length, but nearly every sentence adds necessary operational detail, so the length is justified.

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

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

Given there is no output schema and the tool has high operational complexity, the description is remarkably complete. It explains return fields, safety fields, matching pitfalls, fee implications, skipped comparison counters, and temporal alignment semantics — an agent has enough to call 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?

Schema coverage is 100%, yet the description adds crucial meaning: the topic mode versus explicit pairing mode, that explicit params override topic mappings, and that both modes share identical matching logic. This materially helps an agent choose and combine the three parameters 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 states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two-mode design and explicit mention of matched spreads distinguish it clearly from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description clearly explains when to use topic shortcuts versus explicit ticker/slug pairings, and emphasizes that both modes run the same matcher. It does not explicitly contrast this tool against sibling alternatives, but the context and mode guidance are strong enough for correct selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior; the description adds context about scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, enhancing transparency 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 concise (two sentences) with front-loaded core action, followed by usage guidance, scoping, and pairing details. Every sentence adds value without redundancy.

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

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

The description covers key aspects but lacks explicit mention of the return format (e.g., JSON structures) for both retrieval and listing. Given no output schema, a bit more detail would be beneficial.

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

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

With 100% schema coverage, the description still adds meaning by clarifying that omitting the key lists all keys, and explaining the purpose of keys (storing context like ticker, address, notes).

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 retrieves a value saved via 'remember' or lists all keys when no key argument is provided, clearly differentiating it from sibling tools 'remember' and 'forget'.

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

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

It provides explicit guidance on when to use the tool ('look up context stored earlier without re-deriving it') and implies when not to (use saving/deleting functions), with a clear scope of identifiers.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description transparently discloses that mark_read:true flags events as read (a state change). It adds context about behavior beyond annotations, though it does not cover rate limits or other potential traits.

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 efficient sentences plus a short note, front-loaded with the core action and key details. Every clause adds value with no repetition 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 has 5 optional parameters and no output schema, the description adequately covers return fields, filtering, marking read behavior, and an alternative access method. It is complete for the tool's complexity and context.

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 has 100% description coverage. The text enriches each parameter with context: type filter with example 'sec_8k', since as ISO timestamp, mark_read effect, and unread_only. This adds significant meaning beyond the schema's brief 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 specifies the verb 'Pull' and resource 'fired events from your subscription feed', and details the returned fields (source, citation_uri, raw event payload). It distinguishes clearly from sibling tools by focusing on alerts/subscription feed, with 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 provides explicit context: mentions polling works fine, gives an alternative HTTP endpoint for scripts/dashboards, and explains how mark_read affects subsequent calls. It does not explicitly state when not to use this tool, but the guidance is clear and helpful.

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, openWorld. The description adds detailed behavior: parallel call across multiple sources, fallback logic, soft-fail for USPTO, and output structure. 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?

Single paragraph but packed with information. Starts with usage examples, then functionality, fallback, parameter details, output format, and sibling guidance. Every sentence adds value; 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?

Despite no output schema, the description describes the return format (changes[] grouped by source + total_changes + citation URIs). Covers parallel execution, fallback, and parameter constraints. 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%. Description adds meaning: explains `since` accepts ISO or relative formats with examples, `value` can be ticker or CIK, recommends '30d' for monitoring. Provides usage advice 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 starts with concrete example queries ('What's new with X', 'latest on Y') and explicitly states it is a change feed for a company in a time window. It distinguishes itself from the sibling 'entity_profile' tool, which is for 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 clear when-to-use guidance via example queries. Explicitly states when to use `entity_profile` instead (for static profile). Explains fallback behavior between GDELT and GNews, and soft-fail for USPTO.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds 'keyless, offline', disclosing that no internet or API key is required. This is useful context beyond annotations.

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

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

The description is a single efficient sentence with a key phrase. It is front-loaded, contains no fluff, and every word contributes to understanding. Ideal conciseness.

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

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

For a simple tool with 2 well-documented parameters, no output schema, and comprehensive annotations, the description covers all necessary context: purpose, usage (examples), and behavior (keyless, offline). Complete and self-contained.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining the output format via examples and clarifying the default behavior for the 'from' parameter. This goes beyond the schema alone.

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

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

Description clearly states the tool humanizes a date/time relative to now or a given 'from', with examples like '2 hours ago' and 'in 3 days'. It also distinguishes itself by noting 'Keyless, offline', setting it apart from sibling tools like from_timestamp or deep_research.

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

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

The description implies usage for relative time strings but does not explicitly compare with alternatives or provide when-to-use/when-not-to-use guidance. Sibling tools like from_timestamp and to_timestamp have overlapping functionality, but no differentiation is offered.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds that memory is key-value scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. This adds useful context beyond annotations. However, it does not mention whether storing with an existing key overwrites or errors, which would be helpful.

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: first states core purpose, second provides usage guidance and storage details. Every sentence is informative and non-redundant. 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?

Given no output schema, the description does not explain the return value or confirm success. However, for a save operation, this is often acceptable. The description covers storage behavior, persistence, and pairing with other tools. Minor gap: no mention of overwrite semantics on duplicate keys.

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 has 100% description coverage for both parameters (key and value). The description's parameter examples ('subject_property', 'target_ticker', etc.) are helpful but largely redundant with the schema descriptions. Thus, the description adds limited semantic value 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 the verb 'save' and the resource 'data', specifying 'data the agent will need to reuse later'. It distinguishes from sibling tools 'recall' and 'forget' by mentioning them, 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?

Explicitly says when to use: 'when you discover something worth carrying forward' and provides examples like 'resolved ticker', 'target address', 'user preference'. It also tells to pair with 'recall' and 'forget' for retrieval and deletion, providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: graceful degradation (LEI/FIGI enrichment degrades, EDGAR identifiers still return), cascading internal lookups, and the fact that non-ticker instruments resolve. It doesn't fully detail rate limits or pagination, but for a read-only resolver this is strong context beyond annotations.

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

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

The description is long but densely informative, with front-loaded examples and clear scoping. Each sentence adds meaning, from supported types to degradation behavior to an explicit 'use FIRST' routing. Some redundancy exists with the schema's enum descriptions, but the additional guidance justifies the length.

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

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

Given the tool's complexity (multi-source resolution, multiple ID types, graceful degradation), the description covers what an agent needs to invoke it correctly: input formats, source coverage, fallbacks, and exclusions. No output schema exists, but the description names the outputs (CIK, ticker, LEI, FIGI, RxCUI, etc.), compensating for that absence.

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

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

Schema coverage is 100%, so the schema already documents both parameters, but the description goes far beyond the schema by explaining how to format the value, what entities are acceptable for each type, and what not to pass (e.g., trailing security-class words). The 'value' parameter gains substantial practical semantics from the description's examples and exclusionary guidance.

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

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

The description opens with concrete user-phrase examples and a clear verb 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools that work from IDs or profiles (e.g., compare_entities, entity_profile) by explicitly stating its role as the name-to-ID gateway. It also specifies supported types company and 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It also gives negative guidance ('never the question's full noun phrase') and details what resolves, including non-equity instruments, which prevents common agent errors. Naming alternatives is not required here because this tool is the canonical entry point for ID resolution.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds process details (probes each entity with ai_visibility_check, ranks, returns score/confidence/signal density) and mentions model/api key requirements. 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?

Two sentences, front-loaded with purpose, includes example question. No wasted words, perfectly sized.

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, description explains return format (ranked list with score, confidence, signal density). Covers purpose, parameters, output, and use case. Complete for tool complexity (4 params, no enums).

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. Description adds narrative meaning: entities 2-8 with first as subject, context disambiguates, and models/_apiKey tie to source. Adds value 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?

Clearly states the verb 'compare', resource 'AI visibility across entities', and distinguishes from sibling 'ai_visibility_check' by describing side-by-side ranking. Provides specific context for competitive audits.

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 describes when to use (competitive AI-marketing audits) and implies alternatives (single entity use ai_visibility_check). Gives example question and clarifies that first entity is the subject.

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 critical behavioral traits: partial failures gracefully degrade, bundlephobia's first measurement can take 5-30s, and the sources_failed field indicates timeouts. It also notes the tool is limited to the npm ecosystem in v1.

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

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

The description is a dense paragraph that front-loads the purpose and use cases, then lists return fields and notes. Every sentence adds value, but it could be slightly more structured (e.g., bullet points for return fields). Still, it is concise for the detail it provides.

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

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

With no output schema, the description thoroughly describes the return fields (summary block, per-advisory detail, links, alternative versions) and covers edge cases (partial failures, timing, ecosystem limitation). It provides complete context for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with both 'package' and 'version' having descriptions. The description does not add extra semantics beyond the schema, such as explaining how the parameters interact with the composite check. Baseline score of 3 is appropriate.

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

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

The description clearly states that the tool performs a composite check for deciding whether to add an npm package, fanning out to deps.dev and bundlephobia. It specifies the exact use case and distinguishes from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and provides an alternative for non-NPM ecosystems, giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already mark it as safe (readOnly, idempotent, non-destructive). Description adds critical behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This far exceeds the annotation baseline.

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

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

Four densely informative sentences, no redundancy. Front-loaded with purpose and use case. Every sentence serves a purpose: purpose, usage, technical detail, constraint.

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

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

Despite no output schema, the description explains return type (top-N passages with offsets and similarity scores) and provides embedding/windowing mechanics. Covers all likely agent questions. Complete for the task.

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

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

Schema covers 100% of parameters. Description enriches them: provides example queries for 'query', explains 'text' as document text, states default for 'limit' (5). Adds clarity beyond schema descriptions.

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

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

Clearly states semantic search inside a fetched record with concrete examples (SEC 10-K, article, tool result). The name and description together unambiguously distinguish it from other tools like ask_pipeworx_grounded.

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

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

Explicitly says when to use: when the record is too large for the prompt. Mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but implies it for small texts. Strong guidance overall.

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

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

Adds value beyond annotations: requires OAuth, returns new id, details delivery channel behaviors (SMS cap, webhook secret one-time, auto-disable after failures). No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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?

Moderately long but well-structured and front-loaded: purpose, requirements, then types, then delivery. Every sentence adds value, though could be slightly more compact. No waste.

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

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

Covers all important aspects: type-specific params with examples, delivery constraints, account requirement. No output schema, but mentions return of subscription id and webhook secret. Adequate 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%, but description adds significant context: JSON examples for each type, detailed constraint explanations for delivery fields (e.g., phone verification, 10/day cap, webhook HMAC signing). Goes well beyond schema descriptions.

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

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

Description uses a specific verb-resource pair ('Create a proactive monitoring subscription') and states it returns a subscription id. Clearly distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Explicitly states the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist. Provides detailed type-specific parameters and delivery options. Does not explicitly say when not to use, but implied by alternatives in sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds context by explaining that the tool returns example questions and tool shapes without side effects. It does not contradict annotations, but could mention more about scope (e.g., that it draws from a live catalog) – still strong.

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

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

The description is moderately long but front-loaded with purpose. It lists categories twice (once in text and again implicitly in parameter description), which is slightly redundant. However, it is well-structured and each part serves a purpose. Could be trimmed slightly, but not excessive.

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

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

Given no output schema, the description adequately explains what is returned (category-bucketed example questions with tool+argument shapes). It covers the single optional parameter, provides examples, and gives usage context. For a simple onboarding tool, this is fully 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 repeats the topic parameter values and adds examples, but does not provide significant new meaning beyond the schema description. The schema already lists the possible values with similar detail.

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 that this tool returns category-bucketed example questions for onboarding, lists the categories, and mentions that it provides exact tool+argument shapes. It also explicitly positions itself as the first tool to use when the agent doesn't know Pipeworx's capabilities, indirectly distinguishing it from sibling tools like ask_pipeworx.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains call patterns (no arguments vs. topic parameter) and the purpose of each variant. This clearly tells the agent when and how 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 provide strong safety signals (readOnly, idempotent). The description adds meaningful behavioral context ('keyless, offline') beyond the annotations, but does not detail edge cases or limitations. This is good but not exhaustive.

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

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

The description is extremely concise—two short sentences—with no filler. It front-loads the core action and outcome, making it efficient for agents to parse.

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, no output schema, and no nested objects, the description covers all essential information: input format, output format, and operational characteristics. No gaps are present.

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

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

Schema coverage is 100% with a clear description of the 'date' parameter. The description adds value by specifying 'ISO-8601 (or other parseable)', indicating flexibility beyond the schema's example, which enhances understanding.

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

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

The description uses a specific verb ('Convert'), names the input ('ISO-8601 or other parseable date string'), and clearly states the output ('Unix timestamp with seconds and milliseconds'). It also distinguishes itself by noting 'Keyless, offline', which sets it apart from siblings like 'from_timestamp'.

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 implicitly guides usage by stating 'Keyless, offline', indicating it works without authentication or network. However, it does not explicitly contrast with similar tools (e.g., from_timestamp) or provide when-not-to-use scenarios.

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

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

Adds key behavioral detail beyond annotations: row is deactivated not deleted, historical events remain. Aligns with idempotentHint=true and destructiveHint=false.

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 core action, no wasted words. 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?

Given the tool's simplicity (1 param, no output schema, clear annotations), the description fully covers purpose, constraints, and behavioral nuance.

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 description 'Subscription id (uuid) returned by subscribe.' The description adds no extra meaning beyond the schema, meeting the baseline for high coverage.

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

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

Clearly states the verb 'cancel' and resource 'subscription by id'. Differentiates from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement (only own subscriptions). Provides context for when to use, though does not explicitly mention alternatives or when not to use.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description explains critical failure semantics: 'could_not_verify' means the check did not happen and must not be used as evidence, while 'unsupported' means no source exists. It also discloses the automatic fallback pipeline and the returned verdict/citation/reasoning structure.

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

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

The description is fairly long (~180 words) but information-dense. The opening list of example phrasings could be trimmed, yet the crucial caller guidance about 'could_not_verify' and the pipeline routing justifies the length. It is front-loaded with the purpose and examples.

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 enumerating the verdict options and explaining ambiguous results. It also describes the two data paths and the replacement of multiple sequential calls, giving the agent a full picture of the tool's behavior and output.

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

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

The input schema already provides 100% coverage with clear descriptions for 'claim' and 'tolerance_pct'. The description does not add extra parameter-level detail; it only mentions 'natural-language claim' which mirrors the schema. Thus 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 clearly states the tool's function with a specific verb ('verify') and resource ('natural-language claim'), and includes multiple usage examples like 'fact check' and 'confirm or refute'. It also differentiates the tool by noting it replaces 4–6 sequential calls, distinguishing it from simpler query tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', giving clear when-to-use guidance. It also describes the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for other claims), though it does not explicitly name alternative tools to avoid.

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