Wikiquote

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the default model, BYO key requirement, and return structure ({score, confidence, signals, raw_response}). 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 three sentences, front-loaded with the main action, and every sentence adds value. No fluff or redundancy.

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

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

With no output schema, the description adequately describes return structure (per-model + combined). It covers parameters, behavior, and output. Could mention rate limits or cost implications but not necessary for 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 description coverage is 100%, baseline 3. The description adds meaning: explains how to omit models for default, the purpose of _apiKey (passed through to Anthropic), and context for disambiguation. This exceeds baseline.

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

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

The description clearly states the tool probes LLMs and scores visibility (0-100) per model, with specific examples. It does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', but the action is distinct enough.

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 provide explicit when-to-use vs alternatives or exclusions. Sibling tools exist but no guidance on choosing.

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 readOnly, openWorld, idempotent, and non-destructive behavior, so the description adds useful operational context: it routes to the right tool, fills arguments, and returns structured answers with pipeworx:// citations. It also discloses a 'too short answer' failure mode and advises rephrasing. No contradiction with annotations, though it doesn't discuss failures, rate limits, or edge-case behavior.

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

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

The description is long but front-loaded with the key routing directive ('PREFER OVER WEB SEARCH') and structured with examples, a routing decision list, and a closing practicality note. It earns its length given the many sibling tools, though the routing list is somewhat repetitive and could be tightened.

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

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

With no output schema, the description still explains the return format: 'structured answer with stable pipeworx:// citation URIs.' It covers main use cases, examples, alternatives, and one failure/rephrase guidance. It is nearly complete, but it does not explicitly distinguish ask_pipeworx_beta or explain what happens when no source matches the question.

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%: the only required parameter, question, is described as a natural-language request, and the five other parameters are explicitly documented as aliases. The description adds minimal parameter-level guidance, but the schema already carries the full semantic burden, so baseline 3 is appropriate.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and clearly states what the tool does: routes the question across 5,798 tools from 1,517 verified sources and returns structured answers with stable pipeworx:// citation URIs. It lists concrete domains and examples, so an agent can easily distinguish this from sibling search and research tools.

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

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

Gives explicit selection criteria: use it for factual questions involving 'what is', 'look up', 'find', 'get the latest', 'how much', or 'current', and says 'START HERE for most questions.' It also names alternatives such as ask_pipeworx_grounded, search, deep_research, compare_entities, resolve_entity, and web-search with the conditions under which they should be preferred.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: the tool is experimental, routing improvements are only live when being tested, no candidate is active right now, and it is a fully functional router rather than a fallback 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?

The description is somewhat long but each clause serves a purpose: explaining beta status, the identical interface, the active-candidate behavior, and the current no-candidate state. Key information is front-loaded, and the tone is direct, though the repeated emphasis on sameness could be trimmed slightly.

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

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

Given no output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It covers current behavior, experimental status, usage guidance, and the comparison process, making it complete for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100% and every parameter is described as an alias for 'question' in the schema itself. The description adds no new parameter-level detail, only confirming that arguments are identical to ask_pipeworx, which is useful but not necessary given the complete schema coverage.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It explicitly differentiates itself from the stable ask_pipeworx and the grounded sibling by describing its experimental role and current behavior.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and it contrasts with the stable router by noting that results are compared to decide merges. It also clarifies that with no active candidate it currently matches ask_pipeworx exactly, giving clear guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), and the description adds substantial behavioral context on top: the exact success payload ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the full enumerated refusal_reason values, the constraint that answers are extracted ONLY from tool results, and the cost trade-off. The description also states a key behavioral trait — explicit refusal instead of guessing — which is critical for an agent deciding whether to trust the output. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and the return contract appears early, before usage guidance. It is longer than average, but every sentence earns its place: there is no output schema, so the success/refusal formats must be documented in prose. The density of detail (routing mechanism, both payload shapes, cost warning) is justified, though the specific counts '5,798 across 1517 sources' add minor bulk.

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

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

Given the tool has only one real parameter, rich annotations, and no output schema, the description fully compensates for the missing output schema by specifying both the success shape and the refusal shape with enumerated reason codes. It covers cost, usage context, sibling differentiation, and behavioral guarantees. Nothing an agent needs to decide whether to call this tool and to interpret its result is missing.

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

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

Schema description coverage is 100% — the single meaningful parameter 'question' is fully documented in the schema including alias handling (query, q, prompt, text, input). The description adds contextual value by explaining that the question gets routed to auto-fill arguments across 5,798 tools, but it doesn't add parameter-level detail beyond that. Baseline 3 is appropriate since the schema carries the parametric documentation burden.

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

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

The description opens with a specific purpose — 'Hallucination-resistant answer mode for high-stakes reads' — pairing a precise verb+resource with a clear scope. It distinguishes itself from the sibling ask_pipeworx by describing the grounded extraction mechanism and the structured success/refusal output. An agent can immediately tell what this tool does and how it differs from the plain ask_pipeworx sibling.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete example domains (financial verdicts, legal claims, medical lookups, public statements). It also states the when-not-to-use condition directly: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' naming the alternative and the deciding factor.

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

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

The description discloses extensive behavioral details beyond annotations: resolution contract (market_match_confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread market warnings, and resolution-rule risk (cancellation rule analysis). This fully compensates for the lack of output schema and adds significant value.

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

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

The description is very long and dense, with many examples and edge cases. It is well-structured with sections (classifiers, fan-out examples, response shapes, etc.), but could be more concise. The length may hinder quick parsing by 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?

Given the tool's complexity (3 params, no output schema), the description covers inputs, expected outputs, edge cases (low-confidence, closed markets, wide spreads), resolution rules, and safety mechanisms. It is comprehensive and leaves little ambiguity.

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

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

Although schema coverage is 100%, the description adds critical context: 'market' can be slug, URL, or question text; 'depth' defaults to thorough; 'include_raw' explains default false and when to set true. This meaningfully extends the schema definitions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output structure (evidence packet + market-vs-model comparison). This distinguishes it from siblings like 'polymarket_edges' or 'deep_research' which likely have different scopes.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples. It does not explicitly state when not to use, but given the specificity, it is clear enough 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, open-world, idempotent, and non-destructive. The description adds extra behavioral context: it pulls from SEC EDGAR/XBRL for companies and FAERS for drugs, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. 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 front-loaded with the essential purpose and trigger phrases, then provides concise details. Every sentence adds unique value; there is no redundancy or fluff. It is efficient despite its length.

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

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

There is no output schema, but the description explains the output format (paired data + citation URIs) and sorting behavior. It does not mention error conditions or rate limits, but annotations cover safety. For a tool replacing many lookups, the context is sufficient.

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

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

Schema coverage is 100% and describes type and values clearly. The description adds meaning by explaining what each type pulls (e.g., latest 10-K data for companies, adverse-event counts for drugs), enhancing the schema's context. It doesn't just repeat schema info.

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 natural language trigger phrases and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sequential lookups and specifies what each entity type returns, making the tool's purpose 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. However, it does not explicitly mention alternatives like 'entity_profile' for single entity lookups, which would strengthen the guidance further.

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 far beyond the readOnly/idempotent annotations: it discloses the grounded data universe, parallel facet routing, gaps[] for unanswerable facets, 'never invented', contradiction[] behavior, semantic excerpting, and latency expectations. No statement conflicts 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?

Long, but organized and front-loaded: account gate first, core capability second, then examples, alternatives, and detailed return/latency behavior. Minor redundancy with the depth schema, but every sentence contributes actionable context; not quite the two-sentence ideal.

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

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

With no output schema, the description compensates by specifying the findings packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], citation_uri behavior, and latency. It covers prerequisites, alternatives, expected outputs, and limitations, so an agent can decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already carries the parameter load for `question` and `depth`. The description adds useful examples of multi-part questions and ties paid gating/iteration to depth, but this is mostly reinforcement rather than new parameter 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?

States exactly what it does: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, with decomposition and parallel routing. It also differentiates itself from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx as the single-lookup alternative. Clear verb+resource+scope.

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 conditions use: signed-in required, use ask_pipeworx if not signed in, best for broad/multi-part structured-data questions, and 'For a single lookup use ask_pipeworx instead.' This gives the agent both positive and negative selection criteria.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that each result is ready to call directly with full schemas and curated examples, which is consistent and adds value 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?

Two sentences, front-loaded with purpose then usage guidance. Could be more structured but 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 no output schema, the description explains what the output contains (tools with names, descriptions, schemas, examples). It covers the complexity of discovery and provides context for the limit parameter.

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% (baseline 3). The description adds context: query is a natural language description, and provides examples. It also notes aliases, which are already in schema, but the extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains it returns top-N relevant tools with full schemas, distinguishing it from siblings like 'search'.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies 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 readOnly/openWorld/idempotent annotations, the description discloses important behaviors: an empty section is a 'real no data, not a bug', USPTO patents 'soft-fails until reactivated', fda_products may legitimately be empty for small-molecule companies, and private companies return resolved:false with notes. It also explains sources_used/sources_failed, which enriches the agent's understanding of partial results.

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

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

The description is long but front-loaded with examples and the core guidance. Each sentence conveys functional information, such as source fan-out, empty-section semantics, and fallback behavior, so there is little fluff. It could be tightened by trimming the example list, but the density justifies 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?

The description fully covers the tool's complexity: all fanned-out sources, the shape of key return sections, how to interpret empty results, fallback behavior, input resolution, and private-company handling. Since there is no output schema, the description must carry the burden of explaining return semantics, and it does so thoroughly.

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

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

While the input schema covers both parameters, the description adds meaning beyond it: it clarifies that type is effectively a no-op ('company or ticker interchangeably') and that value may be a ticker, zero-padded CIK, or plain company name resolved via SEC EDGAR. This reduces ambiguity and helps the agent format inputs correctly.

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

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

The description opens with concrete example queries and states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from the alternative of chaining single-pack SEC/XBRL/news lookups, instantiated by the 'ALWAYS PREFER' directive. The resource and scope are unmistakable.

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

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

The description explicitly states when to use the tool: 'when the user asks for a holistic view' and instructs to 'ALWAYS PREFER over chaining single-pack lookups.' It also specifies the acceptable input forms (ticker, CIK, company name) and what happens for private companies, giving the agent clear decision criteria.

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

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

Description confirms delete operation, aligning with destructiveHint=true. Adds context about clearing sensitive data, 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?

Two focused sentences with action verb upfront, minimal and complete.

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?

Sufficient for a simple delete operation: one required param, no output schema needed, guidelines provided.

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

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

Schema already covers the single parameter 'key' with description 'Memory key to delete'. Description adds no additional semantic value.

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

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

Explicit verb 'Delete' and resource 'memory' with 'by key' clarifying scope. Mentions sibling tools 'remember' and 'recall', distinguishing its purpose.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Names alternatives to pair with (remember, recall).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds behavioral steps: HTTP fetch, extraction of metadata, and standard format emission. It does not contradict annotations and usefully enriches the agent's understanding of what happens.

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

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

The description is three dense sentences with no filler. The first sentence states the core action, the second summarizes the workflow, and the third lists explicit use cases. Every sentence adds value, and the structure is front-loaded.

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

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

No output schema exists, but the description explains the output is a 'single text blob in standard llms.txt markdown format.' For a simple tool generating a well-known format, this is sufficient. It does not discuss errors, rate limits, or page size limits, but the annotations provide safety 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 description coverage is 100%, so baseline is 3. The description provides additional context: 'Full URL of the site to summarize' clarifies the scope, and mention of 'key links' connects to the max_links purpose. It does not add syntax details but gives usage motivation 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 uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource ('llms.txt file') and scope ('for any URL'). It distinguishes from siblings by focusing on a unique output format and use case (AI indexing), which is not shared by nearby 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 lists three concrete use cases (client site indexing, personal projects, competitor auditing). While it does not state when to avoid using the tool, the sibling list is large and the tool's purpose is narrow enough that the intended context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds return fields and the effect of the include_inactive parameter, but does not add behavioral context beyond what annotations and schema provide.

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 defines purpose and output, second provides usage context. No unnecessary words, perfectly front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description sufficiently covers what the tool does, what it returns, and when to use it. Minor absence of mention about scoping or limitations.

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 baseline is 3. Description does not add new semantics for the include_inactive parameter beyond its schema description.

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

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

Description uses specific verb 'List' and resource 'caller's active subscriptions', and lists return fields. It clearly distinguishes from sibling tools subscribe and unsubscribe by stating it's for reviewing existing subscriptions.

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

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

Description explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. There is no 'when not to' but the context is clear given 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?

Discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact, and return behavior ('Filing without an account returns a claim_token'). Annotations are all false, so description carries the full burden, and it meets it thoroughly with operational and post-submission details.

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

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

The description is long but every sentence adds crucial operational detail — scope boundaries, claim_token flow, rate limits, and roadmap impact. The opening sentence front-loads the purpose; no wasted words or redundancy.

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

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

For a 4-param tool with no output schema and all-false annotations, the description covers purpose, usage scenarios, scope restrictions, follow-up mechanism, and operational constraints. It sufficiently prepares an agent to invoke the tool correctly and understand the expected flow.

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

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

Schema already has 100% coverage with descriptions for all parameters. Description adds real-world context to `type`, `context`, and `claim_token` — e.g., explaining the claim_token round-trip process and the precise content expectations for `message`. This enriches the schema's bare descriptions, but a bit more on the exact format of `context` could be added.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings like ask_pipeworx and discover_tools by focusing on reporting bugs, features, data gaps, and praise. The title also reinforces the purpose.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Provides exclusions: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' Also instructs on content guidelines: 'don't paste the end-user's prompt.'

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 hints. Description adds value: self-aggregating signal from CF analytics, no PII, caching details (5min-1h). 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?

Description is a single paragraph, front-loaded with main output, then use cases listed with numbers, ending with caching details. Every sentence contributes 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?

Tool is simple (1 optional param, no output schema). Description covers return values, use cases, caching, and data source. Lacks output format details but adequate given no output schema.

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

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

Schema coverage 100% with window enum and description. Baseline 3. Description adds minimal extra meaning beyond schema (window length implications). Does not significantly enhance parameter understanding.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a window. The verb 'returns' and resource are specific. It distinguishes from siblings by focusing on AI agent call patterns, unique among listed 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 enumerates three explicit use cases (discovering hot data, confirming canonical tool, checking alignment). It also explains window implication (short for hot, long for steady-state). Does not mention when not to use, but scenarios cover most needs.

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

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

The description discloses extensive behavioral details beyond annotations: partition check logic (sum of YES prices ≈1, thresholds), semantic anchor for cross-event, partition filter for placeholders, and fill check against live CLOB depth. All annotations (readOnlyHint, etc.) are respected and not contradicted.

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

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

The description is dense but well-structured, front-loading the core purpose and modes. It is longer than typical but every sentence adds necessary behavioral context for a complex arbitrage tool. Minor redundancy (e.g., 'trending_scan' clarified twice) prevents a perfect score.

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 complex tool with two modes and no output schema, the description thoroughly explains response structure (opportunities[], partition_check, fill check fields) and edge cases (cross-event similarity, placeholder filtering). It leaves no critical gaps for an agent to interpret the 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?

Schema coverage is 100% with both parameters described. The description adds significant meaning: what a slug looks like ('fed-decision-may-2026'), that full URLs are accepted for event, and how the topic parameter triggers cross-event scanning with example seed questions.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_fill_risk by specifying that it scans for arbitrage, while others handle custom sizing or edge tracking. The three modes (no args, event, topic) are explicitly described.

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: no args for trending scan, event for single-market analysis, topic for cross-event scanning. It recommends 'event' for specific markets and warns not to trade when fill check shows negative realizable edge. Alternatives like polymarket_fill_risk are mentioned for custom sizing.

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 goes well beyond by detailing caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge computation (net of slippage, 24h-move warning), and model families. There is no contradiction with annotations.

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

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

The description is information-dense and front-loads the purpose, but it is very verbose, with detailed model explanations (e.g., lognormal barrier, GDELT ratios) that may overwhelm agents. While well-structured into segments and knobs, it would benefit from tighter prose. A 'less is more' approach could improve clarity.

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

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

Given the tool's complexity (9 parameters, 3 segments, no output schema), the description is remarkably complete. It explains response shape (top-level fields, diagnostics), caching, edge cases (empty segments, Fed bets), and knob interactions. It compensates for lack of output schema by detailing the return structure thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value for every parameter: explains defaults (e.g., limit=10, window='1wk'), provides context (slippage_pp explains Polymarket fees and suggests adjustments), and clarifies edge cases (min_partition_leg_kelly explains why min_kelly doesn't filter partitions). This far exceeds 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 states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific use case ('what should I bet on today') and distinguishes from siblings by detailing three unique response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) not present in related tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (to discover opportunities without paging hundreds of markets) and provides guidance on knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly. It notes that Fed bets are excluded from ranking and why. However, it does not explicitly state when to use sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which would improve clarity.

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. Description adds rich behavioral context: response structure (tracked, expired, snapshot_dates), decay computation details, meaning of signs in edge_pp_net, data gap handling, and TTL limits. No contradiction found.

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

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

Well-structured with a clear central question, then explains response fields and limits. Front-loaded with key purpose. Somewhat verbose but each sentence adds value.

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

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

Despite no output schema, the description thoroughly explains all three response arrays and their contents, including edge cases like gaps and TTL. Sufficient for understanding 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?

Schema coverage is 100% with descriptions for both parameters. Description adds default values and clarifies clamp range for days. While helpful, it doesn't add substantial meaning beyond what's in the schema.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Answers the core question 'how long has this edge existed and is it shrinking?'. However, it doesn't explicitly differentiate from sibling tool polymarket_edges, though it implies being an analytical layer.

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 context about when to use (comparing fresh vs. old edges). Mentions limits (60-day TTL, snapshot start date). But lacks explicit guidance on when not to use or alternatives to consider.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: walks the ladder, returns specific fields, basket fill risks (thin_legs, forced_directional_risk), and warns about partial fills converting arb into unhedged directional position. No contradiction with annotations.

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

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

The description is well-structured with mode sections (SINGLE-MARKET, BASKET) and front-loads the core purpose. While it is relatively long, every sentence adds value given the tool's complexity. Minor room for tightening, 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?

No output schema exists, so the description bears the full burden of explaining return values. It thoroughly describes both modes' outputs (top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, realizable_sum, profit_usd, per-leg detail for basket) and covers edge cases like thin_legs and forced_directional_risk. Complete for a tool of this 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% (each parameter has a description). The description adds meaning beyond the schema: e.g., size_usd is explained as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional — shares per leg' for basket; side default behavior is explained. It adds context without redundancy.

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

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

The description states the tool's purpose clearly: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly tells the agent to use this before polymarket_arbitrage or polymarket_edges, differentiating 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?

The description explicitly says when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills convert arb to directional) and provides prerequisites ('REQUIRES one of market or event').

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 the tool as read-only, idempotent, and non-destructive. The description adds substantial behavior: it discloses that Kalshi fees are not modeled and spreads are gross, lists all compatibility codes and their meanings, explains when pairs are skipped or unverified, and details the temporal alignment field semantics. It goes far beyond the annotation safety profile.

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 structured with clear caps-lock section labels (TWO MODES, RESPONSE, SAFETY FIELDS, etc.) and front-loads the core purpose. Every sentence adds necessary detail for a complex tool, though a few sections (e.g., the full code list) could arguably be trimmed for brevity without losing critical guidance.

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

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

Given three parameters, no output schema, and two modes, the description covers everything an agent needs: response structure, safety fields, compatibility codes, fee disclaimer, skipped-pair counters, and temporal alignment semantics. It even warns about the rarity of real spreads. No critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches each parameter: it enumerates the exact allowed topic shortcuts, explains that explicit override topic mapping, and clarifies that both modes run the same overlap matcher. It also clarifies that 'null in temporal_alignment' means uncomputed, not aligned. This adds meaning beyond the schema's plain 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 opening sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates from siblings by focusing on cross-venue spread rather than single-venue edges or arbitrage. The two explicit modes and the macro-shortcut list further specify scope.

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

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

The description explains when to use each mode (topic vs explicit ticker/slug) and warns that pre-mapped topics often return compatibility warnings, implying they may not be tradeable. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges, leaving some selection inference to the agent.

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

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

Adds context beyond annotations: explains the source (English Wikiquote) and locale behavior for non-English 'lang' values. 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 sentence with no fluff. Key information front-loaded: 'Daily featured quote' with parenthetical detail about locale.

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?

Sufficient given simplicity (1 optional param, read-only, output schema exists). Could mention return format but output schema handles that.

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

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

Only parameter 'lang' is not described in schema (0% coverage). Description explains its effect with an example ('lang=fr returns locale equivalent'), adding necessary meaning.

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

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

Clearly states it returns a daily featured quote from English Wikiquote with optional language override. Not explicitly differentiating from sibling 'quotes' but the 'daily featured' and locale behavior provide distinction.

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?

Implies usage for fetching a daily quote in a specific locale, but lacks when-not-to-use or comparison to sibling 'quotes'. No alternative suggestions.

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, covering the safety profile. The description adds the note that quotes are 'sourced', but no additional behavioral traits beyond what annotations provide.

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 front-loaded sentence with no wasted words, effectively communicating the core function.

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 presence of an output schema and annotations, the description is adequate but lacks context about the source (e.g., Wikipedia) and how to use the parameters effectively. Not fully complete for a tool with three parameters.

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 only 33% (only 'limit' has a description). The description does not explain the 'lang' or 'title' parameters, leaving their semantics unclear. With low coverage, the description should compensate but fails to do so.

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 'Extract' and the resource 'sourced quotation items from a page', which is specific and distinguishes this tool from the sibling 'quote_of_the_day' that likely returns a single quote.

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 no guidance on when to use this tool versus alternatives like 'quote_of_the_day' or other research tools. No explicit context for usage.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by explaining scoping to identifier and listing behavior (omit 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?

Two clear, front-loaded sentences with no wasted words. Each sentence serves a purpose: action, context, scope, pairing.

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 parameters and good annotations, the description covers behavior and context well. Could mention error handling for missing keys, but not essential.

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 for the key parameter. Description reinforces and elaborates on listing behavior and provides example use cases, adding value beyond the schema.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all keys. It uses specific verbs and distinguishes from sibling tools like 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?

Provides clear guidance on when to use (to look up stored context without re-deriving) and mentions pairing with remember and forget. While it doesn't explicitly state when not to use, the context is sufficient.

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 contradicts annotations: annotations declare readOnlyHint=true, but the description states that setting mark_read:true flags events as read, which modifies state. This is a major inconsistency. Additionally, no other behavioral traits beyond what annotations provide are disclosed.

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

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

The description is four sentences, front-loaded with the core purpose, followed by return field details, filtering/mark_read behavior, and a note about polling. 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?

Without an output schema, the description adequately explains return fields (source, citation_uri, payload) and key behaviors (filters, mark_read). However, it does not mention the limit parameter's effect, though the schema covers it. The contradiction with annotations reduces 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% (baseline 3). The description adds value by explaining the effect of mark_read (flags events as read), mentioning the 'pipeworx://' format for citation_uri, and clarifying that type and since are filters. This goes 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 states the tool pulls fired events from the subscription feed, returns recent alerts, and specifies available fields (source, citation_uri, raw event payload). It distinguishes from siblings like list_subscriptions by focusing on the alert feed rather than subscription management.

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 that polling works fine and points to an alternative endpoint (alerts.json) for scripts and dashboards. It also explains when to use mark_read. However, it does not explicitly state when not to use this tool or compare it to related tools like recent_changes.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: parallel fan-out to multiple sources, fallback logic, output structure (changes[] grouped by source, total_changes, citation URIs), and soft-fail for USPTO. 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 detailed but efficient, front-loading examples and purpose. Every sentence contributes meaningful information. Slightly verbose in parts (e.g., repeating fallback details) but still concise overall.

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 structure (changes[] grouped by source, total_changes, citation URIs). It covers input, behavior, output, fallbacks, and sibling distinction comprehensively. No gaps.

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

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

Input schema has 100% description coverage for 3 parameters. The description adds value: for 'since', it explains accepted formats and gives monitoring recommendation; for 'type', it notes only 'company' supported; for 'value', it clarifies ticker or CIK. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the verb (provide change feed), resource (company), and scope (time window). It explicitly distinguishes from sibling tool entity_profile, stating when to use which.

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: lists example queries ('What's new with X', 'latest on Y'), explains input formats (ISO date or relative shorthand), recommends '30d' or '1m' for typical monitoring, and directs users to entity_profile for static profiles. It also details fallback behavior for GDELT→GNews and USPTO soft-fail.

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 idempotent, non-read-only, non-destructive. Description adds critical behavioral context: storage scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) sessions. 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?

Three sentences, front-loaded with purpose, then usage, then storage details. Every sentence adds value with no redundancy. 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?

Given the simple tool (2 params, no output schema) and comprehensive annotations, the description fully covers all necessary context: what to store, when, how storage works, and relationship to sibling tools. No gaps.

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

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

Schema coverage is 100% with descriptions for both key and value. Description adds value beyond schema by providing concrete example keys (e.g., 'subject_property', 'target_ticker') and explaining the purpose of storing any text, which helps the agent understand parameter usage. Baseline 3 is elevated because description enriches parameter context.

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 saves data for reuse across conversations or sessions, and explicitly distinguishes it from sibling tools recall and forget. The verb 'save' with resource 'data' and scope 'across conversations or sessions' is specific and unambiguous.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward'. Also mentions when not to use by suggesting alternatives: 'Pair with recall to retrieve later, forget to delete.' This covers both usage context and exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important behavior: it cascades through multiple endpoints, asserts nothing on ambiguous matches and returns figi_candidates, reports unresolved identifiers explicitly instead of omitting them, and degrades gracefully when GLEIF/OpenFIGI are unavailable. This is substantive behavioral disclosure, not a restatement of 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 material is front-loaded with examples and the 'Use FIRST' directive, and it is structured by SUPPORTED TYPES. It is long and dense with parentheticals, but nearly every sentence carries an edge-case or behavioral fact needed to use a complex resolver correctly.

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 still explains what a caller should expect: labels and sources on identifiers, an unresolved field, figi_candidates for ambiguous matches, and degradation behavior. For both supported types it states the inputs and returned identifier concepts, which is enough to invoke and interpret the tool correctly.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds value by expanding accepted company inputs to include ISIN (not listed in the value schema), clarifying that bond lookups require the issuer name only, and mapping drug input to RxNorm concepts. This goes beyond the schema's basic type/value descriptions.

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

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

The description opens with concrete natural-language queries and states the function precisely: resolve a user-spoken name to canonical/official identifiers other tools require as input. It names the supported entity types (company, drug) and the specific identifier sets returned, making it clearly distinct from generic search or entity-profile tools.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces multiple manual lookups and covers cases like non-US issuers where EDGAR cannot reach. It does not name sibling alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density per entity. 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?

Four sentences with front-loaded purpose. Each sentence adds unique value: purpose, method, use case, output. No redundant or extraneous content.

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

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

No output schema, but description lists return fields (score, confidence, signal density) and explains the process. Could mention the entity count constraint (2-8) explicitly, but overall complete for the 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 description coverage is 100%, so baseline is 3. Description does not add new parameter information beyond the schema; it mentions the 'entities' parameter contextually but does not elaborate on optional params like models, _apiKey, or context.

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 verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes itself from sibling ai_visibility_check by focusing on side-by-side comparison of multiple entities, and gives a concrete use case example.

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 context for use in competitive AI-marketing audits with an example question. Implies it is intended for multi-entity comparison versus single-entity check (ai_visibility_check), though does not explicitly state 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?

Describes the fan-out across multiple sources, return structure (summary block, per-advisory detail, links, alternative versions), and graceful degradation when sources fail. This adds substantial behavioral context beyond annotations, which only indicate readOnly, openWorld, idempotent, and non-destructive hints.

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

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

The description is well-structured, front-loading the main purpose and then detailing sources, return values, and edge cases. While slightly verbose, every sentence adds value, and the bullet-like listing 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?

Covers return structure in detail (summary block, per-advisory detail, links, alternative versions), ecosystem limitations (NPM only in v1), and partial failure behavior with sources_failed. No output schema exists, so description fully compensates.

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 extra context for both parameters: notes scoped packages accepted for 'package', and default behavior for 'version' (latest). This enhances understanding 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 states it's a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size metrics. It uses a specific verb (scan) and resource (dependency), and distinguishes itself from siblings by explicitly limiting to NPM ecosystem.

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

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

Provides explicit when-to-use criteria ('is X safe / popular / small' or 'what does adding lodash cost me'), notes NPM-only scope in v1, and advises on partial failures and timing (bundlephobia first measurement delay). This gives clear context for selection and expectations.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows it is safe. The description adds the specific scope (Wikiquote, title+fulltext) but does not elaborate on behavior like pagination, response format, or any constraints. It is adequate but minimal.

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 sentence that conveys the core functionality without fluff. It is front-loaded and efficient. However, it could benefit from additional context without becoming verbose.

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

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

While the output schema exists and annotations provide safety, the description fails to explain parameter usage or when to employ this tool. The contextual completeness is low, as the agent remains underinformed about how to construct queries or how results are scoped.

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

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

With only 33% schema description coverage, the description should clarify the missing parameter semantics for 'query' and 'lang'. It does not: the tool description only states it searches, without explaining what 'query' expects or what 'lang' does. This leaves the agent without necessary parameter 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 clearly identifies the tool as performing searches on Wikiquote, covering both titles and fulltext. However, it does not explicitly differentiate from sibling tools like 'search_within' or 'quotes', which might have overlapping functionality. The purpose is well understood but not contrasted.

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 no guidance on when to use this tool versus its siblings such as 'search_within' or 'quotes'. It lacks explicit context or exclusion criteria, leaving the agent to guess the appropriate use case.

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 safe, read-only, idempotent behavior. Description adds valuable context: truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping), cosine similarity, and offsets. No contradiction with annotations.

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

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

Three sentences: first states core purpose, second provides usage context and alternatives, third gives technical details. No filler. Every sentence is essential and informative.

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

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

Even without output schema, description explains return format (passages with offsets and similarity scores). Covers limitations (200K char cap, truncated flag). For a tool with moderate complexity, this is complete and 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%, so baseline is 3. Description adds value with natural-language query examples and clarifies the output includes offsets and similarity scores. Goes beyond the schema by explaining the embedding approach.

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 performs semantic search inside a fetched record. Uses specific verb ('search within'), identifies the resource ('a fetched record'), and provides concrete examples (SEC 10-K, article). Distinguishes from sibling 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 big to cram into the prompt'. Mentions alternative sibling (ask_pipeworx_grounded) and gives a pairing strategy. Provides clear context for decision-making.

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

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

Annotations include readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds context about authentication requirements, the creation of persistent subscriptions, details on delivery channel behavior (always-on feed, optional email/sms/webhook with limits like SMS 10/day and webhook auto-disable after 10 consecutive failures), and the return of a new subscription ID. It does not contradict any annotations.

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

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

The description is relatively long but well-structured: it front-loads the core purpose, then details types and delivery channels in separate sections. Every sentence serves a purpose (examples, requirements, constraints). A slight trim could improve conciseness, but overall it is appropriately sized and organized.

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 3 parameters with nested objects and no output schema, the description is highly complete: it covers parameter details comprehensively, specifies the return value (new subscription ID), explains side effects (persistent subscription), and outlines limitations (auth requirements, SMS cap, webhook auto-disable). No obvious gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: for 'type', it explains each enum value with real-world examples (e.g., 'sec_8k' items codes); for 'params', it provides detailed JSON examples for each type; for 'delivery', it explains verification steps, limits, and webhook signing details. This greatly aids correct parameter construction.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb 'create' and the resource 'subscription', and distinguishes from siblings 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?

The description provides explicit guidance: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), lists supported types with examples, explains delivery channels, and mentions limitations like SMS cap and webhook auto-disable. However, it does not explicitly state when not to use this tool (e.g., for viewing alerts, use recent_alerts).

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. The description adds that it returns questions with tool+argument shape from a live catalog, and how to use the topic parameter. 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 somewhat long but front-loaded with the core purpose. Every sentence adds value, listing categories and usage variants. Could be more concise but is well-structured.

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

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

Given no output schema, the description fully explains return values (category-bucketed example questions with tool+argument shapes). Parameter coverage is complete. It covers all needed context for an onboarding tool.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema: it explains that omitting topic gives full spread, while passing a topic focuses the output, with examples. 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 that the tool returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the onboarding 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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments or a topic to focus. It implies when to use and provides context for 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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. However, the description adds no additional behavioral context, such as what 'summary' entails or any side effects. With annotations covering the basics, a 2 reflects the lack of value added.

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 only two words, which is underspecified rather than efficiently concise. It fails to convey essential information and does not earn its place.

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

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

Given the presence of an output schema, the description should still explain the tool's behavior. It does not mention return values, scope, or anything beyond 'Page summary,' making it inadequate for an agent to understand what the tool does.

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 0%, meaning no parameter descriptions exist in the schema. The description does not explain the 'title' (required) or 'lang' parameters, leaving their purpose ambiguous.

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 'Page summary.' is vague and does not specify what the tool does beyond a generic term. It fails to distinguish from sibling tools like 'entity_profile' or 'deep_research', which likely also provide summaries in some form.

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

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

No guidance is provided on when to use this tool versus alternatives. There are many sibling tools, and the description offers no context for selection.

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

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

The description adds critical behavioral context beyond annotations: ownership enforcement and deactivation (not deletion). Annotations indicate non-destructive and idempotent, which align 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?

Two sentences, front-loaded with the core purpose, then constraints. Every sentence adds value with 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?

Given one parameter, no output schema, and clear annotations, the description fully covers behavior, constraints, and side effects. References 'recent_alerts' for historical 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?

The schema already fully describes the single parameter 'id' with 100% coverage. The description does not add additional semantic value beyond the schema's description.

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

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

The description clearly states the verb ('Cancel') and resource ('subscription'), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description explains ownership enforcement (you can only cancel your own) and the deactivation behavior (not deleted, historical events stay). This gives context for when to use this tool, though it doesn't explicitly state when not to use or compare to all siblings.

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: it discloses the routing logic, the return format (verdict types, citation, reasoning), and critically distinguishes 'could_not_verify' (internal failure, not evidence) from 'unsupported' (no source). Adds context about the verification_error structure and warns callers how to interpret results, which is vital for safe usage.

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

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

The description is long but densely packed with valuable information. It uses a clear structure: examples, purpose, routing logic, return values, and important caveats. While the opening list of paraphrases could be condensed, every subsequent sentence contributes unique meaning, making the length acceptable for a complex tool.

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

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

Despite no output schema, the description fully explains the return value (verdict enum, evidence, citation, reasoning), the failure semantics, and the routing. It also covers the tool's efficiency benefit. Given the tool's complexity, this description is exceptionally complete and leaves little ambiguity.

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

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

The input schema already provides 100% coverage for both parameters, including a detailed explanation of tolerance_pct. The description itself doesn't add parameter-specific details except implicitly through the pipeline description. Since schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description gives a specific verb+resource: verifies natural-language claims against authoritative sources. It lists example phrasings and returns a verdict, clearly distinguishing it from generic search or ask tools. It also explains the composite nature (replaces 4–6 sequential calls), which clarifies its role among 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). However, it does not name specific alternative tools to avoid, relying on context, so it misses some explicit exclusion guidance.

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