Owid

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

Beyond annotations (readOnly, idempotent), the description discloses external API calls to Anthropic when key is provided, cost implications, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 concise sentences front-loaded with the core action and followed by important details. No fluff; every sentence serves a purpose.

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

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

For a 4-param tool with no output schema, the description covers purpose, default behavior, optional extensions, return format, and use cases. Lacks exhaustive detail on signals/confidence but is sufficient for an AI agent to understand the tool.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the default model, the role of _apiKey for Anthropic, and the context parameter's purpose for disambiguation, going beyond the schema.

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

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

The description clearly states the verb ('Probe'), resource ('LLMs'), and output ('score visibility 0-100'). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing specifically on LLM knowledge about a brand/topic.

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 context: default free model, optional Anthropic with BYO key, and use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). Lacks explicit when-not-to-use or alternatives among siblings, but 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context beyond annotations by explaining that the tool routes to 5,635 tools across 1,477 sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict annotations and provides useful behavioral context about the routing and citation mechanisms, though it does not mention rate limits or auth (minor gap).

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 instruction ('PREFER OVER WEB SEARCH') and each sentence serves a purpose: scope, examples, alternatives, and entry-tier guidance. There is minor redundancy between 'PREFER OVER WEB SEARCH' and 'START HERE', but overall it is tightly organized and earns its length for a default entry-point 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?

Given the tool's complexity (routing to many sub-tools), the description is remarkably complete: it states what the tool does, when to use it, what it returns (structured answer with citation URIs), and when to escalate to alternatives. It also mentions it works on every tier and is fast. No essential information for an agent to invoke it correctly is missing.

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

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

Schema description coverage is 100%: all six parameters are aliases for 'question' and are documented in the schema. The description merely repeats that the parameter is a natural-language question, adding no new semantics beyond the schema. Since the schema already fully documents the parameters, the baseline of 3 is appropriate.

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

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

The description clearly states that this tool answers factual questions about real-world entities, events, or numbers, and specifically lists domains (SEC, FDA, FRED, patents, etc.). It also distinguishes itself from siblings by mentioning it routes to thousands of tools and returns structured answers with citation URIs, so an agent can easily tell it apart from ask_pipeworx_grounded and deep_research.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and gives explicit conditions: 'Use whenever the user asks...' with examples. It also provides explicit when-not-to-use guidance by naming alternatives (ask_pipeworx_grounded for grounded answers, deep_research for broad multi-part questions) and says 'START HERE for most questions'. This is exceptionally clear and leaves no ambiguity about choosing this tool over 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?

The description adds valuable context beyond the annotations: it is an experimental edge, may have candidate routing improvements enabled live, and currently matches the stable router. It clarifies that it is a full working router, not a fallback. It does not contradict the readOnlyHint, openWorldHint, or idempotentHint annotations, and the safety profile is consistent.

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 every sentence earns its place: it defines the beta status, notes the current state, gives usage direction, and clarifies it is a real router. Information is front-loaded (beta, identity, current state) before the usage note. It avoids redundancy and 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?

For a complex routing tool with no output schema, the description covers the essential: experimental nature, current parity with stable, usage context, and confirmation it is a full router. It references the sibling for response shape, which is acceptable. It does not detail output behavior, but the reference to ask_pipeworx and the universal router pattern suffice.

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

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

Schema description coverage is 100% — all parameters (question and aliases) already have clear descriptions in the schema. The tool description adds no new meaning about parameters, only mentioning they are the same as ask_pipeworx, which is not essential. Baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that forwards to 5,635 tools. It explicitly distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded, and explains its experimental edge. The verb 'ask' and resource 'router' are clear, and the mention of being identical to ask_pipeworx when no candidate is active differentiates it from siblings.

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

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

It provides explicit guidance: use it like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router for merging decisions. It does not explicitly state when NOT to use it (e.g., for production stability), but the beta framing implies it. The advice is clear enough for an agent to choose it for experimental routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond by disclosing the refusal mechanism with specific refusal_reason values, the evidence requirement (verbatim quote), and the strict 'use ONLY what the tool result contains' extraction behavior. It also notes the extra LLM call cost, which is not in annotations. There is no contradiction with annotations; instead, it enriches behavioral understanding.

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

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

The description is well-structured and front-loaded: it opens with the core purpose, then explains the mechanism, then lists the exact return format and refusal reasons, and finally gives usage guidance and cost trade-off. Every sentence adds necessary information with no filler. It is appropriately detailed 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 having no output schema, the description fully specifies the return object and refusal reasons, so an agent knows exactly what to expect. Combined with the annotations covering safety, the description covers all needed call context: routing, extraction constraints, usage scenarios, cost, and failure modes. Nothing critical is missing for correct invocation.

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

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

The schema description coverage is 100%, and the description does not need to add parameter syntax. The description does explain that the question is routed through tools, but this is behavioral context rather than parameter semantics. Since the schema fully documents the question field and its aliases, a baseline of 3 is appropriate; the description adds minimal extra parameter-level meaning.

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

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

The description states a specific verb and resource: it is a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly differentiates itself from the sibling ask_pipeworx by explaining that it adds extraction and refusal behavior. The purpose is unambiguous and distinguishes it from other tools.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete example domains. It also states when not to use it: 'prefer ask_pipeworx for casual lookups' and discloses the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'). This is clear, actionable usage direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the tool is safe. The description adds extensive behavioral details: it resolves markets, classifies bets, fans out to category-specific data packs, and handles edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. It also explains the resolver contract and response shapes, providing full transparency.

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

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

The description is long but front-loaded with the core purpose. It packs a lot of necessary detail due to the tool's complexity and lack of output schema. While verbose, every part adds value for the agent (e.g., resolver contract, cancellation risk, news fields). It could be more concise if output schema were present, but given the constraints, it earns a 4.

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

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

Given the tool's complexity (3 parameters, classifiers, fan-out logic, multiple response fields, edge cases) and absence of output schema, the description is remarkably complete. It covers all states: low-confidence resolution, closed markets, wide spreads, cancellation rules, and fallback behavior for news sources. An agent can accurately judge when and how to use 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%, but the description adds significant meaning beyond the schema. It explains input formats for 'market' (slug, URL, question text), the depth parameter (quick vs thorough with concrete examples), and include_raw with trade-offs in response size. The description also uses examples and classifiers to clarify parameter usage.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data retrieval and analysis for a single bet.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear context, though it does not explicitly state when not to use it or mention alternatives. The presence of many sibling tools implies differentiation, but exclusionary guidance is absent.

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 significant behavioral traits: it makes one parallel call, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This adds rich context beyond annotations (readOnlyHint, openWorldHint, idempotentHint). No contradictions.

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

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

The description is concise (around 8 sentences), front-loaded with purpose and usage triggers, and every sentence adds value. No redundant or filler content.

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

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

With 2 required parameters and no output schema, the description covers key aspects: data sources, sorting, and return format (paired data + citations). It could specify the output structure more, but it is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning by explaining that type='company' pulls specific financial data from SEC EDGAR/XBRL and type='drug' pulls FAERS, FDA, and trial data. It also provides example inputs for values. This enhances 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 explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides synonyms such as 'X vs Y' and 'which is bigger,' and distinguishes from sibling tools like entity_profile by emphasizing preference over sequential lookups.

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

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

The description gives clear when-to-use guidance with examples and explicitly advises to prefer this tool over sequential single-pack lookups. However, it does not mention when not to use it or alternative tools beyond the sequential lookup, missing some nuance.

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 carry readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial context beyond these: auth requirements per depth tier, parallel routing to 5,635 tools, gap[] reporting with truthful non-invention of answers, contradictions[] in standard/thorough, semantic excerpting rather than head-truncation, the resolvable citation_uri guarantee, and runtime expectations (15-90s). This is a rich behavioral profile well beyond what annotations declare, with no contradictions.

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

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

The description is long, but every sentence carries dense, actionable guidance — the auth requirement and fallback are front-loaded, and the flow moves logically from identity to behavior to depth modes to timing. It earns its length given the tool's complexity, though it is not a model of brevity and could have been 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?

There is no output schema, so the description must carry return-value explanation — and it does: findings packet contents (verbatim evidence, confidence, source, fetched_at), gaps[], contradictions[], hop field, and citation_uri. Combined with no-output-schema and 2 well-documented parameters, everything an agent needs to invoke and interpret deep_research correctly is present. Complete.

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

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

Schema coverage is 100% and the schema already documents depth with its own detailed semantics (quick=3 single hop, standard=3 with gap-recovery + contradictions, thorough=6 paid). The description adds complementary value by framing the 'second-hop iteration' concept and clarifying that standard re-angles gaps while thorough chases leads — this reinforces but goes slightly beyond the schema. Question semantics are well covered by the schema ('Broad/multi-part is fine — decomposition is the point').

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

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

The description states a specific verb and resource ('Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources') and explicitly differentiates itself from open-web search ('this is NOT open-web search'). It names what it is best for ('broad/multi-part questions over structured data') and contrasts with siblings like ask_pipeworx and discover_tools. An agent can unambiguously tell what this tool does and when it applies.

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 with named alternatives and exclusion conditions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx — it routes to live news APIs', and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' It also states a negative case (deep_research returns mostly empty gaps[] for news topics). Nothing is left to inference.

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, non-destructive, idempotent. Description adds behavioral details: returns top-N most relevant tools with names, schemas, and examples, ready to call directly. 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?

Description is a single paragraph but efficiently conveys purpose, domains, return value, and usage advice. All sentences are substantive; no filler. Slightly long but still concise for the information density.

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 what the tool returns (top-N tools with names, descriptions, full input schemas, examples) and how it's intended to be used. Meets completeness needs for a discovery 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 covers 100% of parameters with descriptions. The description mentions query and limit but does not add new semantic info beyond what's already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes it from sibling tools by positioning it as a discovery tool to be called first. The verb 'discover' and resource 'tools' are specific.

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: 'browse, search, look up, or discover what tools exist', and instructs to call it first when many tools are available. Provides examples. Does not explicitly mention when not to use, but the context is clear.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields, notes the patent sunset (soft-fail until reactivated), and mentions it executes in one parallel call. No contradictions with annotations.

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

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

The description is front-loaded with example trigger phrases and structured into clear sections: input spec, preferred use case, data sources, and return fields. While slightly lengthy, every sentence adds value, and the structure aids readability.

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

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

Given the tool's complexity (multi-source, no output schema), the description covers key return fields (cik, filings, fundamentals, patents, news, LEI) and notes the patent limitation. It does not discuss error handling but is sufficiently complete for an agent to understand 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 descriptions. The description adds clarification on parameter values: ticker vs zero-padded CIK, and that names are not supported. This adds meaningful guidance beyond the schema's basic 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: a full cross-source profile of a US public company. It uses specific verbs and resources (fans out across SEC EDGAR, XBRL, etc.) and lists example queries. However, it does not explicitly differentiate from sibling tools like deep_research or compare_entities, though it implies priority over chaining individual lookups.

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

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

The description provides explicit guidance on when to use this tool ('holistic view') and when not to use it ('names not supported'), including an alternative (resolve_entity). It clearly states the input format (ticker or zero-padded CIK) and that names require prior resolution.

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

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

Annotations already provide safety profile (readOnly, openWorld, idempotent). Description adds detailed output format (rows of entity, year, value) and filtering capabilities, which is valuable 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?

Single paragraph that front-loads purpose, then provides usage guidance, examples, output format, and filtering—all in a compact, well-organized manner with no wasted words.

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

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

Given the presence of an output schema (as indicated), the description covers all necessary aspects: purpose, usage guidance, parameter explanation, output structure, and where to find allowed slugs. It is complete for agent decision-making.

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

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

Schema coverage is 100%, but description enriches parameter meaning by specifying that 'country' accepts name or ISO code, and giving concrete slug examples like 'life-expectancy'. This adds significant value 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 fetches tidy long-format data for an OWID indicator by slug, with examples and output format. It distinguishes itself from web search for deep-historical data, making its purpose distinct from sibling tools like get_indicator_metadata.

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 recommends use over web search for deep-historical data, provides examples of when to use (pre-1960 history, specific queries), and directs users to browse slugs at ourworldindata.org/charts. This gives clear context and alternatives.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so the description adds context about clearing stale/sensitive data. It does not contradict annotations and adds value by explaining why to use it, though no additional behavioral details like auth or side effects are given.

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

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

Two sentences, front-loaded with the action and usage context, no wasted words. Perfectly concise for a simple 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?

Given a single required parameter, no output schema, and informative annotations, the description is complete. It covers purpose, usage, and relationship to sibling tools without missing necessary details.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description repeats 'by key' without adding new meaning beyond what the schema provides, so it meets baseline but adds no extra value.

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

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

The description clearly states 'Delete a previously stored memory by key' using a specific verb and resource. It also distinguishes itself from siblings 'remember' and 'recall' by suggesting pairing with them.

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

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

The description provides explicit usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and mentions pairing with alternative tools, giving clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds process details (fetch, extract, emit) and output format, providing context beyond annotations.

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

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

Three sentences, front-loaded with purpose, then process and output. No wasted words. 'Useful for' section provides context 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?

Covers purpose, process, output format, and use cases. Missing details about error handling or more precise output structure, but annotations already cover safety and idempotency.

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 'url' and 'max_links'. Description adds minimal extra meaning (e.g., 'Fetches the page' implies url is used for fetching). 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?

Specific verb 'Generate', resource 'llms.txt file for any URL'. Clearly describes what it does and distinguishes from siblings, which are mostly unrelated.

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

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

Explicitly lists use cases (client indexing, own project, competitor audit). No exclusions given, but sibling list shows no direct alternative for this task.

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 idempotent, read-only, non-destructive. Description adds value by detailing return fields and usage context without contradicting annotations.

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

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

Two clear sentences: first lists return fields, second provides usage guidance. No extraneous information.

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

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

Given simple parameter, existing output schema, and annotations, the description sufficiently covers purpose, usage, and return structure.

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 slug with schema description 'OWID chart slug'; description says 'OWID indicator slug' which is nearly identical. Schema coverage is 100%, so description adds minimal additional 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 describes fetching chart metadata for an OWID indicator slug, listing specific fields (title, subtitle, note, per-column details) and distinguishes from sibling fetch_indicator.

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 to confirm a slug is valid and learn its units before calling fetch_indicator', providing clear context and alternative.

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. The description adds that the tool returns slug+title, is curated, and not exhaustive, providing useful behavioral context beyond annotations.

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

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

The description is two concise sentences. The first clearly states the action and content, while the second adds nuance and cross-reference. No unnecessary words.

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

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

Given it is a simple list tool with an output schema, the description covers purpose, output details, limitations (not exhaustive), and how to use with another tool. It is complete and actionable.

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 and an enum parameter, the description adds minimal extra meaning—only listing example categories that match the enum. Baseline of 3 is appropriate as the schema already documents the parameter fully.

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

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

The description clearly states the verb 'List' and the resource 'curated Our World in Data indicators'. It specifies the output (slug + title) and common categories, effectively distinguishing it from siblings like fetch_indicator or get_indicator_metadata.

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

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

The description provides context on when to use: for common categories and long-run coverage. It also directs users to visit the website for full catalog and mentions using the slug with fetch_indicator. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by noting that only active subscriptions are returned by default and that include_inactive can include cancelled ones, which is useful behavioral context beyond the 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?

Two concise sentences that front-load the primary action and key fields, with no wasted words. Every sentence adds value.

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

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

Despite no output schema, the description explicitly lists the return fields. The single optional parameter is simple. The tool is straightforward and the description fully covers its functionality and usage 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 coverage is 100% (1 parameter fully described). The description does not add additional meaning beyond the schema for the parameter; it merely reiterates the default behavior. A score of 3 is appropriate as per the rubric.

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

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

The description clearly states the verb ('List') and resource ('the caller's active subscriptions'), specifies return fields (id, type, etc.), and distinguishes from siblings like subscribe/unsubscribe by focusing on review and retrieval.

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

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

The explicit phrase 'Use this to review what you're monitoring before adding more or to find an id to cancel' provides clear context for when to use the tool, though it does not identify specific alternatives beyond the named 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?

Annotations are all false, so they provide little safety/side-effect information. The description compensates richly by disclosing the claim_token return, the ability to read resolution later via the same tool, a rate limit of 5/day, free usage with no quota, and guidance to avoid pasting end-user prompts. No contradiction with annotations.

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

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

The description is long but well-structured and every sentence contributes essential operational details (scope restriction, token round-trip, rate limit, quota). It is front-loaded with the core purpose and organizes related guidance logically. Slightly verbose but not wasteful.

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

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

For a tool with four parameters, a nested context object, and no output schema, the description fully covers purpose, usage, constraints, token-based follow-up, and rate limiting. It gives an agent enough to decide when and how to invoke it correctly.

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

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

Schema coverage is 100% and each parameter has detailed descriptions. The description reinforces the claim_token workflow (passing it back later) and the context object, which matches the schema. It adds minimal new semantic value beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by specifying when it should be used and explicitly scoping to Pipeworx-served 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 provides explicit when-to-use cases (bug, feature, data_gap, praise) and a clear when-not-to-use case (other MCP servers). It also includes a 'Not sure?' fallback, giving the agent practical 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?

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and no PII, which are valuable beyond annotations.

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

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

Description is a single paragraph with front-loaded output summary. Every sentence adds value, though it could be slightly more concise by merging some points.

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 one optional parameter, full schema coverage, and robust annotations, the description covers caching, data source, use cases, and return structure (pack, tool, count). 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 provides enum for window with basic description. Description adds meaning: 'shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing agent 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, top packs, and total call volume' over a specific window, differentiating it from siblings like discover_tools or list_popular_indicators by focusing on trending agent usage.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). No explicit when-not-to-use or alternatives, but the context is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. Description adds algorithmic details (Jaccard similarity threshold, placeholder filter, CLOB depth fill check) and explains conditions for null arb signals and when to avoid trading.

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

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

Front-loaded with core purpose, then organizes by mode. Every sentence adds unique value—no wasted words. Despite length, it remains efficient and well-structured.

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

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

Covers all modes, response fields, and fill check caveat. Lacks exact field names for all returned objects but provides enough for an AI agent to understand usage. Minor gap offsets otherwise thorough coverage.

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

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

Schema coverage is 100% but description adds substantial meaning: explains that event walks child markets and checks ordering, topic searches related events. Also details semantic anchor and partition filter, which are not in the schema.

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

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

The description starts with a clear verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and explains each, differentiating from sibling tools like polymarket_fill_risk.

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

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

Explicit instructions: 'Call with NO args for a trending_scan', 'pass event for a specific market', 'topic for cross-event scan'. Recommends event mode and warns against trading when fill check gives non-positive edge, directing to polymarket_fill_risk 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds detailed behavioral context: caching strategy ('Cached 1h at the KV level'), edge calculation (edge_pp_net after slippage), Kelly fractions, 24h move warning, and response structure (by_segment with diagnostics). 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?

Description is long but well-structured with clear sections (main purpose, model families, response layout, knobs). Every sentence adds value for a complex tool. Could be slightly more concise but front-loads key purpose and use case.

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

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

Given the complexity (9 parameters, 3 model families, edge calculation, response diagnostics), the description is extremely thorough. It explains the math behind edges, response fields (by_segment, fed_note, diagnostics), and how to interpret empty segments. No output schema, but response structure is clearly described.

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

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

Schema coverage is 100% with detailed parameter descriptions. The main description adds extra value by grouping knobs under 'TRADEABLE-EDGE KNOBS' and explaining interactions (e.g., min_kelly vs min_partition_leg_kelly), which goes beyond schema documentation.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx-based edge detection.

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 'Built for what should I bet on today', explains when to use each knob (e.g., min_liquidity for thin books), notes Fed bets are excluded from ranking, and explains diagnostics for empty segments. Provides clear alternatives implicitly via 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?

Description goes far beyond annotations, detailing internal behavior: snapshot TTL, cache-miss gaps, decay computation from daily closes, and the exact structure of response fields (tracked, expired, snapshot_dates).

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 dense but well-structured: purpose, args, response breakdown, limitations. Every sentence adds value; could be slightly tighter but is well-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 no output schema, description fully documents response structure and semantics. All critical aspects (purpose, inputs, outputs, limitations) are covered, making the tool self-contained.

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

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

Schema coverage is 100%; description adds practical context like defaults and clamp range for 'days', and clarifies 'window' as snapshot family, reinforcing schema without redundancy.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and its trend. It distinguishes between fresh and old edges, which is a specific use case beyond what sibling tools like polymarket_edges likely offer.

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 implies when to use by explaining the value of knowing edge age and decay, but doesn't explicitly compare to siblings. It provides defaults and limits, aiding usage decisions.

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 (readOnlyHint, openWorldHint, idempotentHint) correctly mark it as non-destructive and safe. The description adds rich detail: walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, verdict, per-leg fill detail, thin_legs[], forced_directional_risk. It explains the dominant loss mode (partial basket fills). 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?

Well-structured with bold headings (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Information is front-loaded and logically organized. A bit lengthy but justified by complexity; every sentence adds value. Could be slightly more terse but still effective.

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, so description fully covers return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket). Addresses edge cases, risk, and scaling. Complete for a tool with 4 params and two modes.

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). Description adds beyond schema: explains meanings of 'side' with defaults and auto-mode for baskets, defines 'size_usd' as settlement notional for baskets with clamp range, and clarifies that 'market' and 'event' are mutually required. Adds context not in schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific inputs and outputs. It uses specific verbs ('check', 'walks the ladder') and resources ('market', 'event'), making the purpose unambiguous.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns against partial fills converting arb into directional positions, providing clear when-to-use and when-to-avoid guidance relative to sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, non-destructive analysis tool. The description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, top spreads, safety fields), compatibility warnings with two cases, temporal alignment, and counters for dropped comparisons. 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 relatively long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. While every sentence adds value, some sentences are dense and could be split for readability (e.g., the compatibility warning explanation). Minor conciseness improvement possible.

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 100% schema coverage, no output schema, and rich annotations, the description compensates by explaining the output indirectly (leg-by-leg prices, top spreads in pp, safety fields). It covers temporal alignment and compatibility warnings. However, a structured output schema would further reduce 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 has 100% coverage with descriptions for each parameter. The description adds significant value beyond the schema: explains the two operational modes, how the topic parameter maps to pre-macro shortcuts, how explicit parameters override, and provides examples. This helps the agent understand parameter interactions and valid values.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage, polymarket_edges, etc., by focusing on inter-venue comparison rather than intra-venue opportunities. Two modes (topic shortcuts and explicit pairings) 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 on when to use the tool (e.g., same question on both venues) and when not (e.g., compatibility_warning cases like non-equivalent bet shapes or unrelated events). It warns that most pre-mapped topics return compatibility warnings, managing expectations. Although it doesn't name alternative tools, the context signals and sibling list are available.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping (anonymous IP, key hash, account ID) but mostly aligns 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?

Two clear, front-loaded sentences with no wasted words.

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

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

For a simple lookup tool with 1 optional param and no output schema, description covers usage, scoping, and pairing. Could mention return format but schema covers enough.

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

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

Schema has 100% coverage, description adds nuance: omitting key lists all, gives examples of key types (ticker, address, notes).

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

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

Description clearly states it retrieves values saved via 'remember' or lists all keys, distinguishing from siblings '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?

Explicitly says when to use (look up stored context, avoid re-deriving), pairs with remember/forget, but doesn't mention when not to use or alternatives among 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by explaining the return fields (source, citation_uri, raw payload) and the mark_read behavior that affects subsequent calls. 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 concise with four sentences, front-loading the purpose. It efficiently covers key behavioral details and an alternative access method. Minor redundancy (mentioning 'persisted feed' twice) but overall 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 the tool has 5 optional parameters and no output schema, the description provides sufficient context: it mentions return fields, filter options, mark_read behavior, and alternative access. Annotations cover safety and idempotency. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with each parameter described. The description enhances understanding by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and the use of ISO timestamps for since, going beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('pull') and resource ('fired events from your subscription feed'), clearly stating what the tool does. It distinguishes from siblings by focusing on recent alerts from a persisted feed, unlike 'list_subscriptions' or 'recent_changes'.

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 polling works fine and provides an alternative URL for scripts/dashboards, giving context for when to use this tool versus other methods. However, it does not explicitly state when not to use it or contrast with sibling tools for reading 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?

The description discloses all major behaviors: parallel call, source fan-out, fallback logic, USPTO sunset status, and return structure (structured changes[] grouped by source, total_changes count, citation URIs). Annotations (readOnly, idempotent, non-destructive) are consistent and enhanced by these 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 information-dense and front-loaded with example queries, but the single paragraph could be more structured (e.g., bullet points for sources). Every sentence adds value; no redundancy.

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

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

The description covers input, sources, fallback, alternatives, and return format mentions, but lacks detailed output schema fields (e.g., exact properties of changes[]). Given complexity and no output schema, it is largely 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?

With 100% schema coverage, the description adds meaningful context: explains 'since' formats with examples ('30d' for typical monitoring), clarifies 'value' accepts ticker or CIK, and confirms 'type' only supports 'company.' This goes beyond the schema to guide correct usage.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' with example queries like 'What's new with X.' It clearly distinguishes from the sibling 'entity_profile' by specifying when to use the alternative.

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 (monitoring recent changes) and when not to (static profile: 'Use entity_profile instead'). It details the sources (SEC EDGAR, GDELT→GNews, USPTO with soft-fail), parameter formats (ISO date or relative shorthand), and fallback behavior.

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 discloses storage as key-value pair scoped by identifier, different persistence (authenticated vs. anonymous), and pairing with recall/forget. Annotations show idempotentHint=true and destructiveHint=false, which are consistent—no contradiction. Description adds valuable behavioral context beyond annotations.

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

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

5 sentences, each earning its place: purpose, usage guidance, storage details, scope/persistence, and references to sibling tools. Front-loaded with key action and examples.

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

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

Fully covers what the tool does, when to use, what it stores, scope, persistence, and relationships to recall/forget. No missing context for a simple 2-parameter tool without 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 is 100% with each parameter described (key as memory key, value as any text). Description adds naming conventions (e.g., 'subject_property') and clarifies value can be findings, addresses, preferences, notes—extending meaning beyond schema.

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

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

Description starts with 'Save data the agent will need to reuse later' and gives concrete examples (resolved ticker, target address, user preference, research subject). Clearly distinguishes from siblings like 'recall' and 'forget', which are explicitly mentioned.

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?

States 'Use when you discover something worth carrying forward' and provides example scenarios. Implicitly guides when not to use by referencing retrieval (recall) and deletion (forget). Could be more explicit about when not to use, but still effective.

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 several behavioral traits beyond annotations: it cascades through multiple lookup endpoints internally, gracefully degrades if enrichment sources are unavailable, labels identifiers with their source, and explicitly reports unresolved identifiers in an `unresolved` field. These details give the agent a realistic expectation of output robustness and failure modes, complementing the readOnly/openWorld/idempotent hints.

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

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

The description is long but well-structured, beginning with example phrasings and the key usage directive. It uses bold labels for supported types and packs dense but relevant detail about identifier sourcing and fallback behavior. While it could be trimmed slightly, every major segment adds value, and the organization aids scanning.

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

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

With no output schema, the description fully compensates by enumerating expected return identifiers for both entity types (CIK, ticker, LEI, FIGI, RxCUI, etc.), including source labels and unresolved handling. It also covers input variations and enrichment degradation. This is a complete description for an agent needing to understand inputs, outputs, and edge cases.

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

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

Even though schema coverage is 100%, the description substantially enriches parameter semantics. It details accepted inputs for 'company' (ticker, CIK, ISIN, or name), explains the ISIN-to-LEI resolution pathway, and specifies drug input forms (brand or generic name). This goes well beyond the schema's brief descriptions, giving the agent crucial disambiguation 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 states the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It gives specific verbs ('resolve', 'look up') and distinguishes the tool by emphasizing it 'Use FIRST whenever you have a name but need an ID' and by enumerating supported entity types (company and drug). This makes it easy for an agent to recognize when to invoke it.

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 instructs when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, contextualizing its role. However, it does not explicitly mention alternative tools or when not to use it, aside from implying it's the first step in a pipeline.

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. The description adds value by explaining the internal mechanism (probing each entity with `ai_visibility_check`) and the output structure (ranked list with score, confidence, signal density). This discloses key behavioral traits beyond the annotations.

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

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

The description is two front-loaded sentences: the first clearly states the core function, and the second adds context and output details. Every sentence earns its place without 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?

For a tool with 4 parameters (1 required) and no output schema, the description adequately describes the output format and the required parameter's role. Optional parameters are covered by the schema. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by specifying that the first entity is treated as the 'subject' for narrative purposes and explaining the `context` parameter's disambiguation role. This provides meaning 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), differentiating it from siblings like `ai_visibility_check` (single entity) and `compare_entities` (generic). It provides a concrete use case and output example, making the purpose unmistakable.

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

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

The description explicitly states the tool is useful for 'competitive AI-marketing audits' and gives an example question, implying when to use it. It does not explicitly list alternatives or exclusions, but the context from sibling names (e.g., `ai_visibility_check`) and the tool's comparative nature provide sufficient guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral details beyond annotations: fans out to two services, partial failures degrade gracefully, first measurement of a new version can take 5-30s, and the 'sources_failed' field will list any timeouts.

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

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

The description is well-structured and front-loaded with the primary purpose. Every sentence adds value, covering usage, inputs, behavior, and limitations. It is slightly verbose but appropriate for the tool's complexity.

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

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

No output schema exists, so the description compensates by listing return fields explicitly (summary block contents, per-advisory detail, links, alternative versions). It also covers partial failures and timing characteristics. This makes the tool's return value and behavior fully transparent.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds marginal value: confirms package name format and version defaults, but these are already in the schema. Baseline 3 is appropriate as the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, fanning out to deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and resource ('npm package'). It distinguishes from siblings by specifying the NPM ecosystem scope, which is unique among the 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusion context: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells when to use and 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation. It also explains output includes character offsets for verification.

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

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

The description is two paragraphs, front-loading the core functionality and then adding usage guidance and technical details. Every sentence is informative, with no redundancy or fluff.

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

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

Despite no output schema, the description explains return values (passages, offsets, scores) and limitations (truncation). Given the tool's complexity and available annotations, it provides all necessary context for correct usage.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing example text and queries, and explaining the limit default. It enhances understanding but does not introduce new necessary info beyond schema.

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

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

The description clearly states the tool's purpose: semantic search inside a fetched record. It specifies the verb 'search', the resource 'text', and provides concrete examples (e.g., SEC 10-K body, article). It distinguishes itself from siblings 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?

The tool explicitly states when to use it: when the record is too big for the prompt. It highlights the benefit of saving context and mentions a complementary tool (ask_pipeworx_grounded), giving clear guidance on alternatives.

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

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

Beyond annotations (readOnlyHint false, idempotentHint true), the description reveals important behaviors: subscription id is returned, SMS has a daily cap, webhook auto-disables after 10 failures, and signing secret is returned only once. This adds significant behavioral context not in 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, then efficiently covers all details in a well-structured manner. Every sentence adds value, with no redundant or extraneous text. Despite the length, it remains clear 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 the complexity (3 parameters, nested objects, 5 subscription types, 3 delivery channels, no output schema), the description is remarkably complete. It covers prerequisites, type-specific parameters, delivery behaviors, and limitations, leaving no significant gaps for an agent to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description enriches each parameter with concrete examples and detailed explanations (e.g., sec_8k items codes, polymarket_edge topics, delivery webhook HMAC signing). This adds substantial meaning 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 action 'Create a proactive monitoring subscription to a live-data event stream' and the outcome 'Returns the new subscription id'. This distinctively identifies the tool's purpose and differentiates it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account), supported subscription types with examples, and delivery channel options with limitations (e.g., SMS 10/day cap). However, it does not directly contrast with alternative tools or explicitly state when not to use this tool, though the context is implied.

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 and idempotentHint=true. The description adds transparency by stating that the tool returns example questions with exact tool+argument shapes drawn from a live catalog, and that it can be called with no arguments or a topic. 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 a single paragraph but is front-loaded with example queries and includes explicit usage guidance. Although slightly verbose, every sentence adds value and the structure is logical.

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

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

With no output schema, the description fully explains the return value (category-bucketed example questions). The tool is simple with one optional parameter, and the description covers its purpose, usage, and parameter semantics comprehensively.

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 one optional parameter described. The description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining the behavior of omitting the parameter (cross-category spread), going beyond the schema's brief description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It explicitly lists example queries like 'what can I ask Pipeworx?' and distinguishes it from siblings by positioning it as the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides examples of when to use (e.g., when needing ideas or getting started). It does not explicitly exclude alternative tools, but the context is clear and 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?

Adds value beyond annotations: ownership enforcement, deactivation vs deletion, and linkage to 'recent_alerts'. Annotations already indicate non-destructive and idempotent.

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

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

Two sentences, front-loaded with main action, no unnecessary words.

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

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

Simple tool with one parameter and no output schema; description covers behavior, ownership, and outcome, making it complete.

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

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

Schema coverage is 100% with clear description of 'id' parameter; description adds no further semantics beyond what schema provides.

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

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

Description clearly states the verb 'cancel' and resource 'subscription by id', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement and explains that deactivation preserves historical events via 'recent_alerts', providing context on when to use. Could mention alternatives more directly.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by explaining the verdict types, the meaning of could_not_verify and unsupported, and the error structure (verification_error{stage,detail}). It also clarifies the distinction between could_not_verify and refuted/inconclusive, which is critical for callers.

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

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

Though long, every sentence earns its place: it opens with natural-language examples, states the use case, explains the dual processing paths, details return values and error semantics, and highlights a critical caller warning. It is well-structured and front-loaded, with no redundancy.

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

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

The description is thorough for a complex tool with no output schema. It explains the return verdicts, the meaning of each ambiguous case, the two processing routes, and the advantage over sequential calls. This gives callers enough context to use the tool correctly and interpret results.

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

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

Schema coverage is 100% and the schema already documents both parameters with examples, defaults, and tolerance ranges. The description adds minimal extra parameter detail (e.g., mentions 'exact percent-delta math' and tolerance implied by wording), but it does not meaningfully supplement the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with a specific verb ('validate', 'fact check') and resource (claims). It distinguishes itself by describing a structured SEC/XBRL fast path for company-financial claims and a grounded pipeline for all other claims, setting it apart from generic ask/deep_research 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear trigger. It also explains the two processing routes based on claim type. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the full 5.

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