Estat Japan

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 behavioral details: it explains the probing mechanism, the per-model response structure (score, confidence, signals, raw_response), and the combined view. This goes beyond annotations without contradicting them.

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

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

The description is concise (3 sentences) and well-structured: first sentence states the primary purpose, second sentence adds model details, third sentence mentions output structure and use cases. No redundant or extraneous information.

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

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

Given the tool has 4 parameters, no output schema, and annotations are present, the description provides sufficient context. It explains the output format (per-model and combined view) and the use cases. It could be slightly more explicit about the scoring algorithm, but the openWorldHint reduces the need for that. Overall, it's complete enough 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 are fully described in the schema (100% coverage). The description adds extra context: it explains the default model, the need for _apiKey with 'anthropic', and the purpose of 'context' for disambiguation. This additional information aids understanding beyond the schema.

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

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

The description clearly states the tool's purpose: probing LLMs for brand knowledge and scoring visibility (0-100). It specifies the default model and optional Anthropic integration, and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains how to use the tool with different models (default free model, BYO key for Anthropic). While it doesn't provide explicit when-not-to-use guidance, the context is clear and helpful for an agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds that it routes to tools and fills arguments automatically, returning structured answers with citations. No contradictions, but could mention failure modes or rate 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 front-loaded with the key directive 'PREFER OVER WEB SEARCH' and organized with examples. It is somewhat long but every sentence serves a purpose. Minor redundancy in listing aliases but overall efficient.

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

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

Given the tool's complexity (routing to 3,436 tools) and no output schema, the description explains the return format (structured answer with citation URIs). It could mention error handling or limitations, but is sufficient for typical 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?

Schema coverage is 100%, so baseline is 3. The description adds usage context and examples but does not provide additional meaning beyond the schema for each parameter. The schema already describes aliases well.

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 routes questions to one of 3,436 tools across 780 verified sources and returns structured answers with citations. It explicitly contrasts with web search, providing a distinct purpose. The verb 'routes' and resource 'pipeworx' 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?

The description explicitly says 'PREFER OVER WEB SEARCH' for specific data types and lists many example queries. It gives clear context for when to use (factual questions about entities, events, numbers) and implies not to use for open-ended reasoning. The examples provide concrete guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral traits: extra LLM call cost, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the extraction process using only tool result. 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?

Description is moderately lengthy but every sentence provides essential context: purpose, comparison, return format, refusal reasons, and cost trade-off. Front-loaded with core purpose. Could trim some minor details but overall efficient.

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

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

Given the tool's complexity (6 param aliases, rich behavioral model) and no output schema, the description fully covers return format on success and failure, refusal reasons, and guidance on when to use. Contextually complete for high-stakes 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?

Schema coverage is 100% (all 6 params described in schema). Description adds value by listing all aliases (q, text, input, query, prompt) and clarifying that 'question' accepts natural language. Above baseline 3 due to helpful alias documentation.

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

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

The description states 'Hallucination-resistant answer mode for high-stakes reads' and details the return format with answer, evidence, confidence, etc. It clearly distinguishes from sibling ask_pipeworx by noting the extra LLM call and grounded behavior.

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

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

Explicitly advises use when 'an answer will be quoted, cited, or acted on, and the agent must not invent facts' and suggests preferring ask_pipeworx for casual lookups. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) are already favorable, but the description adds extensive behavioral details beyond them: fan-out examples for each classifier, resolver contract with match confidence levels, parent event extractor, news fallback mechanisms, safety handling for low-confidence and closed markets, and tradeability warnings. 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 relatively long but well-structured. It front-loads the primary purpose and use cases in the first few sentences. Subsequent paragraphs add detailed behavior without redundancy. Every sentence provides necessary information; no filler. Could be slightly more concise, but density is justified by 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?

Given the tool's complexity (multiple classifiers, fan-outs, resolver, parent events) and the absence of an output schema, the description thoroughly explains all response shapes: market fields, analysis with model probabilities and warnings, evidence keys, resolver contract with match confidence and alternatives, parent event extraction, news fields with fallback handling, and safety behaviors. Complete enough 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 coverage is 100% with descriptions for all three parameters. The description adds value by explaining the 'market' parameter can be slug, URL, or question text; elaborates on 'depth' enum values (quick vs thorough); and clarifies 'include_raw' size implications. Provides concrete examples that enhance understanding beyond the schema alone.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and unique capability (single-call fan-out). Examples of inputs (slug, URL, question text) reinforce clarity. Distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by being a comprehensive research 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?

Provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Describes when to inspect market_match_confidence before trusting analysis, and warns that low-confidence matches suppress analysis. However, does not explicitly state when not to use this tool or name alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: pulls latest 10-K data, handles off-calendar fiscal years (with examples), returns paired data with citation URIs. No contradiction; it complements annotations well.

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

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

The description is thorough but somewhat lengthy. However, it front-loads the purpose with trigger phrases and every sentence adds value. It could be slightly more structured, but overall it's efficient and not wasteful.

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

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

With only 2 parameters and no output schema, the description fully covers input (examples, constraints, behavior), processing (data sources, fiscal year handling, sorting), and output format (paired data, citation URIs). No gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'type', it explains what each enum value retrieves (specific financials for company, counts for drug). For 'values', it provides examples (tickers, drug names) and clarifies sorting by primary metric. This is beyond what the schema offers.

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 does side-by-side comparison of 2–5 companies or drugs, with specific verbs like 'compare', 'rank', 'head-to-head'. It distinguishes from siblings like 'entity_profile' by emphasizing multi-entity comparison. It names data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and lists metrics (revenue, net income, etc.).

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. It defines when to use (comparing 2–5 entities) and implies not to use for single entities. It even quantifies the efficiency gain ('Replaces 8–15 sequential lookups'), providing 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and that each result is ready to call directly. No contradictions.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. It logically flows from purpose to usage context to details about return value. 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?

Given the tool's low complexity (discovery, read-only, idempotent) and the presence of annotations, the description is complete. It explains what it does, when to use, what it returns, and provides examples. Output schema is not needed as the description describes the return format 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% with clear descriptions for each parameter. The description adds context by explaining that the query parameter is a natural language description and lists its aliases again. It reinforces the discovery use case, 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (discover, browse, search) and resource (tools), and distinguishes itself from sibling tools by being the first tool to call when exploring available tools. The list of example domains provides concrete scope.

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

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

Explicit guidance is given: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly tells the agent when to use this tool versus others. The description also implies that if you already know the specific tool, you could skip this step.

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 behavior such as fanning out across multiple sources, specific return fields (cik, recent_filings with URIs, fundamentals, patents with sunset note, news via fallback, LEI), and soft-fail for patents. This significantly enriches transparency beyond the annotations.

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

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

The description is a single efficient paragraph, front-loaded with example queries, then states purpose and details. Every sentence serves a purpose with no unnecessary words.

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

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

Given the tool's complexity (multiple sources, fields, fallback, API sunset) and lack of output schema, the description covers input constraints, return fields, and notable behaviors. Minor improvement could be more precise structure of nested fields (e.g., recent_filings as an array).

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

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

Schema coverage is 100% with each parameter described. The description adds concrete examples ('ticker AAPL', 'zero-padded CIK'), clarifies that names are not supported, and explains the type parameter is currently limited to 'company'. This provides meaningful usage guidance 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 starts with example user queries and explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from chaining individual lookups and from sibling tools like resolve_entity by noting when to use this tool instead.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states to use resolve_entity if only a name is given, providing clear when-to-use and when-not-to-use conditions with an alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no new behavioral details beyond what annotations already 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?

Two efficient sentences: first states the action, second gives usage context. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose and usage. No missing 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?

Input schema at 100% coverage already describes the 'key' parameter. Description does not add extra meaning 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 action ('Delete a previously stored memory by key') and distinguishes from related tools like 'remember' and 'recall'.

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

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

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

The description explains the internal steps: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' Annotations already declare the tool as read-only, open-world, and idempotent; the description adds behavioral detail beyond that without contradiction.

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

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

Three sentences, no redundant information. The key action is stated first, followed by behavior and then use cases. Each sentence adds value.

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

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

The description fully covers the tool's behavior, parameters, and output format despite lacking an output schema. It explains what the output is (standard markdown format, ready for site-root/llms.txt) and the constraints (max 50 links).

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds slight context (e.g., 'default 25, max 50' for max_links) but largely mirrors 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 states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly differentiates the tool's purpose from sibling tools by focusing on a unique output format and use cases.

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

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

The description provides explicit use cases ('getting a client's site indexed...', 'drafting for your own project', 'auditing how an AI crawler would see a competitor'), giving clear context. It does not explicitly state when to avoid using, but the purpose is self-contained.

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 comprehensively declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly safe and side-effect free. The description adds 'fetch observations' which aligns with these annotations. It does not contradict annotations or add significant behavioral context beyond what is already present.

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

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

The description is a single sentence that conveys the core purpose efficiently. No wasted words. It is front-loaded with the key action. Could be slightly expanded without harm, but as is it is 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 the presence of an output schema and 100% parameter coverage, the description does not need to explain return values or all parameters. However, it omits mention of pagination support (via start_position and limit) and does not clarify typical usage patterns. For a data retrieval tool, slightly more context would be beneficial, but it is 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?

Schema coverage is 100% with detailed descriptions for all parameters, including examples. The description's mention of 'optionally filter by dimension codes' adds minor context but does not provide meaning beyond what the schema already explains. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'fetch' and the resource 'observations from a stats table', and optionally filtering by dimension codes. This is specific enough to distinguish from sibling tools like 'search_stats' which appears to search the data catalog rather than retrieve observations. However, it could be more explicit about the exact scope of data retrieved.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when filtering is beneficial, or contrasts with 'search_stats' which likely is used for discovery. An agent would need to infer usage from 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying that it fetches 'dimensions and code lists,' providing specific context about what metadata is returned.

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, clear sentence that front-loads the purpose with no unnecessary words. Every part of the description is informative.

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

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

Given the tool's low complexity (2 parameters, output schema present), the description sufficiently explains what the tool does. The output schema handles any details about return values, so no further description is needed.

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

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

The input schema has 100% coverage with clear descriptions for both parameters. The description does not add additional detail beyond the schema, which is acceptable but provides no extra value.

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

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

The description states a specific verb ('fetch') and resource ('dimensions and code lists for a stats table'), clearly distinguishing it from sibling tools like get_data (which retrieves data) and search_stats (which searches for stats tables).

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 explicit guidance on when to use this tool vs alternatives, but the context of siblings and the verb 'fetch' imply it is for metadata retrieval, not data retrieval. The annotations confirm it is read-only and idempotent, which is helpful but not explicitly stated in the description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds that it returns 'high-level' catalog items (table groupings), which gives context beyond annotations but does not elaborate on pagination or filtering behavior. Value added is moderate.

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 one sentence (7 words), front-loaded with the verb, and contains zero extraneous information. Every word earns its place. Ideal conciseness.

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 that an output schema exists (context signals), the description need not explain return values. The tool has 4 optional parameters, all documented in the schema. The description's brevity is sufficient for a browsing tool, but slightly more context about what 'high-level' means could be added. Still, it is complete enough.

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

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

Schema coverage is 100%, so each parameter (lang, limit, query, start_position) is already described in the schema. The description does not add any additional meaning or usage notes for the parameters, so baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'browse' and resource 'high-level data catalog (table groupings)', clearly distinguishing it from sibling tools like get_data (which retrieves actual data) or search_stats (which searches statistical data). It answers what the tool does precisely.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_data or search_stats. There is no mention of prerequisites, use cases, or exclusions. Without this, an AI agent may select the wrong 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 and idempotentHint, so the safety profile is clear. The description adds context about active vs. inactive subscriptions and the return fields, which is valuable beyond annotations.

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

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

Two sentences, front-loaded with action and return info. Every sentence serves a purpose 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?

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage context, return fields, and parameter behavior. 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%, but the description adds meaning by emphasizing 'active' subscriptions and linking to the include_inactive parameter, clarifying default behavior. This exceeds the baseline of 3.

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 'List the caller's active subscriptions' with a specific verb and resource, and lists returned fields. It clearly distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide when to invoke it versus 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 show readOnlyHint=false and destructiveHint=false, which align with the description's 'tell' action. Description adds rate limiting (5 per identifier per day) and that it doesn't count against quota. Could mention persistence or effect on roadmap more explicitly, but overall adequate.

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 front-loaded purpose. Every sentence is useful, but the description is slightly longer than necessary. Could combine some sentences 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?

Given 3 parameters (1 enum, 1 nested object, 1 free text) and no output schema, the description covers all needed information: parameter usage, rate limits, free cost, and context about how feedback is used ('team reads digests daily'). Complete for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value by explaining each parameter's purpose with examples (type enum has detailed descriptions, message has formatting guidelines, context is optional). Especially helpful: 'don't paste the end-user's prompt' for the message field.

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

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

Clearly states the tool is for giving feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. The verb 'tell' and resource 'Pipeworx team' are specific, and it distinguishes itself from the sibling tools (which are all query/analysis tools) by being the only feedback mechanism.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt, describe in terms of tools). Provides rate-limit info and states it's free. Clear and actionable 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=true, idempotentHint=true, destructiveHint=false. Description adds context about caching (5min-1h), data source (CF analytics-engine), and privacy (no PII), exceeding annotation 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?

Description is concise (3 sentences) with front-loaded return value, followed by use cases, then implementation details. Every sentence adds value with 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?

Without output schema, description explains exactly what is returned (top tools, top packs, total call volume) and mentions caching, data source, and privacy. Covers all necessary context for an aggregated trending tool.

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

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

Schema coverage is 100% with an enum and description for 'window'. Description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand' and mentions default (24h), which is beyond the schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over configurable windows. It uses specific verbs ('returns') and resource ('top tools, top packs, total call volume'), and is distinct from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Lists three explicit use cases: discovering hot data sources, confirming canonical choice, and checking alignment with agent needs. Provides clear when-to-use guidance without needing exclusion statements.

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 rich behavioral context: parameter requirements, algorithmic checks (Jaccard similarity threshold, partition filter), response structure, and placeholder filtering, fully complementing the annotations without contradiction.

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

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

The description is detailed and well-structured, with distinct sections for event mode and topic mode. While every sentence adds value, the length could be slightly reduced without losing clarity. Front-loading with the requirement and usage guidance is 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 tool's complexity and lack of output schema, the description is comprehensive. It covers input modes, algorithmic details (monotonicity, partition sum, Jaccard similarity, placeholder filter), and expected response fields. Minor omissions (e.g., error handling) prevent a perfect score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by providing concrete examples (e.g., 'fed-decision-may-2026'), noting that full Polymarket URLs are accepted, and explaining how topic triggers cross-event searches, thus enhancing parameter understanding.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, 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 recommends event mode for a specific market and topic mode for cross-event scanning, explaining that cross-event catches patterns single-event misses. It also warns that calling with no args fails. However, it does not compare to sibling tools like polymarket_edges, which would further aid selection.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds substantial behavioral detail: three model families, edge calculations with slippage, diagnostic outputs, and 1-hour KV caching. No contradictions exist, and the description far exceeds 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?

The description is lengthy but well-structured, with front-loaded purpose and clear segmentation. Every sentence adds value, though minor tightening could improve conciseness. The structure is effective 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?

The description is exceptionally complete, covering the output structure (by_segment, _diagnostics), knobs, caching, and edge cases like Fed bets. Without an output schema, this is necessary and well-executed.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter understanding, especially for tradeable-edge knobs (e.g., min_partition_leg_kelly explanation of partition-specific filtering). It adds value beyond the schema without redundancy.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb, resource, and unique value, differentiating it from sibling tools like polymarket_arbitrage by focusing on Pipeworx-driven edge detection.

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

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

The description provides explicit usage context: 'Built for "what should I bet on today"' and details filtering knobs and the exclusion of Fed bets. While it doesn't directly compare to siblings, the purpose is clear enough to guide appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and detailed skipped cross-type/subtype counters. 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 dense and comprehensive but somewhat verbose; it could be streamlined while retaining key information. The front-loading of the main purpose is effective, but some detail could be 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 no output schema, the description fully explains the response format (leg prices, spreads, safety fields) and covers all important aspects like compatibility, temporal alignment, and skipped counts, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing all 10 topic shortcuts and explaining that explicit parameters override topic-mapped sides, enhancing understanding beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket, listing two modes (topic and explicit). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on the same resolving question across venues.

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 explains when to use topic mode (pre-mapped macros) vs explicit mode (custom pairings), and warns that most pre-mapped topics return compatibility warnings, guiding the agent to not assume tradeability.

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. Description adds context: scoped to identifier (anonymous IP, BYO key hash, account ID) and pairing with remember/forget. Could mention behavior on missing key, but overall good transparency.

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

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

Three sentences front-loaded with the main action, followed by examples and scope. Every sentence adds value without redundancy. Highly efficient.

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

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

No output schema, but description clarifies returns (value for key, list of keys if omitted). Also covers scope and sibling relationship. Could briefly mention response format (e.g., returns string or list), but sufficient 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?

Schema coverage is 100% with one optional 'key' parameter. Description adds meaning by explaining omitting key lists all keys, and gives concrete examples of key values (target ticker, address). This goes 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 clearly states the tool retrieves a saved value by key or lists all keys if omitted, using specific verbs 'retrieve' and 'list'. It provides examples of stored data (target ticker, address, research notes) and distinguishes from sibling tools 'remember' (save) and 'forget' (delete).

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Mentions scope to identifier and pairing with remember/forget. Provides clear guidance on when not to need it (re-deriving) and alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that mark_read flags events as read (stateful consumption) and that polling works fine, providing extra behavioral context beyond annotations.

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

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

Single paragraph of ~120 words, front-loaded with purpose. It is dense but efficient, with little waste. Could be slightly more structured but 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?

Returns format explained, mark_read behavior clarified, and alternative access provided. Missing details on unread_only parameter but schema covers it. Overall complete for a read-only list tool.

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

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

Schema provides 100% coverage with descriptions for all 5 parameters. The description mentions type, since, and mark_read but repeats schema info without adding new semantics like constraints or defaults. Baseline score applies.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts with specific fields. The verb 'Pull' and resource 'fired events' are specific. However, it does not explicitly distinguish from sibling tools like list_subscriptions or get_data, relying on context.

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

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

No explicit guidance on when to use this tool versus alternatives. Mentions polling works and the same feed is available via a URL, but does not compare to siblings or specify conditions for use.

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

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

Beyond annotations (readOnly, idempotent, etc.), description details parallel fan-out to SEC, GDELT→GNews, USPTO with fallback logic, return format (changes grouped by source + count + URIs), and parameter behavior. 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?

Description is a single dense paragraph but every sentence adds value. Could benefit from bullet points for readability, but no wasted words.

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

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

Despite no output schema, description fully explains return structure (changes[], total_changes, citation URIs) and details each data source and fallback. Sufficient for agent to understand 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 has 100% coverage, but description adds value: explains 'since' accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y'), 'value' is ticker or CIK, and 'type' is restricted to 'company'. Provides usage 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 provides a 'change feed for a company in the last N days/weeks/months' and gives intuitive usage examples like 'what's new with X'. It distinguishes from the sibling 'entity_profile' by specifying when to use that tool instead.

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 (queries about recent changes) and when not to ('Use entity_profile instead when you want the static profile'). Also describes fallback behavior, aiding correct invocation.

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 idempotent and non-destructive hints. Description adds scoping by identifier, persistence details (24-hour for anonymous), and pairing with recall/forget. 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 with efficient wording, front-loaded with purpose and usage. No wasted words.

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

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

Given 2 params, no output schema, and good annotations, the description covers usage, behavior, retention, and sibling tools. Complete for the tool's complexity.

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

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

Schema covers both parameters with descriptions. Description adds context about key-value pair scoping and examples of keys, providing 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?

Clearly states the tool saves data for reuse later with specific examples (resolved ticker, address, preference). Distinguishes from siblings '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?

Explicitly advises when to use (discover something worth carrying forward) and pairs with recall/forget. Mentions scoping and retention duration for different user types.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it cascades through multiple lookup endpoints internally, returns specific fields (e.g., ticker, CIK, RxCUI), and provides citation 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 well-structured with examples and bullet points for supported types. It is slightly verbose but front-loaded with key usage information. Every sentence adds value, though minor redundancy (e.g., repeating 'pipeworx://' URIs) could be trimmed.

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 (2 parameters, no output schema), the description is fully complete. It explains input formats, output fields, internal behavior, and even provides citation URIs. There are no gaps in understanding how to use the tool.

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

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

Schema coverage is 100%, and the description adds significant meaning: it explains what each parameter accepts (e.g., 'value' can be ticker, CIK, or name for company; brand or generic name for drug) and details the return fields for each type, which goes 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 defines the tool's purpose: resolving a user-spoken name to a canonical/official identifier. It provides concrete examples ('ticker', 'CIK', 'RxCUI') and distinguishes supported types (company, drug) with specific outputs, making it 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 explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID.') and mentions that it replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or mention alternative tools among the siblings, which would improve 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 details beyond annotations: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns ranked list with score/confidence/signal density. Annotations already indicate read-only and idempotent; description aligns and enriches.

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

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

Four sentences, front-loaded with main purpose. Every sentence is informative and efficient. No redundancy or fluff.

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

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

Covers purpose, usage, output structure (ranked list with score/confidence/signal density). Mentions constraints (2-8 entities) not in schema. Lacks error handling or edge cases, but sufficient for typical 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?

Schema coverage is 100%, so baseline is 3. Description adds value: explains first entity is subject, context disambiguates names, models default vs Anthropic. 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing it from sibling ai_visibility_check (single entity) and compare_entities (more generic). Provides a concrete use case example.

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

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

Explicitly says useful for competitive AI-marketing audits and provides an example. Lacks explicit when-not-to-use or alternative tool mentions, 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?

Annotations already suggest safe, idempotent, read-only behavior. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 multi-sentence but each sentence adds value. It front-loads the composite nature and then details returns and edge cases. Slightly dense but efficient; no wasted words.

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

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

No output schema exists, so the description fully explains return fields (summary block, advisories, links, versions) and error behavior (partial failures). Given the tool's complexity, this is 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 is 3. The description adds that scoped packages are accepted and that version defaults to latest, but the schema already mentions the default. The scoped package clarification is minor extra value.

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

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

The description starts with a clear action: 'Composite 'should I add this npm package to my project' check'. It specifies the resource (npm package) and the composite nature across deps.dev and bundlephobia, distinguishing it from sibling tools like 'search_stats' or 'entity_profile' that are more generic or focus on other ecosystems.

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 whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding agents to alternative tools.

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

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

Annotations already provide read-only and idempotent hints. The description adds that it returns IDs and names, which is useful but not critical beyond the schema. 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?

Two sentences, no wasted words. Front-loaded with purpose and immediately useful guidance on output usage.

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

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

Given the tool's complexity (4 params, all described, output schema present), the description is complete. It covers the function, output, and downstream usage without needing to repeat return value details.

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

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

Schema description coverage is 100%, so the description does not need to add parameter details. It does not add extra semantics beyond what the schema provides, meeting the baseline.

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

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

Clearly states the action ('Search e-Stat statistical tables') and the result ('Returns IDs and names for tables matching the query'). It also distinguishes from siblings like get_data and get_metadata by specifying the output usage.

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

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

Provides clear context on when to use (searching for tables) and how to use the results with IDs. Lacks explicit exclusions but the workflow is well-defined.

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 (all read-only, idempotent, etc.), the description provides rich behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation, character offsets for verification, and top-N passages. No contradictions with annotations.

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

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

The description is front-loaded with the purpose and is well-organized, but it is a bit lengthy with implementation details (embedding model, window size). Each sentence adds value, but some could be merged for brevity.

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

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

Without an output schema, the description adequately explains return values (top-N passages with offsets and scores). It covers input limits, pairing guidance, and truncation behavior. The tool is moderately complex, and the description addresses all key aspects.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by providing examples for 'query' (e.g., 'supply-chain risk') and clarifying the 'text' parameter's max length and purpose. It also explains the return format implicitly, adding context beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs and resource (e.g., 'semantic search INSIDE a fetched record'). It distinguishes from sibling tools like 'ask_pipeworx_grounded' by mentioning pairing, and it provides concrete examples (SEC 10-K body, article).

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 tells when to use this tool: when the record is too big for the prompt. It also suggests pairing with 'ask_pipeworx_grounded'. However, it does not explicitly state when not to use it or list alternative tools for different scenarios.

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 significant behavioral context beyond annotations: account requirement, type-specific parameters, delivery constraints (SMS cap, email), and return value. 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?

Dense but well-structured information. Front-loads core purpose. Each sentence adds value, though slightly lengthy. No redundant 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?

Covers all necessary aspects for correct usage: account requirement, types, parameters, delivery options, and constraints. No output schema, but description compensates with return info.

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 examples and constraints for each parameter, exceeding schema detail. Delivers meaningful extra guidance.

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

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

Clearly states it creates a proactive monitoring subscription and returns an ID. However, it does not explicitly distinguish from siblings like list_subscriptions or unsubscribe, though the purpose is unambiguous.

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

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

Provides account requirements and lists supported types, but does not explicitly state when not to use or suggest alternatives. The context is clear but lacks explicit 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?

The description goes beyond annotations by revealing ownership enforcement and that the row is deactivated rather than deleted, preserving historical events. This adds meaningful behavioral context that annotations (readOnlyHint=false, destructiveHint=false) alone do not 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 two sentences long, front-loaded with the core action, and every sentence adds value. It is concise without sacrificing 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 simple tool with one parameter, full schema coverage, and annotations, the description provides sufficient context: the cancellation action, ownership constraint, deactivation effect, and a pointer to recent_alerts for historical data. It is 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?

The schema already describes the 'id' parameter as a uuid returned by subscribe, with 100% coverage. The description merely restates 'by id,' adding no new semantics for the parameter. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the action and the resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and adds behavioral details about ownership and deactivation.

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 context on when to use the tool: to cancel a subscription by id. It explains ownership enforcement, implying the agent can only cancel its own subscriptions. However, it does not explicitly state alternatives or when not to use it, so it receives a 4.

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, open-world. Description adds return format (verdict, extracted form, actual value with citation, percent delta) and mentions replacing 4-6 sequential calls, enhancing transparency 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?

Front-loaded with trigger phrases, well-structured, and each sentence adds value. Slightly long but efficient for the information conveyed.

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?

Single-param tool with full schema coverage and rich annotations; description covers purpose, domain, return values, and efficiency benefit. No output schema, but description compensates.

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

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

Schema coverage is 100% with a good description for 'claim'. Description reinforces with natural-language examples, adding value beyond the schema. Baseline 3, improved by contextual 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?

Description states 'natural-language claim verification against authoritative sources' with specific trigger phrases and domain (company-financial claims via SEC EDGAR + XBRL), clearly distinguishing it from sibling tools like resolve_entity or search_stats.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain. Does not mention when not to use or alternative tools, but the context is clear.

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