Public Suffix List

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that the default model is free Workers AI Llama, that Anthropic requires a BYO API key, and that the tool returns per-model data. 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 that are front-loaded with the main action and quickly move to details. 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?

Given 4 parameters and no output schema, the description covers return structure ('per-model {score, confidence, signals, raw_response} + combined view') and use cases. Could mention rate limits or behavior if models fail, but overall 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% and the description adds substantial meaning: example values for 'entity', supported models for 'models', clarification that '_apiKey' is passed through to Anthropic, and help for 'context' to disambiguate. This goes 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 uses a specific verb ('probe') and resource ('LLMs') with a clear outcome ('score visibility 0-100 per model'). It distinguishes from siblings by focusing on multi-model probing and scoring.

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

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

Explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic API key. No explicit when-not to use, but the context is clear.

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

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

The description adds context beyond annotations: it explains that the tool routes to one of 3,436 tools across 780 verified sources, fills arguments, and returns structured answers with stable citation URIs. Annotations already indicate read-only, idempotent, and not destructive. The description does not contradict annotations. It could further describe error handling or fallback behavior, but it provides solid transparency.

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

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

The description is well-structured with a strong opening statement, followed by specifics and examples. It is not overly verbose, but could be slightly trimmed (e.g., the list of example questions might be shortened). However, each sentence serves a purpose, and the information is front-loaded with the key guidance.

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

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

The description provides sufficient context for a tool with 6 parameters (1 required), no output schema, and no nested objects. It explains the tool's scope, when to use, and the nature of the response (structured with citation URIs). It could mention potential limitations or ambiguous inputs, but overall it is complete enough for an agent to understand the tool's role.

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% description coverage, with each parameter including a description. The tool description does not add new information about parameters beyond what the schema already provides. It mentions 'question' in the general text but does not elaborate on formatting, constraints, or examples beyond the schema's examples. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to route factual questions to authoritative structured data sources, with explicit preference over web search. It lists specific use cases (SEC filings, FDA data, etc.) and distinguishes itself from sibling tools by being a general query interface, while siblings like 'compare_entities' and 'entity_profile' are more specialized.

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: 'PREFER OVER WEB SEARCH for questions about current or historical data...' It lists trigger phrases like 'what is', 'look up', 'find', and gives examples. It does not explicitly mention when not to use, but the context implies that for non-factual questions, other tools might be better. The guidance is clear and actionable.

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

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

The description discloses detailed behavioral traits: it only uses tool results, returns structured output with evidence, confidence, source, and explicit refusal reasons (not_in_source, no_tool_match, etc.). This adds significant context beyond the annotations (readOnlyHint, openWorldHint, 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?

The description is concise with no wasted words. It front-loads purpose and routing, then succinctly covers output format, usage guidelines, and cost comparison in a single dense paragraph. 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?

The description is highly complete given the tool's complexity. It covers purpose, routing, output structure (with field names and refusal reasons), usage context, and trade-offs versus the sibling ask_pipeworx. Even without an output schema, the return format is fully described.

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

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

The input schema has six parameters (all aliases for question), and the description does not add extra meaning beyond what the schema already provides ('Your question in natural language'). Schema coverage is 100%, 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?

Clearly states it is a 'hallucination-resistant answer mode' for high-stakes reads, explains it routes like ask_pipeworx but extracts answers only from tool results, and distinguishes itself by emphasizing factuality. The description uses specific verbs and resources.

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 an answer will be quoted, cited, or acted on' and provides examples (financial, legal, medical). It says 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost, clearly guiding when to use this tool 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?

Description adds significant behavioral detail beyond annotations: low-confidence resolution short-circuits, closed markets return status, wide-spread markets carry tradeability note. Also explains resolver contract, parent event extractor, and news fields. No contradictions with readOnlyHint, etc.

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

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

The description is verbose with dense paragraphs and lacks clear structure (e.g., bullet points or sections). While every sentence adds value, it could be more concise and better organized.

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

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

Given the tool's complexity (classifiers, fan-outs, response shapes), the description is thorough, covering edge cases like low-confidence matches, closed markets, illiquid spreads, and detailed resolver contracts. No output schema exists, so description fully handles response explanation.

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 3 parameters have schema descriptions; description adds meaningful context: explains depth enum (quick vs thorough) and include_raw rationale (response size trade-offs). Input format for market is thoroughly explained.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and provides usage examples, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

Explicitly mentions use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Provides context on when results may be low confidence or closed markets, though does not explicitly name alternative tools.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it pulls specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results, and returns citation 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?

The description is information-dense with every sentence adding value. It includes examples, explicit instructions, and technical details. While slightly long, it is well-structured and front-loaded with key usage hints.

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

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

Given no output schema, the description thoroughly explains return values: sorted results, paired data, and citation URIs. It covers both entity types comprehensively, making the tool fully understandable 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% (both parameters described). The description adds meaning beyond the schema by explaining the data sources associated with each type and providing usage examples for values (tickers/CIKs for company, drug names). This enriches the agent's understanding.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific verbs and resources ('Compare X and Y', 'X vs Y'), and distinguishes it from sequential single-pack lookups, contrasting with sibling tools like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance with example queries. It lacks an explicit exclusion for single entity lookups 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is extra behavioral context. No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the purpose and usage. It is efficient and contains no filler, though it is slightly dense. It earns its place with actionable guidance and examples.

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

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

No output schema exists, but the description adequately explains return values: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Parameter coverage is complete, and usage context is provided. Minor gap: doesn't mention if limit parameter affects pagination, but overall complete.

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

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

Schema description coverage is 100%. The input schema already describes parameters and their aliases. The description adds context about the natural language query format with examples, but this only marginally supplements 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's purpose: 'Find tools by describing the data or task.' It provides a comprehensive list of domains (SEC filings, financials, FDA drugs, etc.) and explains that it returns top-N relevant tools with schemas, making the scope very specific and distinct from siblings.

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

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

Explicitly instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies when to use it ('Use when you need to browse, search, look up, or discover what tools exist for:'). While it doesn't explicitly mention when not to use it, the guidance is strong and contextual.

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 readOnlyHint and idempotentHint annotations, the description details the fan-out across multiple sources, specific return fields (CIK, filings, fundamentals, patents, news, LEI), fallback chains, and noted patent API sunset, giving rich behavioral transparency.

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

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

The description is well-structured and front-loaded with usage patterns, but at several sentences it could be tightened. However, every sentence adds value, so it earns a 4.

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

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

Given the tool's complexity and lack of output schema, the description covers all key aspects: returned fields, data sources, limitations (ticker/CIK only, patent sunset), and fallbacks. Minor gap in exact response structure, but otherwise 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 description adds significant meaning beyond the input schema: provides examples (ticker 'AAPL' or CIK '0000320193'), clarifies that names are not supported, and explains the single supported type with future expansion plans, 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's purpose: producing a full cross-source profile of a US public company in one parallel call. It distinguishes itself from chaining single-purpose lookups and from sibling tools like resolve_entity.

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

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

Explicitly advises to prefer this tool over chaining individual lookups when a holistic view is needed, and directs name-based queries to resolve_entity, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive behavior; description adds context about clearing sensitive data and stale context, enhancing 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?

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

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

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

Covers purpose, usage, and pairing; could mention behavior when key is missing but not critical for a simple tool.

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

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

Schema fully covers the key parameter; description adds context about memory key but no new semantics 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 the action (delete) and resource (memory by key), distinguishing it from sibling 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 tells when to use (stale context, task done, sensitive data) and pairs with alternatives (remember, 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 details the process (fetch, extract, emit markdown) and matches annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It adds behavioral context beyond annotations by explicitly describing the output format and actions taken.

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 and immediate value, followed by concise use cases. No redundant or vague 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 tool with 2 parameters and no output schema, the description sufficiently explains the output format (standard llms.txt markdown), the location (site-root/llms.txt), and the internal logic (fetch, extract, emit). 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?

Input schema has 100% coverage with descriptions for both parameters (url, max_links). The tool description does not directly elaborate on parameters beyond the schema, but it provides context for how max_links is used (extracting links). Baseline 3 applies due to complete schema coverage.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the target 'any URL'. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence, which have different focuses.

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 explicit use cases (client site indexing, personal projects, competitor auditing), providing clear context for when to use. It does not specify when not to use, but alternatives are not obvious given the unique tool purpose.

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

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

Annotations already mark it as read-only (readOnlyHint=true) and non-destructive (destructiveHint=false). The description reinforces this by stating it lists subscriptions and returns specific fields. It adds no contradictory info; instead, it provides concrete return field details and usage context, 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: first defines action and output, second gives usage guidance. No filler, every word contributes meaning. Front-loaded with the core purpose.

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

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

Given the tool has a single optional parameter and no output schema, the description adequately covers purpose, output fields, and usage context. It does not mention pagination or sorting, but for a simple list tool this is acceptable. Slightly more could be added about possible empty results, but not necessary.

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

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

Schema description coverage is 100% (the only parameter 'include_inactive' is described in the schema). The description mentions 'active subscriptions' by default, which matches the schema, but adds no extra semantic detail about the parameter's format or behavior beyond what the 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?

Description starts with 'List the caller's active subscriptions', clearly stating verb and resource. It enumerates returned fields ('id, type, params, created_at, last_fired_at, fire_count'), making the tool's output unambiguous. This distinguishes it 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?

Explicitly guides when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent both the context (review before actions) and a specific action (finding an ID to cancel), reducing misuse.

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 minimal behavioral context beyond annotations, only hinting at the output (last refresh and rule count). Annotations already declare readOnlyHint and idempotentHint, so the description adds little 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?

The description is extremely concise (four words), with no wasted text; however, it lacks sentence structure and could be more 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 has no parameters and an output schema exists, the description is minimally sufficient but does not explain what 'version' means or how the numbers relate.

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?

There are no parameters, and schema coverage is 100%, so the description does not need to provide param details. Baseline 3 is appropriate as it neither adds nor detracts.

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 'Last refresh + rule count.' is vague; it does not clearly state what resource or version it refers to, nor does it distinguish from siblings like 'entity_profile' or 'recent_changes'.

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

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

No guidance is provided on when to use this tool versus alternatives; the description lacks any context about its application.

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 is consistent with annotations (readOnlyHint, idempotentHint). However, it does not disclose behavior for invalid inputs (e.g., domains without a public suffix) or edge cases. Annotations already provide safety context, so the description adds minimal extra 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?

The description is a single, clear sentence that immediately conveys the tool's purpose. No unnecessary words or 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 simplicity and the presence of annotations and an output schema, the description is largely sufficient. However, it could mention error handling or input validation to be 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?

The schema has 0% description coverage and only provides examples. The description mentions 'domain' but does not clarify required format (e.g., should it include protocol? Must be fully qualified?). The examples help but the description should explicitly state 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 clearly states the tool's function: splitting a domain into three specific components (subdomain, registrable_domain, public_suffix). It uses precise terminology and differentiates from sibling tools like 'public_suffix' and 'registrable_domain' which only return single components.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, if only the public suffix is needed, the sibling tool 'public_suffix' would be more appropriate, but this is not mentioned.

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

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

Annotations are all false and provide no behavioral info. The description compensates fully by disclosing rate limits (5 per identifier per day), cost (free, no quota impact), and impact (digests read daily, affects roadmap). 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 five sentences, each providing essential information: purpose, usage, formatting guidance, impact, and constraints. No filler or redundancy. Front-loaded with the core action.

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

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

Given the simple nature of the tool and no output schema, the description covers all necessary aspects: what it does, when to use, how to format input, limitations, and cost. Nothing is missing for an agent to correctly invoke 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%, so baseline is 3. The description adds extra meaning for the 'message' parameter by specifying to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts. This provides semantics beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. The specific verb 'tell' and resource 'Pipeworx team' make it unambiguous. It stands out from sibling tools, as no other tool is for feedback.

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: for bug reports, feature/data_gap requests, or praise. It also gives an exclusion: 'don't paste the end-user's prompt'. This provides clear guidance on appropriate 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?

Description adds behavioral context beyond annotations: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h'. 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?

Four sentences, front-loaded with main result. Every sentence adds meaningful information without 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, caching, data source. Does not specify exact return format but mentions output components. Adequate for a simple tool without output schema.

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

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

Schema covers the window parameter with enum and description. Description adds extra context on usage (shorter for hot, longer for steady-state). Baseline 3 but adds value.

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

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

The description clearly states the verb 'Returns' and the resource 'top tools, top packs, total call volume'. It distinguishes from siblings like 'discover_tools' by focusing on trending usage of other AI agents.

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

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

Provides three specific use cases (discovering hot data sources, confirming popular tool, seeing alignment). Does not explicitly state when not to use or alternatives, 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: mode selection, monotonicity checks, partition sums, semantic anchor (Jaccard similarity), partition filter, 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 well-organized and front-loaded with the requirement. It is somewhat verbose but every sentence adds necessary detail. 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 the tool's complexity (two modes, multiple checks, no output schema), the description covers the core functionality well, including response structure. However, it lacks details on error handling and behavior when both parameters are provided.

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, but the tool description adds significant value beyond the schema: explains what each mode does, provides concrete examples of slugs and topics, and clarifies that providing both parameters behavior is undefined.

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, and distinguishes between single-event and cross-event modes. It is distinct from sibling tools like bet_research and polymarket_edges.

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 call with no args fails. Recommends when to use each mode with examples, providing clear usage guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavior: caching strategy (1h at KV level), edge calculation details, response structure with diagnostics, and knob effects. 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 long but well-organized into sections (segments, knobs, response). Every sentence provides essential detail for an AI agent. Minor redundancy could be trimmed, but it's concise given 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?

Tool has 9 parameters, no output schema, and complex behavior. Description thoroughly covers response structure (by_segment, diagnostics), caching, edge calculation, filters, and edge cases (Fed bets). Fully compensates for lack of output schema.

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

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

Schema coverage is 100% with all 9 parameters described. Description adds further value by explaining interactions (e.g., min_partition_leg_kelly vs min_kelly), providing usage context (e.g., slippage_pp on Polymarket), and detailing knobs section that complements 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with specific verb 'Scan' and resource 'top Polymarket markets'. It differentiates from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreements, and includes a usage scenario 'what should I bet on today'.

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 states built for discovering opportunities without paging markets, and includes guidance on when to use each segment and the Fed bets note. However, it does not explicitly mention when not to use the tool or compare to alternatives like polymarket_arbitrage, though context signals show sibling tools.

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

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

The description thoroughly explains the tool's behavior: leg-by-leg prices, spread calculation, compatibility warnings (with specific conditions), temporal alignment, and skipped cross types/subtypes. It goes well beyond the annotations (which only indicate readOnly and idempotent) to provide rich operational detail.

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

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

The description is comprehensive but verbose, with many details about response fields and edge cases that could be shortened or moved to the output schema. While front-loaded with purpose, the lengthy explanation may reduce quick comprehension.

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 all expected response elements (prices, spreads, warnings, alignment, skipped categories) and explains edge cases. Annotations provide safety context, and the description adds sufficient detail for correct usage without ambiguity.

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

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

Schema description coverage is 100%, with each parameter described. The description adds value by explaining the dual-mode interaction (topic vs explicit), listing the exact topic shortcuts, and indicating how parameters override each other. This goes beyond basic 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 computes cross-venue spread between Kalshi and Polymarket for resolving questions. It distinguishes from siblings by focusing on cross-venue comparison and explicitly mentioning two modes (topic shortcuts and explicit pairing), making the purpose specific and unmistakable.

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

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

The description provides explicit guidance on when to use the tool (two modes, pre-mapped topics vs explicit tickers), includes warnings about compatibility and temporal alignment, and cautions that pre-mapped does not imply tradeable. This helps the agent decide appropriate usage and set expectations.

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

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

Annotations indicate readOnlyHint, idempotentHint, and openWorldHint, so the tool is safe and non-destructive. However, the description adds no behavioral details—e.g., what the output looks like, error handling, or domain format expectations.

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 extremely concise but at the cost of clarity. It lacks any structured explanation of tool behavior, returning data, or usage context. Conciseness should not sacrifice informativeness.

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 output schema exists, the description could rely on it partially, but it still fails to explain the core concept of 'public suffix'. The tool is simple, but a minimal paragraph would improve completeness.

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 single parameter 'domain' has no description in the schema (0% coverage) and the tool description adds no explanation of expected format (e.g., FQDN, with/without protocol). Examples in schema help but the description does not clarify.

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 'Just the public suffix.' hints at extracting the public suffix from a domain, but it is vague and does not define 'public suffix'. It distinguishes little from sibling 'registrable_domain' which likely has a similar purpose.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools like 'registrable_domain' and 'parse' suggest related functionality, but the description provides no context for 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=true, idempotentHint=true, destructiveHint=false. Description adds detail about scoping to identifier and behavior of omitting key. Does not contradict annotations.

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

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

Three sentences, no wasted words, front-loaded with primary purpose. Efficient and clear.

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

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

For a simple retrieval tool with good schema and annotations, the description covers purpose, usage, parameter behavior, scoping, and companion tools. 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?

Single parameter 'key' is fully explained: omit to list all keys, provide to retrieve. Schema coverage is 100%, but description adds valuable context about the parameter's optionality and purpose.

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 that the tool retrieves a previously saved value or lists all keys. Distinguishes from sibling tools 'remember' and 'forget' by mentioning pairing with them.

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

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

Explicitly says to use for looking up context stored earlier, provides concrete examples (ticker, address, notes), and mentions alternatives (remember/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?

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds value by explaining the mark_read side effect (flags events as read for subsequent calls) and the availability of the same data via an HTTP endpoint. This provides behavioral context 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 well-structured, starting with purpose, then detailing fields and filters, and ending with usage notes. Each sentence adds value, though slightly verbose for a tool with few parameters.

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 sufficiently outlines what is returned (source, citation_uri, payload). It covers input parameters and their effects, plus provides an alternative access method. Lacks explicit pagination or error behavior, but adequate for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces parameter usage with examples (e.g., 'sec_8k' for type) and explains the effect of mark_read and since, adding practical context that the schema alone does not provide.

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 'Pull fired events from your subscription feed' with specific details about the returned fields (source, citation_uri, raw event payload) and common filters (type, since). This differentiates it from sibling tools like 'list_subscriptions' which manage subscriptions, not events.

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

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

The description explains when to use the tool (to retrieve recent alerts) and provides context for polling and parameter usage. It mentions an alternative HTTP endpoint for scripts, but does not explicitly compare to siblings or give '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?

Discloses complex behaviors beyond annotations: parallel fan-out to multiple APIs, fallback logic (GDELT→GNews), soft-fail for USPTO, accepted since formats, and return structure (grouped changes, total count, citation URIs). No contradiction with annotations (readOnlyHint consistent with fetch-only operation).

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 user intent examples, then efficiently describes sources, parameters, return format, and alternatives. Every sentence serves a purpose 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?

Despite no output schema, description fully details return structure and edge cases (soft-fail). Given complexity (3 data sources, fallback, parameter formats), the description is complete enough for reliable agent 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 covers basics but description adds value: examples of relative since shorthand ('7d', '30d', '3m', '1y'), recommendation for typical monitoring ('30d' or '1m'), and example values for ticker/CIK. These enrich understanding beyond schema.

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

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

The description clearly states the tool provides a 'change feed for a company' and lists supported sources (SEC EDGAR, GDELT/GNews, USPTO). It differentiates from sibling 'entity_profile' by specifying this tool is for recent changes over a window, not a static profile.

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

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

Explicitly tells when to use this tool ('latest on Y') and when to use an alternative ('Use entity_profile instead when you want the static profile'). Also provides typical usage hints like 'use 30d for typical monitoring'.

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 little beyond the annotations, which already declare it as read-only, idempotent, and non-destructive. It does not explain what 'nearest suffix' means, what the tool returns, or any side effects. The description is too minimal to provide meaningful 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?

The description is very concise (one sentence), but this comes at the cost of clarity. It is front-loaded but cryptic. While it is not verbose, it could be more informative without becoming lengthy.

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 one parameter, annotations, and an output schema, the description should explain what the tool does and when to use it. It fails to set proper expectations about output or behavior, leaving the agent with insufficient context for correct 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?

The input schema has 0% description coverage for the single parameter 'domain', but the description mentions 'Domain', indicating the input is a domain name. This adds some meaning, though it fails to specify format or provide examples beyond what the schema already includes. The description partially compensates for the missing schema documentation.

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

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

The description 'Domain + nearest suffix (the site)' is vague and does not clearly state what the tool does. It lacks a specific verb (e.g., 'check', 'determine') and resource description, making it difficult for an agent to discern that it likely checks domain registrability. Sibling tool 'public_suffix' suggests a similar function, but no differentiation is provided.

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?

There is no guidance on when to use this tool versus alternatives like 'public_suffix'. The description does not specify prerequisites, use cases, or exclusions, leaving the agent without context for 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds key behavioral details: memory scoping by user identifier, 24-hour retention for anonymous sessions, and persistent storage for authenticated users.

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, no redundant words. Each sentence adds unique value: purpose, usage, persistence details, and sibling pointers.

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 2-param tool with no output schema, description fully covers purpose, usage, behavioral nuances, and integration with sibling tools. 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 covers both parameters with descriptions and examples (100% coverage). Description adds no additional parameter semantics beyond schema, so baseline 3 is appropriate.

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

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

Description starts with 'Save data for reuse across sessions' which clearly identifies verb+resource. It provides concrete examples (ticker, address, preference) and 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 states when to use ('when you discover something worth carrying forward') and how it pairs with recall/forget tools. Also distinguishes memory persistence by authentication status.

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 non-destructive. The description adds significant behavioral context: it resolves names to IDs, auto-disambiguates, cascades through multiple internal endpoints, and returns citation URIs. This enriches the agent's understanding of the tool's behavior beyond annotations.

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

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

The description is concise yet comprehensive, using a single paragraph that front-loads examples and usage guidance. Every sentence adds value—examples, purpose, usage instruction, supported types, and behavioral notes—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?

Despite no output schema, the description fully explains what each entity type returns, including citation URIs. It covers input, process (cascading lookups), and output, making the tool's behavior clear for an AI agent. No gaps remain for effective 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% (both parameters described). The description adds meaning by detailing acceptable inputs per type (e.g., ticker, CIK, or name for company; brand/generic for drug) and hints at expected outputs. This goes well beyond the schema's limited 'description' fields.

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

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

The description starts with concrete user queries like 'What's the ticker for...' and explicitly states it resolves names to canonical identifiers required by other tools. It clearly distinguishes itself as the first step for getting IDs, contrasting with sibling tools that likely use those 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?

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It lists supported entity types (company, drug) and explains what each returns, making the tool's applicability clear. While it doesn't explicitly say when not to use, the 'first' emphasis implicitly guides priority.

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 behavioral details: it probes each entity, ranks by score, surfaces most/least recognized, and mentions the _apiKey requirement for Anthropic. This adds value beyond annotations.

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

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

Two sentences, front-loaded with the core purpose and outcome. Every sentence is informative 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?

No output schema, but the description specifies return elements: ranked list with score, confidence, signal density per entity. This is sufficient for an agent to understand expected output. Missing information about error handling or rate limits, but acceptable given current complexity.

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

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

Schema coverage is 100%, but the description adds semantic context: first entity is treated as 'subject', models list supported values, _apiKey is conditional, context disambiguates names. This enriches 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 compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use, but does not explicitly list exclusions or alternatives, though the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: composite check across multiple sources, return block details, per-advisory detail, links, and importantly that bundlephobia's first measurement can take 5-30s with graceful degradation via 'sources_failed'.

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 dense paragraph but front-loaded with purpose. Every sentence adds value. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (composite, multiple sources, partial failures), the description covers ecosystem, timeout behavior, return summary, and additional details. No output schema, but the description adequately explains what is returned.

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

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

Schema coverage is 100% with well-described parameters. The description does not add new meaning beyond the schema, merely restating that version defaults to latest. 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 is a composite check for npm packages covering license, advisories, version history, and bundle size. It specifically says 'fans out across deps.dev and bundlephobia,' making the purpose distinct from sibling tools like 'validate_claim' or 'entity_profile'.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies NPM ecosystem only in v1 and mentions partial failure handling. 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?

Beyond annotations (read-only, idempotent), the description details the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging, fully disclosing behavioral traits.

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?

Concise three-sentence structure with front-loaded purpose ('Semantic search INSIDE'), every sentence adds value (use-case, technical details, pairing guidance), no redundancy.

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

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

Given no output schema, the description covers return format (passages with offsets and scores), parameters fully, and usage context. Pairs with sibling tool for grounding, leaving no gaps for safe 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 coverage is 100% with good descriptions, but the description adds meaningful context: examples for queries, explanation of text max size, and default limit. It slightly 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 clearly states the tool performs semantic search inside a fetched record, specifying verb ('search'), resource ('inside a fetched record'), and differentiating from siblings like ask_pipeworx_grounded with concrete use cases (e.g., 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded as an alternative, providing a clear decision framework for 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?

The description states 'Create' which implies a mutation (creating a new subscription), but annotations have readOnlyHint: true, indicating a read-only operation. This is a clear contradiction. Additionally, idempotentHint: true conflicts with the description implying each call creates a new subscription, returning a new id.

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

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

The description is concise, with two well-structured paragraphs. Key information is front-loaded: purpose, supported type, example parameters, return value, requirements, and delivery options. Every sentence adds value without 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?

The description covers the creation of a subscription, requirements, delivery channels, and limitations. It mentions the return value (subscription id). Missing details like error handling for invalid tickers or duplicate subscriptions, but given no output schema, it is fairly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the params object structure for sec_8k, providing examples for items, and detailing delivery channels with constraints (SMS must match verified phone, capped at 10/day, email validated). This clarifies usage beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, specifically for SEC 8-K filings with example items. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use: to get alerts on SEC 8-K filings. It mentions requirements (Pipeworx OAuth account) and delivery channel options with limitations (SMS capped at 10/day). It does not explicitly state when not to use or alternatives, 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?

The description claims the tool cancels a subscription, which is a mutation, but annotations include readOnlyHint: true, creating a direct contradiction. The description does not correct or clarify this inconsistency, and does not disclose other behavioral traits like authorization or rate limits beyond the 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 sentences with no wasted words. Information is efficiently front-loaded: action, ownership, and effect on data.

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

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

Given the simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and data handling behavior (deactivation vs deletion). It lacks details on error cases (e.g., non-existent id) but is fairly complete for a straightforward mutation.

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

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

Schema description coverage is 100% for the single parameter 'id', which is already described as a UUID returned by subscribe. The description adds no further semantic meaning beyond what the schema provides.

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

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

The description clearly states the action (cancel a subscription by id), specifies the resource, and distinguishes from sibling 'subscribe' by mentioning ownership enforcement. It provides a specific verb and resource.

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 'Ownership is enforced — you can only cancel your own subscriptions', which is a key usage guideline. It also mentions the row is deactivated not deleted, preserving historical events. However, it does not explicitly compare to sibling tools like 'list_subscriptions' or provide when-not-to-use 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. The description adds valuable behavioral context: it returns a verdict (confirmed, refuted, etc.), an extracted structured form, actual value with a pipeworx:// citation, and percent delta. It also reveals that the tool replaces 4-6 sequential calls, which is useful. No contradictions with annotations.

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

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

The description is a single paragraph that is well-structured, starting with usage cues and example phrasings, then specifying scope and return value. It packs substantial information without redundancy. Could be slightly more concise, but every sentence earns its place.

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

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

Given that the tool has only one parameter and no output schema, the description compensates fully by explaining the domain, the types of claims supported, and the exact return structure (verdict types, citation, delta). It is complete enough for an agent to understand when and how to invoke the tool correctly.

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

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

The input schema has 100% coverage and describes the 'claim' parameter as a natural-language factual claim with examples. The tool description reinforces this with additional examples and specifies the domain (company-financial). It adds meaning by clarifying acceptable claim types and the expected format, going beyond the schema description.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources, with specific examples ('fact check', 'verify the claim that…'). It distinguishes itself from siblings by specifying the domain (company-financial claims via SEC EDGAR + XBRL) and listing the exact verdict types, 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines the supported claim types (company-financial). While it doesn't directly mention alternatives for other claim types, the sibling list includes tools like 'bet_research' and 'compare_entities' that might be used instead, but this is implicit. The guidance is clear enough for most cases.

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