Censtatd Hk

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: default model is Workers AI Llama-3.3-70b (free), optional Anthropic probing with BYO key, and return structure (score, confidence, signals, raw_response). 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 (4 sentences), well-structured, and front-loaded with the core action. Every sentence adds essential information without redundancy.

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

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

Given the tool's complexity (multi-model, optional API key, scoring, context), the description covers key aspects adequately. It explains the return format and use cases, though it could briefly distinguish from the similar sibling scan_competitor_ai_presence.

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 parameters. The description enhances understanding by explaining the default model, the purpose of _apiKey for Anthropic, and how context helps disambiguate. This adds meaning 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: probe LLMs for AI visibility and score it 0-100 per model. It specifies the verb 'probe' and resource 'LLMs', and distinguishes from siblings by focusing on AI visibility scoring rather than general entity profiles or comparisons.

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 specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), giving agents clear context for when to apply the tool. However, it does not explicitly mention when not to use it or contrast with sibling tools like scan_competitor_ai_presence.

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, covering safety and side effects. The description adds context about routing and citations but does not disclose other behaviors like performance, error handling, 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 a single paragraph but is well-structured: key instruction first, then domains, usage triggers, and examples. It is informative without being overly verbose, though it could benefit from bullet points for 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 the complexity and lack of output schema, the description covers when to use, input expectations, and output format (structured answer with citation URIs). It could detail the response structure more, but the core completeness is achieved.

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 aliases for the question parameter. The description adds value by clarifying the appropriate input (factual questions), giving examples, and specifying the preference over web search—going beyond the schema's property 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: answering factual questions by routing to over 3,600 tools across 860 sources, with a preference over web search. It lists specific domains (SEC, FDA, economic stats, etc.) and contrasts with web search, providing a distinct identity.

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

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

The description explicitly instructs to prefer this tool over web search for factual questions and provides specific trigger phrases ('what is', 'look up', 'find', etc.) with examples. It lacks explicit exclusions or references to sibling tools but gives a strong contextual framework.

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 show readOnlyHint=true, idempotentHint=true. The description adds valuable context about refusal reasons (not_in_source, no_tool_match, etc.), the exact output format, and the cost of an extra LLM call. 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 dense but well-structured: purpose, behavior, output format, use case, and trade-off with sibling. Every sentence adds value without repetition. Front-loaded with key 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?

Despite no output schema, the description fully specifies the return object (answer, evidence, confidence, source, etc.) and all possible refusal reasons. With 100% parameter coverage and detailed behavioral disclosure, the description is 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% (all 6 params documented, including aliases). The description mentions 'question' and aliases but adds no meaning beyond 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains that it routes queries through the same system as ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from ask_pipeworx by noting the extra LLM call and the use case for verifiable answers.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists examples like financial verdicts, legal claims. Also advises 'prefer ask_pipeworx for casual lookups.' No 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond, detailing classifier behavior, fan-out patterns, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety behaviors for low-confidence or closed markets, and illiquidity warnings. 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 a concise summary. Every sentence provides essential information; however, the length could be trimmed slightly without losing clarity. Given the complexity of the tool, the density is justified.

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

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

Without an output schema, the description thoroughly explains the response structure (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields). Covers edge cases like low-confidence matches, closed markets, and wide spreads, making it 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% (all three parameters have descriptions). The description adds valuable context: market parameter can be slug/URL/text; depth parameter has examples 'quick' vs 'thorough'; include_raw is explained with size implications and use cases. This enhances the schema significantly.

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 researches Polymarket bets, accepts multiple input formats (slug, URL, question text), and clearly distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on pulling Pipeworx data for a specific bet.

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

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

Provides clear usage context: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Includes fan-out examples for different bet categories, implicitly guiding the agent on when to use this tool versus 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 indicate readOnly, idempotent, and non-destructive. Description adds detail: default returns full series, param behavior disables full_series. 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 action and output format. Efficiently covers purpose, examples, and alternatives.

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

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

Despite no output schema, the description explains return structure (time series fields). Covers how to get IDs, optional param, and typical use. Complete for a read-only data fetch 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 description adds value: id examples, lang enum explanation, param's opaque nature and effect. Provides helpful usage context 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 fetches a specific type of data (HK C&SD statistical table) in a specific format (structured JSON). It distinguishes from sibling censtatd_search_tables by noting that tool finds table IDs.

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 example use cases (GDP, earnings, trade, etc.) and instructs to use censtatd_search_tables to find IDs. Explains optional param usage. 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?

Annotations already cover safety and idempotency; description adds context about underlying data source (data.gov.hk) and notes that not all tables are indexed, clarifying the openWorldHint. 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?

Two concise sentences: first delivers core purpose and output, second provides caveat and alternative. No wasted words, front-loaded with key 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?

For a simple search tool with 2 params and no output schema, description explains what is returned (IDs + titles), limitations (not exhaustive), and provides fallback method. Complete and self-contained.

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

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

Schema already describes both parameters at 100% coverage. Description adds practical examples for query (e.g., 'exchange rates') and mentions default/max for limit, which adds 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?

Description clearly states verb 'Search', resource 'Hong Kong C&SD table catalogue', and outputs 'matching table ids + titles'. Distinguishes from sibling tools like censtatd_get_table and censtatd_table_info.

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 usage with censtatd_get_table and provides examples of search keywords. Implicitly indicates when to use (keyword search) and offers an alternative method (reading from URL). 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description correctly confirms it does not pull data. It adds detail about what metadata is returned (title, notes, source), aligning with and complementing 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?

Two sentences, 140 characters, no wasted words. Purpose is front-loaded and 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?

Complete for a simple metadata lookup tool: parameters fully documented, return fields described, annotations present, and sibling tools provide context. No output schema needed as return values are explained.

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

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

Schema coverage is 100% for both parameters (id and lang), with clear descriptions and examples. The tool description does not add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Get metadata for a Hong Kong C&SD statistical table without pulling the data' and lists specific return fields (title, footnotes, source/contact). It distinguishes from sibling tools censtatd_get_table and censtatd_search_tables by focusing on metadata-only retrieval.

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

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

Explicitly recommends using this tool 'to confirm a table id and read measurement caveats before calling censtatd_get_table', providing clear context for when to use it. Does not explicitly name alternative tools or exclude other use cases, but the purpose 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?

Description adds behavioral context beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + pipeworx:// citation URIs). No contradictions with annotations (readOnlyHint, idempotentHint).

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 compact yet comprehensive. Every sentence serves a purpose. A slight improvement would be to break examples into a separate line for even quicker scanning, 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?

For a tool with 2 parameters and no output schema, the description covers input constraints, data sources, edge cases, and output format. No apparent gaps given the tool's complexity.

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

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

Schema coverage is 100% but description adds substantial meaning: for 'type' it enumerates exact data fields pulled per entity type; for 'values' it gives concrete examples and format (tickers/CIKs vs drug names). Exceeds baseline of 3 due to high-value context.

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 performs side-by-side comparison of 2-5 companies or drugs in one call, with specific verb phrases ('Compare X and Y', 'head to head') and explicit differentiation from sequential lookups. It distinguishes from sibling tools by emphasizing parallel over sequential.

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

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

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides query examples. It defines when to use but does not explicitly list when not to use (e.g., for single entity), though this is implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context about the output format (returns full schemas, ready to call directly) and the breadth of domains. It doesn't contradict annotations and adds some value beyond them, though it could mention limitations like network dependency.

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

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

The description is front-loaded with the core purpose and usage. It includes a list of example domains which is helpful but slightly verbose. Overall, every sentence earns its place, but 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 no output schema, the description explains what is returned (top-N tools with names, descriptions, full schemas) and that results are 'ready to call directly.' It covers the key aspects for a discovery tool, though it lacks details about pagination or sorting.

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). The description adds meaning by explaining aliases for the query parameter and providing natural language examples. It also mentions the limit parameter. This adds value beyond the schema's 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 tools by describing the data or task.' It provides specific examples of use cases (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by being a discovery tool rather than a specific data 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 instructs: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use versus alternatives, and implies that if you already know the tool, you can skip 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant context: it fans across multiple sources, returns specific fields, notes USPTO patents API sunset and soft-fail behavior, and mentions it's a single parallel call. 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 front-loaded with example queries, then purpose, then details. Every sentence adds value, though it is somewhat dense. Still 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?

No output schema exists, so description fully explains return values: cik, company_name, recent_filings (with URIs), fundamentals, patents (with caveat), news, LEI. Also covers input constraints and fallback behaviors. Complete for a complex 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%. Description adds practical meaning: explains that 'value' can be ticker or zero-padded CIK, emphasizes names not supported, and clarifies 'type' is limited to 'company'. This goes beyond schema details to guide correct usage.

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

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

Description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and outputs. It distinguishes from sibling tools by advising preference over chaining single-source 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 (user asks 'Tell me about X' or similar), states to prefer over chaining other lookups, and warns that names are not supported (use resolve_entity first if only have name).

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. Description confirms it deletes by key, adding context about clearing sensitive data. No contradiction, but could briefly note behavior on missing key.

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 short sentences, each serving a distinct purpose: action, usage, sibling relations. 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 destructive idempotent tool with one parameter, the description together with annotations provides all necessary context. No output schema 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?

Schema coverage is 100% with description 'Memory key to delete'. Description adds only 'by key', reinforcing but not extending 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 'Delete a previously stored memory by key', specifying verb and resource. Differentiates from siblings 'remember' and 'recall' by indicating it is the deletion counterpart.

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: when context is stale, task done, or clearing sensitive data. Mentions pairing with 'remember' and 'recall' as 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 declare read-only, idempotent, non-destructive. The description adds important behavioral details: it fetches the page, extracts key elements, and outputs a standard format. This goes beyond the annotations and helps the agent understand what the tool actually does.

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 well-structured sentences followed by a bullet list of use cases. Every sentence adds value, front-loading purpose and benefits. No redundant or unclear language.

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 two parameters and no output schema, the description covers the main aspects: input URL, optional max_links, output format, and use cases. It lacks details on error handling or non-accessible URLs, but is otherwise 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%, so the baseline is 3. The description confirms that 'url' is the target and implies 'max_links' limits entries, but does not add significant new meaning beyond the schema. It acknowledges parameters but does not elaborate on syntax or constraints.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') and explains the process: fetches page, extracts title/description/key links, emits standard llms.txt markdown. It also lists use cases, making the purpose very clear and distinct 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 explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitors. While it doesn't state when not to use or name alternatives, the context is clear and sufficient for most 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it lists only active subscriptions (default filter) and specifies returned fields, providing extra 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?

Two sentences, front-loaded with purpose, 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?

Simple tool with one optional parameter; description covers purpose, usage, and returned fields, making it fully adequate without output schema.

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

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

Schema coverage is 100% with parameter include_inactive already described. Description mentions 'active subscriptions' aligning with default, but adds no 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 uses specific verb 'List' and resource 'caller's active subscriptions', clearly distinguishing 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 when-to-use context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Lacks 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?

Description discloses that feedback goes to the team, is read daily, influences roadmap, is rate-limited to 5 per identifier per day, and doesn't count against quota. 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?

Description is concise, front-loaded with purpose, then usage, then constraints. 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?

For a feedback tool with 3 parameters and an enum, the description covers essential context. It doesn't describe the response or confirmation, but that is acceptable as output schema is absent.

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 good descriptions, but the tool description adds context like explaining each 'type' enum value and advising to be specific in 'message'. This enhances understanding beyond 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 it sends feedback to Pipeworx about bugs, features, data gaps, or praise. It defines each feedback type and distinguishes itself from sibling tools as the sole feedback channel.

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 each feedback type (bug, feature, etc.) and provides specific instructions: describe issues in terms of tools/packs, don't paste prompts. Also mentions rate limits and free usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), cached results (5min-1h), and the nature of the signal (self-aggregating). These details go beyond annotations.

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

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

Three concise sentences with no redundancy. First sentence defines purpose, second lists use cases efficiently, third gives technical details. Perfectly front-loaded and each 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?

Despite no output schema, description sufficiently explains return values (top tools, top packs, total call volume). With strong annotations and a simple parameter, this is fully adequate for an agent to invoke 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 one optional parameter described. The description adds semantic guidance on window interpretation ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing the schema's enum values.

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

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

Description clearly states the verb 'returns' and the resource 'trending calls on Pipeworx', specifically listing what is returned (top tools, top packs, call volume). It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on aggregated trend 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?

Explicitly provides three distinct use cases for when the tool is useful (discovering hot data sources, confirming canonical choices, aligning use case). This gives clear guidance on appropriate contexts, effectively differentiating from 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 indicate read-only, idempotent, non-destructive. Description adds behavioral context like Jaccard similarity threshold, placeholder filtering, and response structure. 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 detailed but well-structured, starting with requirements and then explaining modes, filters, and response. Could be slightly trimmed but no unnecessary repetition.

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 covers response fields (opportunities, partition_check) and important details like similarity and placeholder filter, making it complete for effective tool 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 has 100% coverage with descriptions for both parameters. Description enriches understanding by explaining the mode distinction, examples, and that they are mutually exclusive, adding 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It differentiates from sibling tools like polymarket_edges by specifying the approach.

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 that one of event or topic is required and recommends event for specific markets, topic for cross-event scanning. It does not provide exclusion criteria for when not to use, but the guidance is sufficient.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds extensive behavioral details: response structure (by_segment, fed_candidates, _diagnostics), caching (1h at KV level), 24h-move warning, and tradeable-edge knob effects. 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 very long and includes dense technical details on model families and internal logic. While front-loaded with purpose and segments, it could be more concise by separating essential usage guidance from implementation details. The length may overwhelm agents.

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

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

Despite no output schema, the description thoroughly explains the response format (segments, fed_candidates, diagnostics), what each opportunity includes (edge_pp_net, kelly_fraction, etc.), and caching behavior. This compensates for the lack of an output schema given the tool's complexity and 9 parameters.

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 context beyond parameter descriptions, such as explaining 'Tradeable-edge filters' groups, default values with rationale (e.g., slippage_pp default 0.3), and usage notes (e.g., bump for thin partitions). This extra information aids 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly positioning it for 'what should I bet on today'. It distinguishes its behavior from siblings like polymarket_arbitrage by focusing on edge discovery without manual paging.

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

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

The description explains usage context (discovering opportunities) and when to adjust knobs (tradeable-edge filters), but does not explicitly contrast with sibling tools like polymarket_arbitrage or bet_research, nor state prerequisites or 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 mark the tool as read-only and idempotent, and the description adds significant behavioral context: it explains safety fields (compatibility_warning, temporal_alignment), skipped cross-type/subtype counters, and conditions under which spreads are meaningful. 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 well-structured: it starts with purpose, then details modes, response structure, and safety fields. Every sentence provides necessary detail. Minor redundancy in the warning about pre-mapped topics, but overall efficient for the complexity.

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

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

Despite no output schema, the description fully explains the response (leg-by-leg prices, matched spread, top_spreads_pp, safety fields). It covers edge cases like compatibility warnings and temporal alignment, making the tool's behavior predictable.

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 enriches parameter understanding by listing valid topic values, explaining that explicit parameters override topic-mapped sides, and providing examples. It adds value beyond the schema.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and explains two modes (topic and explicit) with specific 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?

Provides clear guidance on when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and warns that pre-mapped topics often return compatibility warnings, indicating when the tool may not yield meaningful spreads. However, it does not explicitly state when to prefer other tools, but the context is sufficient.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds scoping details (anonymous IP, BYO key hash, account ID) and behavior when key is omitted (list all). 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 three well-structured sentences, front-loaded with the main action. 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?

Given the simple tool (1 optional param, no output schema), the description covers purpose, usage, scope, and sibling pairing completely. No gaps.

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

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

Schema coverage is 100% with parameter description, but the description adds the dual behavior (retrieve value vs. list keys) and clarifies optionality. Provides 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 verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings like remember and forget. It provides specific examples of 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 explicitly states when to use the tool (to look up context stored earlier) and implies when not (use remember to save, forget to delete). It pairs with sibling tools.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns only recent alerts, mentions the effect of mark_read (flagging events read so next call shows newer ones), and lists return fields. This goes beyond annotation basics. No contradictions noted.

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

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

The description is a single, well-structured paragraph of 5 sentences. It is front-loaded with the primary purpose, then details parameters, return fields, and side effects. Every sentence adds value without redundancy. It is concise yet comprehensive.

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 what the tool returns (source, citation_uri, raw event payload) and the effect of parameters. It mentions that the same feed is available via a GET endpoint for other use cases. However, it could be more explicit about the exact format or structure of the returned data, but it is sufficient for typical usage.

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

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

Input schema has 100% parameter descriptions, but the description adds extra usage context: e.g., 'Filter by type (e.g. 'sec_8k')' and 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This helps an agent use parameters correctly beyond schema definitions.

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: 'Pull fired events from your subscription feed.' It specifies the resource (alerts from subscription feed), the action (pull/return), and adds detail about returned fields (source, citation_uri, raw event payload) and filtering options. This sets a clear and distinct purpose from sibling tools which involve subscriptions, searches, or other actions.

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 retrieve recent alerts from the subscription feed. It explains parameter usage (filter by type, since, mark_read) and even mentions alternative access via a GET endpoint. While it does not explicitly exclude cases where other tools should be used, the nature of the tool is specific enough that usage is well-understood. A minor omission is no direct comparison to sibling tools like 'subscribe' or 'list_subscriptions'.

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. Description adds valuable behavioral context: fans out to multiple sources, fallback chain, PatentsView sunset handling, and return structure (changes grouped by source + total_changes + URIs). No contradictions.

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

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

Description is concise yet comprehensive, front-loaded with usage examples, and every sentence adds value. 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, the description explicitly states the return structure (changes[] grouped by source + total_changes + citation URIs). Covers multiple data sources, fallback logic, parameter behavior, and differentiation from sibling tool. Complete for this complex 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%. Description adds meaning beyond schema: explains that 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y'), suggests '30d' or '1m' for typical monitoring, and clarifies that 'type' is only 'company' today.

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, with specific examples ('What's new with X', 'latest on Y', etc.) and explicitly distinguishes from sibling tool entity_profile by specifying when to use each.

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 query examples, describes when to use entity_profile instead, and explains the fallback mechanism (GDELT preferred, GNews on rate limit/5xx) and soft-fail for USPTO, giving clear guidance on tool 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?

Adds key context beyond annotations: scoped by user identifier, persistent vs 24-hour retention. No contradiction with annotations (idempotentHint matches effect).

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, front-loaded with purpose, then usage details. 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?

Covers purpose, usage, storage scope, retention policy, and pairing with other tools. Complete for effective 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?

Schema has 100% coverage; description repeats key-value pair concept but doesn't add new semantic depth. Baseline score 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 explicitly states 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. Distinguishes from sibling tools recall and forget.

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

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

Provides precise when-to-use guidance: 'when you discover something worth carrying forward'. Also gives examples like resolved ticker, target address. Mentions pairing with recall and forget.

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 that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. Details return format: for company (ticker, CIK, name, citation URI) and drug (RxCUI, ingredient, brand, citation). Mentions auto-disambiguation. Adds significant 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?

Well-structured with examples and entity-specific details. Slightly lengthy but each sentence adds value. Front-loaded with query examples. Could be trimmed slightly but very 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 two parameters, 100% schema coverage, rich annotations, and no output schema, the description fully covers purpose, when to use, return details, internal behavior, and examples. Leaves no gaps 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% with descriptions. Description adds examples (e.g., 'ozempic', 'metformin') and explains that value for company can be ticker, CIK, or name. Provides mapping to return types, adding 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?

Description starts with example queries and clearly states the purpose: resolve a name to a canonical identifier. It lists supported entity types and what they return, differentiating from siblings by saying 'Use FIRST whenever you have a name but need an ID.'

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 FIRST whenever you have a name but need an ID.' Provides guidance on input types (ticker, CIK, name; brand/generic name). Could be clearer on when not to use, but sufficiently directs the 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?

Discloses that each entity is probed with ai_visibility_check, results are ranked, and output includes score, confidence, signal density. Annotations already cover safety and idempotency; description adds behavioral detail 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?

Two purposeful sentences plus a concrete example quote. Front-loaded with purpose, then details, no filler.

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

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

Despite no output schema, description specifies return structure (ranked list with score, confidence, signal density per entity). Internal process (probing with ai_visibility_check) and entity ordering are explained. Sufficient for usage.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by noting that first entity is treated as 'subject' for narrative ordering, and context is applied to every probe.

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 'compare AI visibility across multiple entities side-by-side', names the resource (entities), and distinguishes from sibling ai_visibility_check by specifying multiple entity comparison and 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?

Provides clear context for competitive AI-marketing audits with an example question, but does not explicitly state when not to use (e.g., for single entity checks) or mention alternatives like ai_visibility_check.

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 enriches annotations by detailing the composite nature, graceful degradation, bundlephobia's first-measurement delay (5-30s), and partial failure handling (sources_failed). 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?

Informative and front-loaded, but slightly dense. Every sentence earns its place, though could benefit from bulleted return fields for quick scanning.

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

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

Given no output schema, the description fully enumerates return fields (summary block, per-advisory detail, links, alternative versions). Explains error conditions, default behavior, and ecosystem limitation. Very 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. Description adds extra value: explains scoped packages ('@types/node') for 'package', and default behavior for 'version'. Also clarifies ecosystem scope (NPM only).

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 'scan' (composite check) and the resource 'npm package'. It distinguishes from sibling tools by specifying the domain and alternatives for other ecosystems, e.g., 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Explicit usage cues: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusions for non-npm ecosystems, directing to deps.dev 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 declare readOnlyHint and idempotentHint. Description adds BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flagging, and character offsets for verification.

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

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

Well-structured front-loading purpose and usage, then technical details. Each sentence adds value; not overly verbose.

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

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

With no output schema and complexity of semantic search, description covers purpose, when to use, technical details (embeddings, windows, cap), and output (passages, offsets, scores, flag).

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. Description adds meaning: explains text is document text, query with examples, limit as max passages. Also details output format (passages with offsets and scores) 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 'Semantic search INSIDE a fetched record,' specifying a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides an alternative tool (ask_pipeworx_grounded) and workflow 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?

The description contradicts the idempotentHint annotation (true) by explicitly stating 'Create a new subscription' and implying non-idempotent behavior (each call returns a new id). No clarification on idempotency is provided, which is a significant gap. Additionally, while it adds value beyond annotations in other areas, the contradiction outweighs that. Annotation Contradiction flagged.

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 yet comprehensive, using clear structure: purpose statement, prerequisites, type breakdown with examples, and delivery channel details. It front-loads critical information and avoids redundancy despite covering complex options.

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

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

Given the tool's complexity (3 params, nested objects, multiple types), the description covers all essential aspects: action, prerequisites, type-specific parameters, delivery channels with limitations, and return value. No output schema exists, but the return is adequately specified.

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

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

With 100% schema coverage, the description adds substantial meaning by providing concrete examples, constraints (e.g., 'items:["5.02"] = officer change'), and detailed explanations for each subscription type and delivery channel, going well beyond the schema's minimal 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 creates a proactive monitoring subscription to a live-data event stream, distinguishing it from sibling tools like 'list_subscriptions' and 'unsubscribe'. It specifies the action ('create'), resource ('subscription'), and return value ('new subscription id').

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

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

The description provides explicit guidance on when to use the tool, including prerequisites (Pipeworx OAuth account), supported subscription types, and delivery channels. It also implies when not to use (anonymous/BYO accounts cannot persist subscriptions) and offers context about alternatives through sibling tool names.

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 safety and idempotency. Description adds that it draws from a live catalog, returns exact tool+argument shapes, and is an onboarding entry point. Could mention if output is cached or dynamic, but overall good.

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?

Packed with useful info and front-loaded with natural language queries. Could be slightly more concise, but every sentence adds value. Structure is logical: what it returns, how to call, when to use.

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

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

Despite no output schema, the description thoroughly explains the return type (category-bucketed example questions with tool+argument shapes) and sources. For a simple tool with one optional param, this is fully complete.

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

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

Schema coverage is 100% with parameter description. Description adds value by listing example topic values and explaining the effect of omitting it (cross-category spread). Minor duplication but helpful.

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 for onboarding. It lists exact categories and explicitly differentiates itself from siblings like ask_pipeworx and discover_tools by positioning as the first tool to use when unsure of capabilities.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also details call patterns: no args for full spread, topic to focus. Mentions alternatives like meta-tools.

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

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

The description adds behavioral details beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Annotations already indicate idempotent, non-destructive, non-read-only; description enhances understanding.

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

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

Three concise sentences, each with distinct value: action, ownership, side effects. 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?

The description covers purpose, behavior, and side effects. Missing return value information, but given low complexity (1 param, no output schema), it is mostly complete.

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

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

Schema coverage is 100% and description does not add new semantics for the 'id' parameter beyond what schema provides. 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 verb 'Cancel a subscription by id' and the resource 'subscription'. It distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' (list), and mentions interaction with 'recent_alerts'.

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 'Ownership is enforced — you can only cancel your own subscriptions', providing guidance on when to use. It does not explicitly list alternatives, but the context (sibling tools named 'subscribe' and 'list_subscriptions') makes usage clear.

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

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

Annotations indicate idempotent, read-only, and open-world hints. The description adds behavioral details: returns verdict, structured form, actual value with citation, and percent delta. It also explains that it replaces 4-6 sequential calls and uses 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 front-loaded with natural-language triggers, then states purpose, use case, scope, output, and efficiency. Every sentence is informative and necessary. It is structured well 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 a single parameter and no output schema, the description provides complete context: input format, output components, data source, domain limitation, and efficiency benefit. The agent can reliably select and invoke this tool.

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

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

The input schema has 100% coverage with a good description of 'claim' including examples. The tool description reinforces this but adds little new beyond 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 verifies natural-language claims using authoritative sources, specifically for company-financial claims. It distinguishes from siblings by noting it replaces multiple sequential calls. The verb 'validate' is explicit, and the resource is claim verification via SEC EDGAR + XBRL.

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 to use when the agent needs to check factual correctness. It also specifies the domain (company-financial claims for v1). However, it does not explicitly mention when not to use or list alternatives, though the scope limitation is clear.

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