Data Lv

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable behavioral context: default model is free, Anthropic requires BYO key and charges, returns per-model details. No contradictions.

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

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

Two sentences, front-loaded with core purpose, no fluff. Each sentence adds value: what it does, default/optional behavior, return structure, use cases.

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

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

Despite no output schema, description explains return format (per-model fields + combined view). Covers all 4 parameters meaningfully. Lacks only minor details like rate limits, but annotations imply idempotent and read-only, so not critical.

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 good property descriptions. Tool description enriches: explains _apiKey passed through to Anthropic, context helps disambiguate, entity examples provided. Adds 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?

States specific verb 'Probe' and clear resource 'LLMs for what they know about a business/brand/product/topic', with explicit output 'score visibility (0-100) per model'. Distinct from siblings like ask_pipeworx which are about different domains.

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?

Clearly states when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default model and optional Anthropic probe. Does not directly compare to sibling tools but context is sufficient given the unique purpose.

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 cover read-only, open-world, idempotent, and non-destructive hints. The description adds behavioral context beyond these: returns structured answers with pipeworx:// citation URIs, fills arguments automatically, works on every tier, one fast call, and routes to live news for breaking topics. This adds significant value beyond annotations, with no contradiction.

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

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

The description is lengthy (~250 words), but it's front-loaded with the key directive ('PREFER OVER WEB SEARCH') and structured with examples and alternatives. Each section earns its place, though some repetition exists (e.g., 'START HERE' and 'default entry point'). It's appropriately detailed for a tool with many use cases without being overly verbose.

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

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

The description fully equips an agent: it covers when to use (factual questions), what it does (routes to tools, fills arguments), what it returns (structured answer with citation URIs), alternatives with specific conditions, and example queries. Since there's no output schema, the description clearly states the return value. It's comprehensive for 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% with descriptions for each parameter, so baseline is 3. The description adds examples of valid queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that clarify the expected input format and the kind of factual questions to ask. This goes beyond the schema's basic 'natural language question' description, enriching parameter understanding.

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

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

The description clearly states the tool's purpose: it routes questions to appropriate tools among 5,635 tools and returns structured answers with citations. It gives specific domains (SEC filings, FDA, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. This is a specific verb+resource+scope and differentiates clearly.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions – this is the default entry point.' It names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions) and provides conditions for stepping up. Gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: the experimental beta nature, that no candidate is currently active (so it matches stable exactly), and the important clarification that it 'Falls back to nothing — this IS a full working router' rather than a stub. 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 essential facts are front-loaded — 'Beta version of ask_pipeworx' appears first, immediately orienting the agent. However, the description is a bit wordy: details like the exact retirement date (2026-07-26) and 'on outcome evidence' are precise but arguably expendable and risk going stale. It could lose ~30% of its words without losing signal.

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 router tool whose output is not schema-defined, the description covers the essentials: what it is, the identical shape to ask_pipeworx, current status (no active candidate), and when to use it. It appropriately defers full behavioral detail to ask_pipeworx as the canonical reference. Minor gap: it doesn't describe the return format, but for a delegated router this is reasonably 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 description coverage is 100%, and the schema thoroughly documents the question parameter and its five aliases (q, text, input, query, prompt). The description adds general routing context but no parameter-specific semantics that aren't already in the schema. At full coverage the baseline of 3 is appropriate since the schema carries the load.

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 ('identical universal router' exposing the same 5,635 tools and same response shape), and it explicitly differentiates itself from ask_pipeworx by naming the beta/experimental status. An agent can immediately tell this apart from the stable ask_pipeworx and ask_pipeworx_grounded siblings.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. It clearly states when this beta is the right choice. It stops short of explicitly saying when NOT to use it (e.g., when production stability is needed), but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail beyond those: the extraction mechanism ('using ONLY what the tool result contains'), the return format with refusal reasons, the cost ('Costs one extra LLM call vs ask_pipeworx'), and explicit refusal behavior. No contradiction with annotations; it enhances the safety profile with concrete 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 dense but every sentence carries actionable information. It front-loads the purpose, then the mechanism, return format, usage guidance, and cost trade-off in a logical order. No filler or redundancy; it earns its length.

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

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

With no output schema, the description fully explains the return structure: {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and the refusal reasons list. It also covers usage context, cost, and the distinction from ask_pipeworx. Given the tool's complexity and existing annotations, nothing an agent needs to call it correctly is missing.

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

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

The input schema covers 100% of parameters with descriptions ('Your question in natural language... accepts q, prompt, text, input as aliases'), so the baseline is 3. The description does not add any additional parameter semantics beyond what the schema already states, which is acceptable given the full coverage.

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

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

The description explicitly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by saying 'Same routing as ask_pipeworx' but with extraction. This clearly identifies the specific verb, resource, and scope, and differentiates it from siblings without needing to inspect schemas.

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

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

It gives explicit usage conditions: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and directly names the alternative with a preference: 'prefer ask_pipeworx for casual lookups.' This is unambiguous when-to-use and when-not-to-use guidance with a sibling mentioned.

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 extensively details behaviors beyond annotations: resolution confidence, parent event extraction, news fallback, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread warnings, and cancellation rules. No contradictions with annotations.

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

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

The description is lengthy but well-structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT, etc.). It is front-loaded with purpose and usage. While every sentence adds value, some details could be summarized to improve conciseness for quick reading.

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

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

Despite no output schema, the description thoroughly covers response shapes (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and provides detailed examples for fan-outs. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaningful context: clarifies the 'depth' enum's default and effect, explains 'include_raw' usage, and provides input examples for 'market'. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, listing input types (slug, URL, question text) and use cases. It implicitly distinguishes from siblings like polymarket_arbitrage but does not explicitly contrast 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 explicitly says 'Use for "should I bet on X"...' and provides classifiers and fan-out examples. It lacks explicit exclusions (e.g., 'do not use for...'), but mentions closed markets and low-confidence scenarios as blocking paths.

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

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

Annotations already declare read-only, open-world, idempotent. Description adds data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs, providing rich 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?

Description is somewhat long but every sentence adds value. Front-loaded with examples and key guidance. Slight opportunity to tighten, but still efficient.

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

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

For a 2-param tool with no output schema, description covers return format (paired data + citation URIs), sorting, entity-specific data, and usage constraints. Complete for an AI agent to use correctly.

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

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

Despite 100% schema coverage, description adds meaning: explains what each enum type pulls, how to format values (tickers/CIKs vs drug names), and reinforces min/max constraints.

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 does side-by-side comparison of 2-5 companies/drugs, providing example trigger phrases and distinguishing between entity types. This is specific and differentiates from siblings like entity_profile.

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 'ALWAYS PREFER over sequential single-pack lookups' and warns against sequential lookups, providing clear when-to-use guidance with examples.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds the behavioral detail that it returns metadata including resources and resource_ids, which is sufficient for understanding the tool's effect. 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 a single, well-structured sentence that front-loads the purpose and includes all necessary information without unnecessary words. Highly concise and efficient.

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

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

For a simple read operation with one parameter and no output schema, the description is complete. It explains what the output includes, and the annotations cover safety. No gaps remain.

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

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

Schema coverage is 100% and the description reiterates the parameter's purpose but adds the context 'from search_datasets', which provides additional semantic meaning about where the id comes from. This adds slight value beyond the schema.

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

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

The description clearly states the tool's function: showing full metadata for a Latvia Open Data dataset by id or name. It specifies the source (from search_datasets) and what is included (all resources and their resource_ids), effectively distinguishing it from sibling tools like search_datasets.

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

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

The description implies the tool is to be used after search_datasets by referencing 'from search_datasets'. It provides clear context for when to use, though it does not explicitly state when not to use or mention alternatives. Still, the guidance is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond that: auth/tier requirements ('depth:"thorough" needs a paid plan'), latency expectations (15-60s, up to ~90s for thorough), gaps[] behavior, contradictions[] scanning, citation fetchability guarantees, and semantic (not head-) excerpting. No contradiction with annotations; the description aligns with the read-only profile while adding operational detail.

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 carries substantive information with essentially no filler, but the description is a single dense wall-of-text paragraph exceeding 200 words. The core purpose statement is buried mid-paragraph behind account/pricing details that are front-loaded, hurting scannability for an agent parsing it. The content justifies its length, but the structure and ordering do not.

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

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

There is no output schema, so the description carries the full burden of explaining return values — and it does: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[], contradictions[], and hop fields. Given the tool's high complexity (decomposition, parallel routing, depth tiers, iteration), auth, timing, and citation resolvability are all disclosed. Very little an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters well (question with guidance, depth enum with facet counts). The description adds real behavioral meaning beyond the schema — depth:'standard' re-angles unanswered gaps, 'thorough' chases the best first-pass leads, and the hop/second-hop iteration model — which helps an agent choose the right depth 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?

States a specific verb+resource ('grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources') and sharply distinguishes itself from open-web search ('this is NOT open-web search'). It also names sibling ask_pipeworx and differentiates on single-vs-multi-lookup, so an agent can select correctly without opening either schema.

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 best-fit ('Best for broad/multi-part questions over structured data'), names the alternative for each exclusion ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even gives an auth-based routing rule ('If you are not signed in, use ask_pipeworx'). When/why-not/alternatives are all spelled out with nothing 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, and each result is ready to call directly. No contradiction exists.

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

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

The description is a single paragraph with a clear front-loaded purpose. It includes a list of domains and details about the output. It is slightly long but all sentences earn their place, and the most critical information appears first.

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 absence of an output schema, the description fully explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also notes that no second lookup is needed. This is complete and appropriate 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 coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for parameters; it repeats the alias list but provides no additional semantics. However, it does reinforce that 'query' accepts natural language, which is already 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples (SEC filings, FDA drugs, etc.) and contrasts with siblings by advising to call this first when exploring many tools. This enables an agent to quickly understand and select it.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: [list of domains]' and 'Call this FIRST when you have many tools available and want to see the option set.' While it doesn't explicitly state when not to use or compare to alternatives like search_datasets, the guidance is clear and actionable.

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description details the internal fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and specifies return fields including patent API sunset and soft-fail behavior. 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 thorough but slightly verbose, containing multiple pieces of detail in a single paragraph. It is front-loaded with example queries, but could benefit from more structured formatting (e.g., bullet points) for key return fields.

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

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

Given no output schema, the description comprehensively lists return elements: cik, company_name, recent_filings (up to 5 with URIs), fundamentals (sorted by period_end), patents (with caveat), news, and LEI. It also mentions data sources, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, and the description adds examples ('AAPL', '0000320193'), clarifies that value can be ticker or CIK, and emphasizes that names are not supported. This provides practical guidance beyond the schema itself.

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 provides a 'full cross-source profile of a US public company' and uses example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling tools like resolve_entity and compare_entities, establishing a unique purpose.

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also instructs to use resolve_entity if only a name is available, as names are not supported. Provides clear when-to-use guidance 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 indicate destructiveHint=true, and the description aligns, adding context about clearing stale/sensitive data. No contradictions, but could mention if deletion is reversible. Overall clear.

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 with no fluff. The first sentence immediately states the action, followed by usage guidance. Perfectly sized and front-loaded.

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

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

Given the simple tool with one parameter, comprehensive annotations, and no output schema, the description covers usage, purpose, and relationships to siblings completely.

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

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

Schema coverage is 100% with a description for 'key' as 'Memory key to delete.' The description adds no further semantics beyond what schema provides, so baseline 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb-resource pair. It clearly distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve).

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: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall,' providing clear context and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', aligning with the safe, idempotent nature.

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 plus a bullet line of use cases. Front-loaded with action, no redundant words. 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?

Tool has 2 parameters (1 required), no output schema. Description covers what the tool does, what it outputs ('single text blob ready to drop at site-root/llms.txt'), and use cases. 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%, so baseline is 3. The description mentions 'Fetches the page, extracts title/description/key links' and 'maximum of link entries' implicitly refers to max_links, but does not add significant meaning beyond the schema descriptions. Adequate, not exceptional.

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 generates a 'production-ready llms.txt file' for any URL, specifying the verb, resource, and context. It uniquely identifies the tool's purpose among siblings (e.g., scan_competitor_ai_presence) without confusion.

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: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not include when-not-to-use or alternatives, but context is clear enough given sibling differences.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context by listing the return fields, which is useful beyond annotations.

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

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

Two concise sentences, no wasted words, front-loaded with purpose.

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

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

Given no output schema and low parameter count, the description adequately lists return fields and provides usage context, making it complete for this simple tool.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). Description does not add meaning beyond what's in 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 it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from siblings like 'subscribe' 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?

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when and why to use the tool.

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

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

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), providing minimal behavioral signal. The description compensates richly: filing returns a claim_token, you can pass it back later to read resolution status, rate-limited to 5 per identifier per day, free and does not count against quota, and the team reads digests daily. This adds substantial behavioral context beyond the structured fields, with no contradiction.

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

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

The description is longer than average but every sentence contributes: purpose, usage triggers, exclusion, filing guidance, claim_token mechanics, rate limit, and cost. It is front-loaded with the core purpose and structured logically. While a bit dense, it earns its length given the tool's complexity and lack of output schema.

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

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

Despite having no output schema, the description fully covers the return value behavior (claim_token) and how to consume it later. It addresses rate limits, quota, scope boundaries, and response semantics. For a feedback tool with nested context objects and four parameters, the description leaves no critical ambiguity about when or how to use it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving message field guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It doesn't redundantly repeat schema descriptions but enriches usage semantics, justifying a 4.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this from sibling query tools (ask_pipeworx, query_resource) by focusing on feedback submission. The title and description align, and the purpose is 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?

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is textbook usage differentiation with a named 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 indicate safe read operation. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching policy (5min-1h depending on window). This goes beyond annotations to build trust.

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 well-structured sentences with bullet points for use cases. Every sentence adds value; no wasted words. The description is front-loaded with the core function.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, usage context, and behavior. It answers what, when, and how to use, leaving no significant gaps.

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

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

Schema coverage is 100% for the single parameter 'window', including enum values and description. The description reinforces usage nuance: shorter windows for hot topics, longer for steady-state demand, adding semantic value.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It distinguishes from sibling tools by focusing on aggregated call volume from AI agents, not generic search or entity profiles.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. While it lacks explicit when-not-to-use guidance, the use cases are clear and helpful.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details behavioral traits: the scan logic (monotonicity, partition checks, semantic anchor, partition filter), the fill check against live CLOB depth, and the conditions under which signals should not be acted upon. No contradictions with annotations.

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

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

While the description is lengthy, every section is justified by the tool's complexity. It is well-structured with clear separation of modes, filters, and fill checks. Minor redundancy could be trimmed, but overall it is informative and front-loaded with the core purpose.

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

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

Given the lack of output schema, the description compensates by detailing the response structure (opportunities array, partition_check fields). It covers all modes, edge cases (semantic anchor, placeholder filter, fill check), and provides enough detail for correct invocation and interpretation.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds significant value by explaining that `event` selects single-event mode with slug/URL examples, `topic` enables cross-event scanning with seed question examples, and elaborates on their respective behaviors.

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 tool's purpose is explicitly stated: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk by specifying its unique methodology and modes of operation.

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 comprehensive usage guidance: when to call with no arguments (trending scan), with `event` (single-event mode with specific slug examples), and with `topic` (cross-event scanning). It explains why cross-event mode is beneficial and warns when not to trade (realizable_edge_pp ≤ 0). It also references a sibling tool for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: caching strategy (1h KV), response structure (by_segment, diagnostics), edge calculation (slippage, Kelly fractions), tradeable-edge knobs, and Fed bets disclaimer. No contradictions with annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with the core purpose. Technical details like model formulas and Kelly caps are included but could be slightly more concise; however, they are relevant for correct tool usage.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment with three segments, diagnostics, fed_candidates) and the fields in each opportunity. The tool has 9 parameters with detailed guidance, making it complete for complex 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?

Schema coverage is 100% with detailed descriptions. The description adds extra context for several parameters, e.g., slippage_pp explains Polymarket's zero fees and bid/ask spread, and min_partition_leg_kelly clarifies why min_kelly does not apply to partition arbs. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes three segments (model_driven, structural_arbitrage, concentrated_longshot) with detailed explanations, clearly differentiating from siblings 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 is built for 'what should I bet on today' and guides agents to discover opportunities without paging through hundreds of markets. It explains when to use filters (e.g., min_liquidity, max_spread_pp) but does not explicitly compare to sibling tools or 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 mark it as read-only, open-world, idempotent, non-destructive. The description adds behavioral details: reads snapshots, returns time-series, trend, decay, expired opportunities, and snapshot dates. No contradiction.

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

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

The description is front-loaded with the core purpose and is well-structured. It is somewhat lengthy but every sentence provides value; minor tightening could improve conciseness without losing detail.

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

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

Despite no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and covers limitations (TTL, start date, daily closes). No gaps given 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% with descriptions for both parameters. The description adds default values and clamping for 'days', and explains the 'window' parameter's meaning. This adds 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?

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge age and trend. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on time-series and decay analysis.

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

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

The description explains when to use the tool (to assess if an edge is fresh vs. old) and implies when not to use it (intraday not supported). It does not explicitly list alternatives but context makes the complementary nature 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context beyond these: it reveals that the tool 'walks the ladder' and returns verdicts (clean|degraded|cannot_fill), explains that partial basket fills convert arb into unhedged directional positions, and mentions forced_directional_risk. There is no contradiction with annotations.

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

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

The description is fairly long but well-structured with clear mode separators (SINGLE-MARKET, BASKET) and bullet-like formatting. It is front-loaded with the core purpose and each section adds unique information. While dense, it avoids redundancy and earns its length. It could be slightly more concise, but it remains readable.

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

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

Despite lacking an output schema, the description exhaustively lists the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It also includes warnings about risk and edge cases. Given the complexity of dual modes and the absence of an output schema, this is a fully complete description.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant extra context: it clarifies that `size_usd` has different interpretations for single-market (max spend vs target proceeds) versus basket (settlement notional), and explains the default `side` logic for basket mode. This goes beyond the schema descriptions and meaningfully aids 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 begins with a clear verb+resource pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to clarify its unique role. This meets the highest standard of differentiation.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also specifies that one of `market` or `event` is required, and explains the consequences of not using it (partial fills leading to directional risk). However, it does not explicitly state when not to use the tool, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructiveness. The description adds behavioral context: compatibility_warning conditions (non-equivalent bet shapes, no token overlap), temporal alignment flag, and skipped leg counters. This significantly enhances agent understanding beyond annotations.

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

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

The description is well-structured with sections for modes, response, and safety fields. It is somewhat verbose but every sentence adds necessary detail. No superfluous information. Front-loading the main purpose helps quick understanding.

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

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

Despite no output schema, the description thoroughly explains response structure (leg-by-leg prices, top_spreads_pp, safety fields). It covers all three parameters. The lack of required parameters and presence of examples makes it complete. Minor gap: could mention that output is JSON, but it's implied.

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 each parameter, but the description adds value by listing valid topic values (fed, btc, etc.) and providing concrete examples for explicit parameters. The baseline is 3; the added examples and explanation of overriding behavior justify a 4.

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

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

The description clearly states the tool calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue analysis. The verb 'calculate' and resource 'spread' are 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 explains two modes (topic shortcuts and explicit tickers) and warns that pre-mapped topics often return compatibility warnings, guiding users to explicit pairing for reliable results. It lacks explicit alternatives but infers when not to use (e.g., when compatibility warning fires).

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, and destructiveHint=false. The description adds value by specifying the data source (Latvia Open Data CKAN DataStore) and the queryability condition, enhancing the agent's understanding of behavior 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 sentences, front-loaded with the primary action and conditions. Every sentence provides essential information 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?

While the input and condition are clear, the description does not hint at the output format (e.g., JSON rows). Given no output schema, the agent may need to infer the result structure. The annotations (readOnlyHint) partially cover safety, but completeness is adequate for a simple query 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 each parameter already described. The description reiterates these but adds minimal new context (e.g., 'from a dataset's resources' for resource_id). It does not significantly augment the schema's meaning.

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

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

The description clearly states the tool pulls rows from a tabular CKAN DataStore resource by resource_id, with optional filters. This specific verb+resource pair distinguishes it from sibling tools like search_datasets which return datasets, not rows.

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 notes that only resources with DataStore enabled are queryable, providing a clear precondition. While it doesn't explicitly contrast with alternatives, the sibling list includes search_datasets (for dataset lookup) and others, so 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 provide readOnlyHint, destructiveHint, idempotentHint. Description adds scoping to user identifier and the key omission behavior, which is useful context beyond annotations.

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

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

Description is two sentences, front-loading the main action and usage. Every sentence provides necessary information 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?

For a simple retrieval tool with one optional parameter and no output schema, the description covers usage, scoping, and pairing with siblings. Annotations handle safety. Complete.

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

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

Schema coverage is 100% and the single parameter 'key' is well-described. Description clarifies that omitting key lists all keys, adding semantic value beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It distinguishes itself from sibling tools (remember, forget) by specifying the exact operation and pairing.

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 (look up stored context, avoid re-deriving) and how to list all keys. Mentions scoping but could be more explicit about when not to use or alternatives beyond siblings.

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

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

The description indicates that setting mark_read:true modifies state by flagging events as read, contradicting the readOnlyHint=true annotation. This is a serious inconsistency that undermines 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 concise at four sentences, each serving a clear purpose: stating the tool's function, describing return fields, explaining parameters with examples, and noting alternative access. No fluff.

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

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

The description covers the return format, parameter usage, and alternative access method. It lacks details on pagination and ordering, but given the simple nature of a feed pull, it is reasonably 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?

With 100% schema coverage, the description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the behavioral effect of mark_read. It also lists what each returned alert carries.

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 'Pull fired events from your subscription feed', clearly specifying the verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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

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

The description mentions the alternative HTTP endpoint, providing context for when to use the tool vs. direct access. However, it does not explicitly state when to use this tool over other query tools like query_resource.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world hints. The description adds valuable context: fan-out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail, and structured return format with citation URIs.

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 serves a purpose. First line captures intent with examples, then explains sources, parameters, fallback, and sibling comparison. 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?

Covers all essential aspects: sources, fallback mechanism, parameter formats, return structure, and sibling differentiation. Despite no output schema, the description compensates by mentioning the return format.

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

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

Schema coverage is 100% but description adds significant value beyond schema: explains since format with examples, clarifies value as ticker or CIK, and notes type is only company.

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

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

The description starts with concrete example queries and explicitly states it provides a change feed for a company within a time window, calling multiple sources in parallel. It clearly distinguishes itself from the sibling tool entity_profile.

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 this tool versus entity_profile, provides example queries, and gives detailed guidance on the since parameter (ISO date or relative shorthand).

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 important behavioral traits beyond annotations: key-value pairs are scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. This adds significant context not in the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). 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 and well-structured: it first states purpose, then usage, then technical details. Every sentence adds value without redundancy. It is appropriately sized 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?

Despite no output schema, the description fully covers the tool's functionality, usage context, and behavior. It explains what the tool does, how data is stored, scoping, persistence, and how it relates to sibling tools (recall, forget). No gaps remain.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds value by providing examples of keys (e.g., 'subject_property') and explaining the scoping mechanism, giving the agent a clearer understanding of parameter usage 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: 'Save data the agent will need to reuse later.' It specifies the verb (save), resource (data as key-value pairs), and distinguishes from siblings by mentioning paired tools recall 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?

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward.' It lists concrete examples (resolved ticker, target address, user preference, research subject) and mentions alternatives (recall, forget), though 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?

Beyond the readOnly/idempotent annotations, the description discloses important behavior: identifiers are source-labelled, unresolved identifiers are listed under `unresolved` rather than omitted, GLEIF/OpenFIGI enrichment degrades gracefully, and internal cascading lookups replace multiple manual steps. This adds meaningful context about reliability and output semantics without contradicting any annotation.

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 it is well-organized: opening examples, action statement, supported types with bullets-like details, and graceful-degradation note. The length is justified by the tool's complexity, but a few phrases (e.g., 'cross-source identity spine') feel slightly dense. Overall it is structured and informative, just shy of the tightness of a 5.

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 partially compensates by describing the output for drugs (RxCUI + ingredient + brand) and for companies (identifiers with source labels, plus the `unresolved` field). It also covers error handling (graceful degradation) and scope (non-US issuers via ISIN). It does not give a full output shape or list all fields explicitly, but it is reasonably complete for a resolver 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%, so the baseline is 3. The description adds value by expanding the accepted input forms for company (ticker, CIK, ISIN, or name) and providing a concrete ISIN example, as well as clarifying drug inputs (brand or generic). This supplements the schema's brief descriptions without being redundant.

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 is anchored by concrete user-phrased examples (“What's the ticker for…”) and then states the core action: “resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.” This clearly differentiates it from siblings like entity_profile or compare_entities by focusing on the act of resolving names to IDs, with explicit mention of supported types.

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 FIRST whenever you have a name but need an ID,” giving clear context for when to invoke this tool. It also notes that it replaces 2-3 manual lookups, implying it is a high-value first step. However, it does not explicitly list alternatives or state when not to use it, which would push it to a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds process details: probes each entity, ranks by score, returns confidence and signal density. Does not mention potential rate limits or API key dependency for anthropic model, but schema covers that.

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

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

Three sentences, each adding unique information: action, process, use case, and output. No fluff.

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

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

For a composite tool with 4 params (1 required) and no output schema, description adequately explains input semantics, process (calls ai_visibility_check), and output structure (ranked list with metrics). No missing critical information.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that first entity is treated as 'subject' for narrative and that context disambiguates names, going beyond schema descriptions.

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

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

Clearly states verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. Distinguishes from sibling 'compare_entities' by specifying it uses AI visibility checks and scoring.

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

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

Provides explicit use case ('competitive AI-marketing audits') and example question. Implicitly suggests when to use over sibling ai_visibility_check, but no explicit exclusions or 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, idempotentHint), description details partial failures, timeouts for bundlephobia, and sources_failed list. 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?

Well-structured, front-loaded with purpose, then usage, then behavioral details. Slightly verbose but each sentence adds value.

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

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

Despite no output schema, description explains return shape (summary block, advisories, links, alternatives). Covers parameters, behavior, limitations, and usage 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%, so baseline is 3. Description adds context about scoped packages and version defaulting, which enhances 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 it as a composite check for npm packages, combining deps.dev and bundlephobia. It uses a specific verb ('scan dependency') and distinguishes from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly tells when to use (when asked about safety, popularity, size) and when not to use (NPM only; other ecosystems should use deps.dev:version directly). Provides clear alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context by specifying the exact return structure (dataset id/name, title, organization, resources with resource_id), which helps the agent understand what the tool provides.

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

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

The description is two sentences: the first defines purpose, the second details return fields. Every sentence adds value with no redundancy, and key information is front-loaded.

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

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

Given the tool has 3 parameters with full schema coverage, no output schema, and comprehensive annotations, the description provides complete context: it names the data source (Latvia Open Data), specifies what is returned, and links to a sibling tool (query_resource). No gaps remain.

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

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

Schema coverage is 100%, with clear descriptions for all parameters (limit, query, offset). The description does not add any additional parameter semantics beyond what is already in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'search' and the resource 'Latvia Open Data datasets.' It lists specific return fields (id/name, title, organization, resources with resource_id), which distinguishes it from sibling tools like query_resource or search_within.

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

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

The description implies usage for searching datasets and mentions query_resource for next steps, but it does not explicitly state when to use this tool over alternatives, nor does it provide exclusion 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?

Adds specific behavioral details beyond annotations: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K), and truncation behavior. 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?

Compact single paragraph with front-loaded purpose, every sentence adds value. No filler.

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

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

Explains return format (passages with offsets and scores) and mentions model details. No output schema; missing error handling details but sufficient 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%, so baseline 3. The description adds examples for the query parameter and restates schema info. Some added value but limited 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 it performs semantic search inside a fetched record, using specific verbs like 'semantic search' and 'get back top-N passages'. It implies differentiation by specifying the use case (large record) but does not explicitly distinguish from all sibling tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but provides clear context.

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

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

Discloses behavioral traits beyond annotations: requires OAuth account, details delivery channels (feed always on, optional email/sms/webhook), SMS 10/day cap, webhook auto-disabled after 10 failures, and webhook signing. Annotations indicate idempotent and non-destructive, but description adds rich context.

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

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

Moderately long but every sentence adds value. Front-loaded with main purpose. Could be more structured (bullets), but still efficient and clear.

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

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

Covers all aspects: purpose, prerequisites, supported types, parameter formats, delivery options, limitations (caps, verification, auto-disable). No output schema, but description states it returns the subscription id. Complete for a complex subscription creation 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?

Despite 100% schema coverage, the description adds significant meaning: examples for each params type (e.g., sec_8k items, polymarket_edge topic), delivery constraints (phone verification, webhook signing), and details on always-on feed. Goes far beyond schema descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), and mentions that anonymous/BYO cannot persist subscriptions. Covers supported types and delivery channels, though does not explicitly list alternative tools.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe read behavior. The description adds that the tool returns example questions with exact tool+argument shapes from a live catalog, and explains calling with no arguments for a full spread or passing a topic to focus. No contradictions with annotations.

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

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

The description is fairly long but front-loaded with key information. It uses examples and lists, which aids understanding, but some sentences could be combined for conciseness. Still, it is not overly verbose and remains clear.

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

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

Given the large set of sibling tools, the description adequately positions this tool as an onboarding entry point. It explains the return format (category-bucketed example questions with tool+argument shapes) and mentions meta-tools, providing sufficient context. No output schema, but the description compensates.

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

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

Schema coverage is 100% with one optional parameter 'topic' described as an optional focus area. The description adds concrete examples of valid topics (finance, pharma, etc.) and clarifies that omitting the topic returns a cross-category spread, exceeding what the schema alone provides.

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

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

The description clearly defines the tool's purpose: returning category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It distinguishes from siblings by stating 'Use this FIRST' and explicitly listing the categories and what it returns (tool + argument shapes).

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

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

The description explicitly states when to use this tool ('when you do not yet know what Pipeworx can do') and mentions how it can teach the use of meta-tools (ask_pipeworx, entity_profile, etc.). It does not explicitly list when not to use it, but provides clear context for its role.

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 behavioral detail beyond annotations: explains that the row is deactivated (not deleted) and historical events stay available via recent_alerts. No contradictions with annotations.

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

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

Three sentences, each serving a distinct purpose: action, ownership constraint, and behavioral effect. 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?

For a simple one-parameter mutation tool without output schema, the description covers action, ownership, and deactivation behavior. Lacks error handling details but is sufficient for a basic 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 has 100% coverage with a clear description of the id parameter. Description does not add further meaning beyond what the schema already provides.

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

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

The description uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from siblings like subscribe and list_subscriptions. It also adds ownership and deactivation context.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when the tool is applicable. Missing explicit when-not or alternatives, but the intent 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?

The description goes well beyond the readOnly/idempotent annotations by clarifying the meaning of each verdict, especially the crucial distinction between could_not_verify (check did not happen, includes verification_error{stage,detail}) and unsupported (no source exists). It also warns callers not to treat could_not_verify as evidence. This is exactly the kind of behavioral context agents need.

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

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

The description is long but densely informative. It is front-loaded with examples and a clear usage statement, then covers the two paths, return values, and an IMPORTANT caller note. Every sentence adds value; however, the length and multiple clauses make it slightly less scannable than ideal. Given the tool's complexity, this is well-justified.

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

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

With no output schema, the description fully covers the return contract: verdict options, the actual value with citation, reasoning, and the error semantics for could_not_verify. It also explains the internal routing logic, which is essential for an agent to set expectations. The tool has only two parameters, both documented, and the description fairly explains all relevant behavior.

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

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

Schema coverage is 100% for both parameters, but the description adds meaningful detail: tolerance_pct overrides the wording-implied tolerance, suggests 1–2 for hallucination detection, and documents the default as implied by wording capped at 5. This goes beyond the raw schema and helps the agent choose appropriate values.

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

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

The description opens with explicit trigger phrases ("Is it true that…"/"fact check") and states the core action: natural-language claim verification against authoritative sources. It clearly distinguishes itself from siblings by describing a consolidated single-call tool that replaces 4–6 sequential steps, and the two processing paths (SEC EDGAR for company financials, grounded pipeline for other claims) make its scope 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 whenever the agent needs to check whether something a user said is factually correct.' It also provides decision-relevant nuance: company-financial claims take the structured fast path, while any other factual claim automatically falls through to the grounded pipeline. This is strong when-to-use guidance, though it does not name specific alternative tools.

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