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 establish read-only, open-world, and idempotent behavior, so the description does not need to restate those. It adds meaningful behavioral context by explaining the tool fills arguments, routes to verified sources, and returns stable citation URIs. This goes beyond what the annotations alone convey.

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

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

The description is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and is densely informative with trigger phrases, examples, and sibling routing. It is somewhat long, and the self-reference to 'ask_pipeworx (low-latency mode)' is slightly confusing, but overall it remains well-structured and purposeful.

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 appropriately explains the return behavior: a structured answer with stable citation URIs. It covers a wide range of domains, gives concrete examples, and provides clear routing guidance to alternatives. An agent has enough context to invoke the tool correctly for most factual questions.

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 fully documented in the schema. The description adds examples of valid questions but no new parameter semantics, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes a natural-language question to one of 5,798 tools and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from web search and several sibling tools, making its role immediately apparent.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names specific alternatives with their conditions, such as ask_pipeworx_grounded for verified citations, compare_entities for tradeoff matrices, and deep_research for broad multi-part research.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description builds on that with the current state ('No candidate is active... this currently matches ask_pipeworx exactly') and the dynamic beta behavior. It also discloses that results feed comparison/merge decisions. It does not mention rate limits or auth, but those are less relevant for an annotated read-only ask tool.

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

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

The paragraph is information-dense but each clause earns its place: beta status, equivalence, current inactive candidate, usage instruction, and fallback reassurance. The final 'Falls back to nothing...' sentence is slightly redundant with earlier statements, but it prevents a dangerous misinterpretation that this is a wrapper that could fail.

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 single-question router with no output schema, the description covers the essential context: what it is, how it behaves now, when to use it, and that it is a full router. It relies on ask_pipeworx for exact response details, but since it explicitly declares the same response shape, this is acceptable. A small gap is the absence of any note on whether the routing result can change during a session, but the live-candidate caveat covers that.

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

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

Schema description coverage is 100%, with every parameter clearly documented as an alias for question, so the schema carries the parameter burden. The description only adds 'same arguments' without naming semantics, so there is no need to compensate; baseline 3 is appropriate.

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

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

The description opens with 'Beta version of ask_pipeworx' and defines it as an identical universal router with the same tools, arguments, and response shape, so an agent knows exactly what the tool does and how it differs from the stable sibling. It connects the name to a concrete behavior (routing a question) and clearly separates it from ask_pipeworx and ask_pipeworx_grounded by labeling it the experimental edge.

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

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

It gives an explicit selection rule: 'Use it exactly like ask_pipeworx when you want the newest routing', and it explains that current behavior matches ask_pipeworx because no candidate is active. The comparison against the stable router also signals that ask_pipeworx is the default alternative. This is sufficient routing guidance for an agent.

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

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

Beyond the annotations, the description discloses the full success return shape including evidence as a verbatim quote, confidence, source, and fetched_at. It also enumerates all refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and states that the answer only uses tool result content. The extra LLM call cost and routing mechanism are also transparently disclosed.

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

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

The description is relatively long but every sentence carries substantive information: purpose, mechanism, return values, refusal modes, usage guidance, and cost comparison. It is front-loaded with the core purpose and structured logically, though slightly verbose in the routing explanation.

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 specifying both the success and refusal return shapes, including exact field names and enum values for refusal_reason. It also covers when to use, when not to, cost implications, and the routing behavior. Nothing an agent needs to invoke or interpret this tool 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%: the only meaningful parameter, question, is fully described in the schema, and all five aliases are documented. The tool description does not add parameter-specific semantics, but given full schema coverage, 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 immediately identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes it from its sibling ask_pipeworx by explaining the extraction mechanism: 'EXTRACTS the answer using ONLY what the tool result contains.' The verb, resource, and differentiating behavior are all explicit.

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

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

The description states exactly when to use the tool ('Use whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative explicitly and provides the cost trade-off ('Costs one extra LLM call vs ask_pipeworx').

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

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

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description goes far beyond that with genuinely useful behavioral context: latency expectations (15-60s, up to ~90s), gap recovery behavior ('never invented', explicit gaps[]), contradiction scanning, the parallel decomposition strategy, citation resolvability ('present only when the source emits one'), and semantic excerpting. Nothing about the tool's observable behavior is hidden.

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?

Every sentence earns its place — the account gate is front-loaded before anything else, and the dense middle section packs an unusual amount of behavioral detail without fluff. It is long, but the tool is legitimately complex (two params, no output schema, rich runtime behavior), so the length is justified. Minor redundancy exists: the depth-level mechanics repeat what the schema already documents.

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

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

With no output schema, the description carries the full burden of explaining return values — and it does exhaustively: findings packet with verbatim evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], and the hop field. It also covers prerequisites (account, paid plan), latency, data-source scope (1517 sources, 5,798 tools), and behavior on unanswerable facets. Nothing an agent needs to invoke this tool 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 coverage is 100%, so per the baseline rule a 3 is warranted even with no description-side info. However, the description adds real value beyond the schema: it specifies that 'thorough' requires a paid plan, gives latency expectations per depth, and provides example questions ('compare X and Y's regulatory + financial exposure') that help an agent formulate a good `question` value. This is supplementary semantic guidance the schema doesn't offer.

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 1517 STRUCTURED data sources' — and explicitly disambiguates from siblings with 'this is NOT open-web search.' It also carves out its niche versus ask_pipeworx ('For a single lookup use ask_pipeworx instead'), so an agent can distinguish it from every one of the 33 siblings without opening another tool.

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

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

The description gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), an alternative gate ('If you are not signed in, use ask_pipeworx instead — it works on every tier'), and a hard prerequisite (account, paid plan for thorough). No usage condition 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 already mark this readOnly, non-destructive, idempotent, and open-world; the description adds consequential behavior beyond that: it fans out across EDGAR, XBRL, patents, contracts, FDA Purple Book, H-1B, news, and GLEIF; patents soft-fail after the May 2025 sunset; an empty fda_products section is expected for non-biologic companies; and sources_used/sources_failed distinguish real no-data from bugs. 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 the length is earned: there is no output schema, so it must enumerate response sections and edge cases. It is front-loaded with usage examples and the overriding 'ALWAYS PREFER' rule. Minor redundancy exists with the schema's type/value descriptions, but each sentence contributes operational guidance.

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

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

For a complex tool with no output schema, the description is remarkably complete: it enumerates all returned fields, source coverage, expected-empty semantics, soft-failure modes, input resolution behavior, and private-company handling. An agent can decide when to call it and interpret its results without additional lookups.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds value with concrete examples ('AAPL', '0000320193', 'Moderna'), explains that names resolve via SEC EDGAR's company-name match, and clarifies that type enum values behave identically regardless of which is passed—nuance not in the schema on its own.

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 defines a specific operation—build a full cross-source profile of a US public company—and anchors it with concrete user intents ('brief me on Tesla'). It also distinguishes itself from chained single-source lookups by promising everything in one parallel call, so an agent can tell it apart from narrow 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?

Explicit guidance is present: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent what inputs are valid (ticker, zero-padded CIK, or company name), what happens for private companies (resolved:false with a notes line), and that 'type' accepts both enum values interchangeably.

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?

The description goes well beyond the annotations: it explains compatibility_codes semantics, non-equivalent bet shapes, skipped leg handling, temporal_alignment null meaning, gross-vs-net fee treatment, and the standing pairing_unverified caveat. Nothing contradicts the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false annotations; the extra disclosure reinforces them.

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

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

The description is long but well front-loaded: purpose, modes, response shape, safety fields, and limitations appear in logical order with clear uppercase labels. The density is justified for a complex tool with no output schema, though it could be slightly tightened per topic with bullet-like formatting.

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 and only sparse parameter metadata, the description carries the full explanatory burden and succeeds: it covers response semantics, compatibility warnings, skipped leg counters, fee caveats, temporal alignment null behavior, and the current caveat about pre-mapped topics. An agent has enough to invoke the tool and interpret its results correctly.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds non-obvious value by stating that both modes run the identical token-overlap matcher, that explicit parameters override the topic-mapped side, and that pre-mapped topics do not guarantee tradeable spreads.

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

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

The opening sentence defines the deliverable precisely: a cross-venue spread between Kalshi and Polymarket for the same resolving question, and the following sentence clarifies when that delta is meaningful. It is clear and distinct from generic arb/edge tools, but it does not explicitly name or differentiate against a sibling like polymarket_arbitrage.

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

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

The description provides explicit mode selection: use `topic` shortcuts for pre-mapped macro events, or provide explicit `kalshi_event_ticker` and `polymarket_event_slug` for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning, giving practical usage caution, though it never directly contrasts this tool with sibling 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 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 adds substantial behavioral context beyond the annotations: it explains that multiple lookup endpoints cascade internally, that LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable, that unresolved identifiers are stated explicitly, that multi-match cases return `figi_candidates` rather than asserting incorrectly, and that ISIN inputs resolve through GLEIF mapping. This is rich, non-obvious behavior an agent needs to predict outcomes.

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 quite long, but it is front-loaded with realistic user phrases and a clear 'Use FIRST' directive, and nearly every sentence carries operational information. Some nested parentheticals and repetitive caveats make it denser than necessary, but the structure remains scannable by supported type.

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

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

For a tool with no output schema and two polymorphic entity types, the description is remarkably complete. It covers accepted inputs, source databases (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), ambiguity behavior, failure/degradation behavior, unresolved identifiers, and the internal multi-call benefit. An agent has enough context to invoke it correctly and interpret unexpected results.

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

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

The input schema already documents both parameters well, so the baseline is 3. The description adds extra semantic guidance: company input may be a ticker, CIK, ISIN, or name; ISINs resolve to the legal entity issuers; and non-equity instruments without tickers are explicitly supported. It also gives the important warning to pass the issuer name exactly and not the full noun phrase, which prevents a common invocation mistake.

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 resolves a user-spoken name to canonical/official identifiers needed as input by other tools. The examples cover multiple concrete question phrasings, and the routing instruction 'Use FIRST whenever you have a name but need an ID' clearly separates it from the broader entity/analysis tools in the sibling list.

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

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

The description explicitly says when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported entity types and input formats. It does not explicitly name alternative tools or state when not to use it, but the condition and supported-type scoping are clear enough for an agent to route correctly.

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.