Repology

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: it probes multiple models, returns per-model scores with confidence, signals, raw response, and combined view. It also explains how the API key is used and that Anthropic calls are paid directly by the user. 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 four sentences long, front-loaded with the main action, and each sentence adds distinct value without redundancy. It is well-structured 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?

Given there is no output schema, the description adequately explains the return format (per-model {score, confidence, signals, raw_response} + combined view). All parameters are documented in the schema, and the description adds necessary context for usage. The tool is complex but the description is complete for an agent to use correctly.

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

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

All 4 parameters have descriptions in the schema (100% coverage), so baseline is 3. The description adds valuable context beyond the schema: it explains the default model (Workers AI Llama-3.3-70b free), the role of _apiKey for Anthropic, and the purpose of the context parameter for disambiguation. This enhances 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 it probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It specifies default model and optional Anthropic probe, making the tool's purpose distinct from sibling tools like scan_competitor_ai_presence.

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

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

The description provides clear usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use or compare with alternatives like scan_competitor_ai_presence. The guidelines are good but could be more exhaustive.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. Description adds that the tool routes queries, fills arguments, and returns structured answers with citation URIs, exceeding annotation coverage.

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

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

Description is lengthy but front-loaded with key information, structured logically with purpose, usage, and examples. Could be slightly more concise but remains effective.

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

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

For a tool with no output schema, the description fully explains the output format, behavior, and integration with other tools. It is complete given the tool's simplicity and annotation richness.

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 well-documented aliases. Description reinforces the meaning by providing example questions, adding value beyond the schema.

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

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

The description explicitly states the tool routes questions to over 4,800 sources for structured answers with citations, distinguishes from siblings like 'ask_pipeworx_grounded' and 'deep_research', and provides concrete examples of use.

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?

Clear guidance to use this as the default entry point, with explicit when-not-to-use and alternatives for hallucination-resistant or broad queries. Examples illustrate appropriate use cases.

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

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

Description adds substantial context beyond annotations: costs one extra LLM call, explains the internal routing (picks from 4,819 tools across 1,259 sources), and details refusal reasons. 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 with key info front-loaded (purpose, then process, then return format, then usage). Slightly long but every sentence earns its place.

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

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

Complete: explains return format (including refusal cases) and cost despite no output schema; covers all 6 parameters; distinguishes from main sibling despite many siblings.

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 of aliases; description adds no new semantic info beyond 'Your question in natural language.' Baseline 3 is appropriate.

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

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

Description clearly states 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers solely from tool results, distinguishing it from sibling ask_pipeworx which is for casual lookups.

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

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

Explicitly tells when to use (quoted/cited/acted-on answers, no invention for financial/legal/medical/public claims) and when not (prefer ask_pipeworx for casual lookups), 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?

The description extensively discloses behavioral traits beyond annotations, including fan-out logic, response shapes (market, analysis, evidence), safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), resolution-rule risk, and cancellation rule parsing. This far exceeds the hints provided by annotations (readOnly, openWorld, idempotent) and adds critical context for safe usage.

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

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

The description is well-structured and front-loaded with the primary purpose. It efficiently packs extensive information into sections (classifiers, fan-out examples, response shapes, safety) without redundancy. Every sentence adds value, and the length is appropriate given 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 lacking an output schema, the description thoroughly explains all return fields (market, analysis, evidence) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It covers safety, blocking conditions, and provides examples, making it fully sufficient for an agent to use the tool correctly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant extra meaning beyond the schema: it explains the behavioral difference between 'quick' and 'thorough' depth (2-3 sources vs full fan-out) and the impact of 'include_raw' (summarized vs full payloads), enriching the agent's understanding of parameter trade-offs.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' specifying the verb ('Research') and resource ('Polymarket bet'). It distinguishes from sibling tools by detailing the comprehensive fan-out and use cases like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', which are not covered by other specific tools.

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

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

The description provides explicit usage context with phrases like 'Use for...' and explains when the tool short-circuits (low confidence, closed markets). However, it does not explicitly compare against sibling tools or state when not to use this tool versus alternatives, leaving some ambiguity.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds significant context: single parallel call (fast), results sorted by primary metric, includes citation URIs, handles off-calendar fiscal years. 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?

Dense paragraph packs much information with front-loaded usage examples. Every sentence adds value. Could be slightly more structured (e.g., bullet points), but remains effective and concise.

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 key aspects: two entity types, data sources, parallel call behavior, sorting, citation URIs. No output schema, but mentions return format. Sufficient for an agent to understand capabilities and constraints.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enriches by explaining type enum values ('company' vs 'drug') with what data they retrieve, and values field format (tickers/CIKs for company, drug names for drugs) plus constraints (2-5 items). 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's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It uses specific verbs like 'compare', 'rank', 'head to head' and specifies resources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs). It distinguishes itself from sibling tools like 'entity_profile' by emphasizing efficiency.

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 prefer this tool over sequential lookups and provides example query phrases. Explains when to use 'company' vs 'drug' type and what data each retrieves. Missing explicit 'when not to use' scenarios, but overall guidance 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?

No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). Description adds account requirements, paid plan for 'thorough', expected latency (15-60s), parallel decomposition, output format (findings packet with citations and gaps), and behavior when topic not in catalog (returns empty gaps).

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

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

Description is long but well-structured with parentheticals and bullet points. Front-loaded with account requirement. Every sentence adds value; no fluff. Given complexity, length is acceptable.

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

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

Given the tool's complexity (parallel research, 1259 sources, 4819 tools, 2 params), the description covers prerequisites, latency, output format, limitations, and use cases. No output schema, but description explains return type sufficiently.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: depth enum values explained (quick=3, standard=5, thorough=8 paid) and question described as broad/multi-part fine. Adds value beyond raw schema.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1259 STRUCTURED data sources' and distinguishes it from siblings like ask_pipeworx (single lookup) and open-web search. The verb 'research' and resource 'structured data sources' are specific.

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

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

Explicit guidance: 'Best for broad/multi-part questions over structured data' and when not to use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also mentions account requirement and fallback tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral details beyond: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

Single paragraph is information-dense with no wasted words. Front-loads purpose, then provides usage guidance and key behavioral details. Very 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?

Despite no output schema, the description fully explains what the tool returns (top-N tools with schemas and examples) and the context for using it first. Adequately covers all aspects 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the query parameter expects a 'natural language description,' listing example queries, and mentioning aliases (task, q, search, description) and the limit parameter's default/max. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb and resource, and distinguishes itself from siblings by advising 'Call this FIRST' and listing many domain examples.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear context and implies when not to use.

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

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

Annotations already convey readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds critical context: the USPTO API sunset (soft-fail behavior), the parallel fan-out across sources, and the specific return fields. 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 lengthy but front-loaded with example queries and a clear purpose. Every sentence adds value, though some details (like 'USPTO PatentsView API sunset May 2025') could be slightly more concise. Still highly functional for an agent.

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

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

Despite lacking an output schema, the description thoroughly explains return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and sources. It also notes the patent API sunset and name unsupported case, providing complete context for the tool's capabilities.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: it explains that 'value' accepts ticker or zero-padded CIK (not names), and that 'type' is currently limited to 'company'. It also clarifies the CIK zero-padding requirement.

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 specifies that the tool provides a full cross-source profile of US public companies, listing data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return types. It distinguishes itself from sibling tools like 'compare_entities' and 'deep_research' by focusing on a holistic view of a single entity.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using 'resolve_entity' first if only a name is available, providing clear usage boundaries.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not elaborate on behavioral details beyond what annotations provide. With good annotation coverage, the description's value is modest.

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, first stating purpose, second giving usage guidelines. No redundant information, highly efficient.

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

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

For a simple 1-parameter tool with good annotations and no output schema, the description covers use cases and sibling relationships well. It could mention irreversibility implicitly covered by destructiveHint, but overall complete.

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

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

Schema coverage is 100%, so baseline 3 applies. The description adds no parameter-specific information beyond what the schema provides (e.g., 'Memory key to delete').

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 deletes a previously stored memory by key, with a specific verb and resource. It distinguishes from siblings by explicitly pairing with 'remember' and 'recall', indicating its complementary role.

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 when-to-use scenarios: context stale, task done, or clearing sensitive data. It also mentions pairing with alternatives 'remember' and 'recall', offering clear guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining the process: fetches page, extracts title/description/key links, and emits standard format. This goes beyond annotations, but could mention rate limiting or content extraction limits.

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 plus a bullet list of use cases, all front-loaded with the core purpose. No extraneous words or redundancy. Every sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema, clear annotations), the description provides sufficient context: explains output format, use cases, and process. An agent can correctly invoke and use the tool without gaps.

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

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

Schema coverage is 100% with both parameters described. The description does not add significant new meaning beyond the schema; it mentions 'max_links' is the max number, which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate), resource (llms.txt for a URL), and output format (standard markdown). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on a specific output file rather than scanning or 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 explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor visibility. This provides clear guidance on when to use this tool versus others, 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds useful behavioral context: scoped to caller's own subscriptions, default to active, and lists return fields. No contradictions.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No fluff, front-loaded, every sentence earns its place.

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

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

For a simple list tool with one optional parameter, description adequately covers purpose, output, and usage. Could mention pagination but not critical given openWorldHint. Sufficient overall.

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 parameter include_inactive already described. Description reinforces the default behavior (active only) but doesn't add significant new meaning beyond schema.

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

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

Description clearly states 'List the caller's active subscriptions' with specific return fields. Distinguishes from siblings like subscribe/unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly advises using this tool before adding subscriptions or to find an id for cancellation, providing clear context. Alternatives (subscribe/unsubscribe) are implied via sibling tools but not named directly.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds that the parameter is a canonical ID (often email), but does not disclose other behavioral traits like rate limits or output variability. This is adequate given the annotation richness.

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

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

The description is a single, front-loaded sentence with no extraneous information. Every word serves a purpose.

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

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

For a simple one-parameter lookup tool with an output schema, the description provides essential context. It could be improved by hinting at what the summary contains, but the presence of an output schema reduces this need.

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 0% schema description coverage, the description partially compensates by clarifying the parameter represents a canonical maintainer ID, often an email. However, it does not specify expected format, validation rules, or constraints beyond the schema examples.

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

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

The description clearly states the tool returns a summary for a maintainer identified by ID. It is specific about the resource and action, but could be more explicit about the verb. It does not differentiate from sibling tools 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?

No guidance is provided on when to use this tool versus alternatives such as entity_profile or project. The description does not mention contexts or exclusions.

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

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

Despite sparse annotations, the description adds key behavioral details: rate limit of 5 per day, no quota impact, and roadmap influence. 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?

Single paragraph with clear front-loading of purpose, followed by usage conditions and constraints. Every sentence is informative and necessary.

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 feedback tool with 3 parameters and no output schema, the description fully covers use cases, constraints, and expectations. 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 already has 100% description coverage. The description adds contextual guidance (e.g., 'don't paste end-user prompt') and reinforces enum meanings, providing extra value beyond schema.

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

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

The description clearly states the tool's purpose: sending feedback about broken, missing, or needed features. It specifies categories like bug, feature/data_gap, praise, and distinguishes it clearly from sibling tools which are analytical or research-oriented.

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 when to use each feedback type and cautions against pasting user prompts. Mentions rate limits and that it's free, providing comprehensive usage 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?

Adds behavioral context beyond annotations: data source (CF analytics-engine), privacy (no PII), caching (5min-1h). No contradiction with readOnlyHint, idempotentHint, etc.

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?

Efficient, front-loaded with main function. Bullet points for use cases. Every sentence adds value, no fluff.

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

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

Provides sufficient context for a read-only tool with one optional parameter and no output schema. Includes return contents, caching, privacy. Minor gap: exact return format not specified but 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 single parameter having enum. Description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Description clearly states it returns trending tools, packs, and call volume over a window, using specific verbs and resource. Distinguishes from sibling tools like discover_tools by focusing on aggregate trending data.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Lacks explicit when-not-to-use but context is clear.

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

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

The description provides extensive behavioral details beyond annotations, such as monotonicity checks, partition_sum computation, semantic anchor similarity threshold, partition filter, and fill check with realizable edge. It does not contradict any annotations.

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

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

The description is well-structured and front-loaded with the core function. While detailed, it remains focused and organized, though some specifics (like exact thresholds) could be considered excessive for an AI agent.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill_check) and references related tools for further actions. It covers all necessary aspects for an agent to use the tool correctly.

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

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

Schema description coverage is 100% for both parameters, but the description adds significant context: example values for event slugs, seed questions for topics, and how each mode works. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between different modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning).' Also directs to alternative tool: 'For custom sizing use polymarket_fill_risk.'

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable transparency: caching at 1h, exclusion of Fed bets with reasoning, and detailed diagnostics for empty segments. It also explains edge calculation and slippage assumptions, which are crucial for correct invocation.

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

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

The description is very long (≈600 words) and contains detailed explanations of model families and algorithms. While well-structured with clear headings, it could be more concise; some details (e.g., exact alpha values per sport) might be better suited for external documentation.

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 documents the response structure (by_segment, diagnostics, edge fields) and explains all knobs and their effects. It covers caching, limitations (Fed bets), and how to interpret empty results, making it fully actionable for an agent.

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?

All 9 parameters have descriptions in the schema (100% coverage), and the tool description goes beyond by explaining practical usage, defaults, and edge cases (e.g., min_kelly skips small opportunities, min_partition_leg_kelly applies to per-leg Kelly). This adds significant value for correct parameter selection.

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

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

The description explicitly states it 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', with a clear use case: 'Built for "what should I bet on today"'. This distinguishes it from sibling tools like polymarket_arbitrage, as it focuses on Pipeworx disagreement and includes multiple model families.

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 identifies a clear usage scenario: 'agents discover opportunities without paging hundreds of markets', and explains when results may be empty and why (e.g., Fed bets excluded due to unreliable signal). However, it does not explicitly state when not to use this tool or compare it to alternative sibling tools, leaving some ambiguity.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: explains the response structure (tracked, expired, snapshot_dates), how decay is computed (based on |edge_pp_net|), and snapshot behavior (cache-miss triggers). This goes well 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 a clear opening sentence, then detailed response field explanations, and finally limitations. It is somewhat lengthy but every sentence adds value. Could be slightly more concise, but information density is high.

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 thoroughly documents the return format with fields like tracked[], expired[], snapshot_dates[] and their contents. It covers input parameters, behavior, and limits (TTL, snapshot gaps). The tool has simple inputs and the description provides all necessary context for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning: default values, max lookback, and the purpose of 'window' (snapshot family). It also clarifies the clamp range (2-30) despite saying 'max 30' in the description, which is a minor inconsistency but not misleading.

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: 'Edge persistence and decay telemetry' and the specific question it answers about edge age and trend. It distinguishes itself from siblings like `polymarket_edges` (raw edges) and `polymarket_arbitrage` (arbitrage opportunities) by focusing on time-series decay.

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 guidance on when to use the tool (e.g., comparing fresh vs. old wide edges) and notes limitations (history depth bounded by 60-day TTL, snapshot gaps). It does not explicitly list alternatives but implies its unique value. The sibling list offers alternatives if needed.

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 details the tool's behavior: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and gives a verdict (clean|degraded|cannot_fill). It warns about forced directional risk in basket mode. All disclosed behaviors are consistent with the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false).

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

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

The description is long but every sentence adds essential information. It is well-structured with section breaks (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that make it easy to scan. No redundant filler.

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

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

Given the tool's complexity (two modes, no output schema), the description is remarkably complete. It enumerates all return fields for both modes, explains edge cases (thin legs, forced directional risk), and provides usage thresholds. The lack of an output schema is fully compensated by the detailed textual output specification.

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

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

The input schema already describes all 4 parameters with 100% coverage, but the description adds significant semantic value by explaining how size_usd is interpreted differently in single-market vs basket mode (max spend vs target proceeds vs settlement notional) and providing default and clamp ranges. It also clarifies the side parameter's default behavior in basket mode (auto based on partition sum).

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 title 'Polymarket Fill Risk' and description 'Realizable-vs-theoretical edge check against live CLOB order-book depth' clearly state the tool's verb (check) and resource (fill risk). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk assessment tool.

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

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

The description explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear conditions for use. It also explains the two modes (single-market and basket) and when each is applicable, and warns about partial basket fills converting arb into directional risk.

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, idempotent), description details safety fields (compatibility_warning, temporal_alignment, skipped counters) that reveal tool's inner logic and failure modes. No annotation contradiction; description adds valuable behavioral 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?

Description is dense but well-organized with clear sections (modes, response, safety fields). Front-loaded with purpose. Some repetition in safety explanations could be trimmed, but overall effective.

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

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

Given no output schema, the description thoroughly explains the response format (leg prices, spreads) and all safety fields. Covers complex behavior like temporal alignment and leg matching. Fully equips agent to interpret results.

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

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

Schema coverage is 100%, but description adds meaning by explaining the interaction between parameters: topic auto-fetches, explicit overrides, and enumerates macro shortcuts. This enhances agent understanding beyond raw 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison. The verb 'spread' and resource naming are specific.

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

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

Provides explicit guidance on two modes (topic shortcuts vs explicit parameters) and explains when spreads are meaningful vs when warnings are triggered. Includes caution that pre-mapped topics often yield compatibility_warnings, setting realistic expectations. Effectively tells when to use and when not to.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds no extra behavioral context about rate limits, auth needs, or what happens. It neither contradicts nor enhances the annotations.

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

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

Very short, one sentence. However, it omits a verb and necessary detail, making it less effective. It is concise but at the cost of completeness.

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

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

Given it has an output schema, the description doesn't need to explain return values, but it still lacks context about the overall operation and scope. It states 'for a project' but doesn't clarify that it expects a project identifier or returns a list. Minimally adequate.

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 description does not mention the single required parameter 'project'. Schema description coverage is 0%, so the description should compensate but fails. The examples in the input schema provide some context, but the description itself adds no parameter 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 uses a noun phrase without an action verb, so it's unclear what the tool does (list? get?). It identifies the resource as 'outstanding maintenance problems for a project', which gives some clarity but doesn't distinguish from siblings like 'projects_search' or '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?

No guidance on when to use this tool vs. alternatives. With many sibling tools, the agent has no context for selection. No when-not-to or prerequisites 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?

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds that it returns 'all packages (per-repo)', providing some behavioral context. However, it does not disclose additional traits such as response structure or limitations, but the output schema exists to fill some gaps.

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, focused sentence that conveys the core purpose without unnecessary words. It is front-loaded and efficient, earning its place.

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

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

Given the tool's simplicity (one parameter, strong annotations, output schema), the description provides adequate context for basic usage. However, it lacks differentiation from sibling tools like 'repositories' or 'projects_search', which could be relevant for users deciding which tool to use.

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

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

With only one parameter 'name' and 0% schema coverage, the description provides examples ('firefox', 'curl') to illustrate usage. While it adds meaning by linking the parameter to a project name, it does not explain constraints or format beyond the name itself. The examples partially compensate for the lack of parameter 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 retrieves all packages for a project name, with an example. However, the phrase 'per-repo' is ambiguous and could be clarified. It distinguishes the tool from siblings like 'repositories' and 'projects_search' by focusing on packages for a single project.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It implies usage when you need packages for a project, but does not mention when not to use it or mention sibling tools like 'repositories' or 'projects_search' that might be more appropriate for other tasks.

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

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

Annotations already indicate read-only, idempotent, and non-destructive nature. The description adds behavioral context: pagination with up to 200 results per page and per-repo version data. This provides useful beyond-annotation details, though could elaborate on cursor-based pagination.

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

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

The description is a single, efficient sentence that front-loads the purpose and key details. Every part earns its place with no redundancy.

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

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

Given the tool's complexity (8 parameters, output schema present), the description covers the main behavior: search types, pagination limit, and return content. It could mention cursor parameters for pagination, but the output schema may provide additional context.

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

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

Schema description coverage is 75% (6 of 8 parameters documented). The description mentions filter types (name substring, maintainer, category, repo) but does not add specific syntax or format details beyond what the schema provides. For the undocumented parameters (category, maintainer), the description helps by listing them as filter options.

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: paginate or filter Repology projects by various criteria and return up to 200 project names with per-repo version data. It uses specific verbs (paginate, filter) and resource (Repology projects), distinguishing it from 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?

The description lists multiple filter criteria but does not provide explicit guidance on when to use this tool versus alternatives. Usage is implied but not directly stated, and no exclusions or alternative tools are 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?

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description aligns with by describing only retrieval/list. The description adds valuable context: scoping per identifier, the ability to list all keys, and relationships to siblings. 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 concise (3 sentences) and front-loaded with the main action. It efficiently covers purpose, usage, and scoping. No redundant or irrelevant content.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains both modes of operation (with key and without), scoping, and relationships to siblings. 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% (1 parameter). The schema already explains the parameter: 'Memory key to retrieve (omit to list all keys).' The description repeats this but adds no new parameter-level detail beyond usage context. 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 starts with 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument),' which clearly states the verb (retrieve/list) and resource (saved values/keys). It distinguishes itself from sibling tools like remember (save) and forget (delete), making the purpose unambiguous.

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

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

The description says 'Use to look up context the agent stored earlier' and gives examples (ticker, address, notes). It also mentions scoping and pairing with siblings, implying when to use remember/forget instead. However, it does not explicitly state when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds useful behavioral details: mark_read affects subsequent calls (only newer events), and the feed is persisted. No contradictions.

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

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

Four succinct sentences front-loading purpose, then parameters, followed by polling and alternative endpoint. Every sentence earns its place with no redundancy.

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

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

Given no output schema, description explains return fields (source, citation_uri, raw payload). Covers all parameters, filtering options, mark_read behavior, and polling note. Complete for a read tool with 5 optional params.

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?

All 5 parameters have schema descriptions (100% coverage). Description enriches with examples ('sec_8k' for type), format guidance (ISO timestamp for since), and behavioral impact (mark_read makes next call show newer). 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 starts with a clear verb 'Pull' and resource 'fired events from your subscription feed', and specifies what each alert carries (source, citation_uri, raw event payload). This distinguishes it from sibling tools like 'list_subscriptions' or 'subscribe'.

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

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

Provides clear usage context: filtering by type and since, using mark_read to manage read state, and polling suitability. Mentions alternative HTTP endpoint. Does not explicitly list when not to use or contrast with siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: parallel fan-out to sources, fallback mechanism (GDELT preferred, GNews on rate-limit/5xx), soft-failure for USPTO, and the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). No contradictions with annotations.

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

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

The description is a single paragraph but packs a dense amount of useful information. It could be slightly more structured (e.g., bullet points) but remains readable and front-loaded with the purpose. Every sentence earns its place with examples and fallback details.

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 explicitly states the return structure (changes[] grouped by source, total_changes count, URIs). It covers all three parameters, fallback behavior, and provides a clear comparison with entity_profile. For a tool with 3 required parameters and moderate complexity, this description is complete and self-sufficient.

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

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

Schema coverage is 100%, yet the description adds meaningful context for each parameter. For 'since', it provides ISO date and relative shorthand examples and a usage recommendation ('Use "30d" or "1m" for typical monitoring'). For 'type', it clarifies that only 'company' is supported. For 'value', it explains Ticker or CIK formats. This adds significant 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 purpose: returns a change feed for a company from multiple sources (SEC, GDELT/GNews, USPTO) within a given time window. It distinguishes from sibling tool entity_profile by specifying when to use the latter. The examples of queries ('What's new with X', 'latest on Y') make the purpose unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance. Examples of query formulations and fallback logic (GDELT→GNews) are given. Directly says 'Use entity_profile instead when you want the static profile' which clearly delineates from a sibling tool. This exceeds the minimum viability.

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 idempotentHint=true and destructiveHint=false; the description adds retention policy (persistent for authenticated users, 24-hour for anonymous) and scoping by identifier. 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 (three sentences) and well-structured: first sentence states purpose, second provides usage examples, third covers technical details. Every sentence adds value.

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

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

Given two parameters with full schema coverage, no output schema, and sibling tools, the description provides sufficient context for correct usage. It covers persistence, scoping, and pairing with recall/forget.

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 example key values ('subject_property', 'target_ticker', 'user_preference'), but does not significantly extend 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), and usage context (across conversation or sessions). It distinguishes from siblings by mentioning pairing with '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 clear when-to-use guidance: 'Use when you discover something worth carrying forward...' with concrete examples. It does not explicitly state when not to use, but the pairing with recall/forget implies alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it lists 'all' repositories but does not disclose additional behavioral traits like pagination or completeness. With robust annotations, the description provides marginal added value.

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

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

A single sentence that front-loads the action and resource, with no wasted words. Every element earns its place.

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

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

Given zero parameters and that an output schema exists, the description completely covers the tool's functionality. It specifies what is returned (names, family, counts) and the scope (all repositories).

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

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

The input schema has zero parameters and the schema description coverage is 100%. For a no-parameter tool, the baseline is 4, and the description correctly avoids adding parameter details since none exist.

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

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

The description clearly states the verb 'list' and the resource 'all package repositories indexed by Repology', providing examples (distros, BSDs, language ecosystems) and detailing the returned information (names, family, active/total package counts). This distinguishes it from sibling tools like 'search_within' and 'problems'.

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 for broad listing of repositories but provides no explicit guidance on when to use it versus alternatives like 'search_within' or 'problems'. Usage context is clear but exclusion criteria are absent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing internal cascading through multiple lookup endpoints and providing citation URIs, which goes well beyond what annotations convey.

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

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

The description is thorough and front-loaded, but slightly long at 3 sentences. Every sentence adds unique value; however, the examples could be condensed without losing clarity.

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

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

For a tool with 2 required parameters and no output schema, the description fully covers the return structure for both entity types, including citation URIs. It leaves no gaps in understanding what the tool does or returns.

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

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

Schema coverage is 100%, but the description enriches parameter understanding by explaining what each type returns (e.g., company returns ticker, CIK, company_name) and giving concrete examples for values (AAPL, 0000320193, ozempic).

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: resolving a name to an official identifier, with examples like 'What's the ticker for...' that match common agent queries. It distinguishes itself by covering multiple entity types (company, drug) and the return payloads, differentiating it from sibling tools 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?

The description instructs to 'Use FIRST whenever you have a name but need an ID,' giving clear usage context. It lacks explicit when-not-to-use or alternatives, but the purpose is so specific that the intended use case is unambiguous.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific fields. No contradictions; adds value beyond annotations.

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

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

The description is three sentences, densely packed with purpose, method, example, and output. Every sentence adds value, and it is front-loaded with the core action.

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 explains the output structure (ranked list with score, confidence, signal density). It covers what the tool does, how it works, and the output format, making it sufficiently 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%, so the schema already documents parameters fully. The description adds minimal extra meaning: it notes that the first entity is the 'subject' for narrative. 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 uses specific verbs and resources: 'Compare AI visibility across multiple entities side-by-side' and explains it uses ai_visibility_check. It clearly distinguishes from siblings by noting it is for multiple entities vs single entity check (ai_visibility_check) and mentions ranking.

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 states 'Useful for competitive AI-marketing audits' and gives an example question, providing clear context. It does not explicitly state when not to use, but the purpose implies it's for multi-entity comparison, differentiating from single-entity tools.

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

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

Description adds significant behavioral detail beyond annotations: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed lists timeouts. No contradiction with readOnlyHint and idempotentHint 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 fairly long but each sentence serves a purpose, front-loading core functionality and then detailing behavior and limitations. Could be slightly more concise but effective overall.

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

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

Given the tool's multi-source composite nature, the description covers all critical aspects: return fields, per-advisory details, links, alternative versions, failure handling, and timing behavior. Adequately compensates for lack of output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining default version behavior (latest when omitted) and acceptance of scoped packages, which enhances clarity beyond schema descriptions.

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

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

Description explicitly states 'composite check' combining deps.dev and bundlephobia, with specific verb 'scan' and resource 'dependency'. Clearly distinguishes from sibling tools by specifying NPM ecosystem focus and composite nature.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies NPM-only v1 and points to alternatives for other ecosystems, giving comprehensive usage 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?

The description discloses internal mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. These details go beyond annotations (readOnlyHint, etc.) and inform the agent about behavior constraints and edge cases.

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 (under 100 words) and well-structured: front-loaded with purpose, then usage guidelines, behavioral details, and parameters. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains return values (top-N passages with offsets and scores). Input constraints, internal algorithm, and use case are fully covered, making the tool self-contained for the agent.

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 beyond schema properties: max char limit for text, natural-language query examples, and default/range for limit. This helps the agent construct correct invocations.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb (search), resource (fetched record), and distinguishes from siblings by referencing 'ask_pipeworx_grounded' and contrasting with whole-document approaches.

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: 'Use when the record is too big to cram into the prompt.' It also suggests pairing with another tool. However, it does not explicitly state when NOT to use or list excluded scenarios, which would improve the 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?

Discloses key behaviors (OAuth requirement, SMS cap, webhook signing once) beyond annotations, though idempotency hinted by annotation is not mentioned in text. No contradictions with annotations.

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

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

Single paragraph is dense but efficient; could benefit from bullet points for readability, but no wasted sentences.

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

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

Covers return value, auth, types, delivery details; missing error cases or explicit idempotency but sufficient for agent invocation.

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

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

Adds substantial value beyond schema with detailed type-specific examples and delivery constraints, despite 100% schema coverage.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource, plus examples of supported types, distinguishing it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides context on OAuth requirement and delivery channels, but does not explicitly contrast with alternatives like 'list_subscriptions' for viewing existing subscriptions or 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds that it returns example questions with exact tool calls and argument shapes, and that it can be called with or without a topic. 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 well-structured with alternative questions, output details, and usage instructions. It is a bit lengthy but every sentence contributes meaning. Could be slightly more concise, but still effective.

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

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

Given the strong annotations and single optional parameter, the description fully covers when and how to use the tool, what output to expect (category-bucketed questions with tool calls), and the rationale for using it. No missing 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% and the description adds significant value by listing example values (finance, pharma, etc.) and explaining that omitting the topic gives a cross-category spread. This goes beyond what the schema provides.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, serving as the onboarding entry point. It distinguishes itself from siblings like ask_pipeworx, entity_profile, etc., by positioning itself as the first-stop discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains how to call with no arguments for full spread or pass a topic to focus. It also lists related meta-tools (ask_pipeworx, entity_profile, compare_entities) as 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?

Disclosure of ownership enforcement, deactivation (not deletion), and persistence of historical events via recent_alerts adds significant value beyond the annotations. Annotations already indicate idempotentHint=true and destructiveHint=false; the description aligns and elaborates helpfully.

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 action and key constraint, with no superfluous information.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description effectively covers purpose, usage constraint, behavioral impact, and even references a sibling tool (recent_alerts) for context. It is fully sufficient for an agent to use correctly.

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

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

Schema description coverage is 100% for the single parameter 'id'. The description does not add extra meaning beyond what the schema already provides ('Subscription id (uuid) returned by subscribe.'), so a baseline of 3 is appropriate.

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

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

The description uses the verb 'Cancel' matching the tool's title 'Unsubscribe', specifies the action on a subscription by id, and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation instead of deletion.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use the tool. Also explains that the row is deactivated not deleted, implying it should be used when you want to cancel without losing historical data. Does not provide explicit alternatives but implies recent_alerts for history.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are complemented by description detailing return types (verdict, structured form, actual value, citation) and data sources (SEC EDGAR + XBRL). 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 moderately sized and front-loaded with usage examples. Every sentence adds value, though it could be slightly more concise.

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

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

Given a single parameter with full schema coverage, no output schema, and low complexity, the description fully covers the tool's behavior, scope, and output characteristics.

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% for the single parameter 'claim'. The description adds valuable context on supported claim types (company-financial) and example phrasing, going beyond the schema description.

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

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

The description uses specific verbs and resources (e.g., 'verify the claim that…', 'natural-language claim verification') and clearly distinguishes from siblings by noting it replaces 4-6 sequential calls, making its purpose unambiguous.

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

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

Explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and provides context on scope (company-financial claims) and efficiency gains over alternative approaches.

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