Finnhub

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

Adds significant detail beyond annotations: returns per-model {score, confidence, signals, raw_response} + combined view, billing model (free default, BYO key for Anthropic). Annotations already indicate read-only and idempotent, and description aligns perfectly.

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 main purpose and key details. Efficiently communicates all critical 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, description fully specifies return shape (per-model structure + combined view). Covers all parameters and side effects. No gaps given the tool's complexity.

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

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

Adds meaning beyond schema: default model behavior, how to use _apiKey for Anthropic, and context disambiguation. Schema coverage is 100%, but description provides essential usage context, justifying above baseline.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by being more general (any entity) and focusing on AI visibility scoring.

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

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

Describes use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides context on default vs. paid models but does not explicitly mention when not to use or list 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 context beyond annotations: mentions routing to 4,552 tools, fills arguments, returns structured answer with citation URIs. 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?

Every sentence adds value: preference, usage guidelines, examples, differentiation. Front-loaded with key message. No wasted words.

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

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

Covers usage context, behavior, and expected output (structured answer with citations). Missing explicit mention of error handling or edge cases, but sufficient given tool simplicity.

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 parameter descriptions. Description adds semantic context on what types of questions are suitable, but doesn't add new parameter-level details 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 tool routes questions to a large database of sources, provides specific examples, and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives when-to-use vs alternatives (grounded for verbatim evidence, deep_research for broad questions). Also lists trigger phrases.

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

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

Discloses behavioral traits beyond annotations: extraction process, response format with evidence and refusal reasons, extra LLM call cost. Annotations already indicate read-only, idempotent, non-destructive; description adds context 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?

Description is slightly verbose but well-structured and front-loaded with key info. Every sentence adds value, though could be tightened without losing clarity.

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

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

Given complexity and absence of output schema, description fully explains purpose, usage, behavior, output format with success and refusal cases, and cost trade-offs. Complete for high-stakes use.

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

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

Schema coverage is 100% with parameter descriptions. The description adds minimal additional meaning beyond what schema provides (notes aliases), so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' that returns answers with evidence and explicit refusals, distinguishing it from sibling tool ask_pipeworx by emphasizing groundedness and cost.

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 when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and advises preferring ask_pipeworx for casual lookups, providing clear when/when-not 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 declare read-only, idempotent, non-destructive. Description adds extensive behavioral details: fan-out logic, response shapes, resolver contract, safety blocking for low confidence/closed markets, spread warnings, and cancellation rule parsing. 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?

Very long and dense, but well-structured with labeled sections. Front-loads main purpose. Every sentence adds information, but length may overwhelm agents. Not succinct, but 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?

No output schema, so description fully compensates by detailing response fields (market, analysis, evidence, resolver contract, parent_event, news). Covers edge cases, error states, and resolution risk. Very thorough 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% with short descriptions. The tool description enriches parameter meaning: explains depth (quick vs thorough), include_raw (size trade-off), and market input flexibility (slug, URL, question). 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?

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data. Provides specific use cases ('should I bet on X') and distinguishes from sibling tools like polymarket_edges via its comprehensive data-fetching 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 lists when to use (bet analysis, edge detection) and gives example queries. Does not explicitly state when not to use, but the context is clear from examples and comparison to siblings.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details what data is pulled for each type (company: 10-K metrics with fiscal year handling; drug: FAERS counts, FDA approvals, trials), sorting by primary metric, and citation URIs. This fully discloses behavior.

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 and dense with information. Every sentence adds value, and the structure efficiently covers purpose, usage, and behavior.

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 entity types, multiple data sources, sorting, citations), the description is highly complete. It explains return data and citations despite no output schema. Siblings like entity_profile are implicitly handled by the usage guidance.

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

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

Schema has 100% coverage, but the description adds examples (tickers/CIKs for company, drug names) and explains sorting. It adds value beyond the schema, justifying a 4.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit examples like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives query examples that trigger the tool. It also mentions it replaces 8–15 sequential lookups, providing clear when-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 declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds critical behavioral context: account requirement, depth plan limitations, return format (findings packet with evidence, confidence, gaps), and expected duration (15-60s). 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 relatively long but well-structured, front-loading critical account information. Each sentence adds value, though some details (like the exact tool count) could be slightly trimmed without loss.

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 fully covers return format, limitations (gaps[], news topics), and prerequisites (account). No gaps for agent understanding.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the depth enum values ('quick=3, standard=5, thorough=8 paid') and clarifying the question parameter accepts natural language, broad/multi-part queries. This goes beyond what the schema alone provides.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets. It distinguishes itself from sibling tools like ask_pipeworx by specifying that it uses parallel tool routing and is not an open-web search.

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 when-to-use (broad/multi-part questions over structured data), when-not-to-use (single lookup, breaking news), and names alternatives (ask_pipeworx). This helps the agent decide correctly.

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. The description adds value by noting that each result is ready to call directly (no second schema lookup), and implies a search-based behavior. No contradictions.

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

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

The description is a single dense paragraph. It front-loads purpose and provides a comprehensive list of domains and return format. It could be slightly more structured, but every sentence adds value without redundancy.

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

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

Without an output schema, the description fully explains the return content: top-N relevant tools with names, descriptions, full input schemas, and curated examples, ready to call. This is complete for a discovery tool.

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

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

100% schema coverage means all parameters are already documented. The description enhances understanding by explaining the 'query' parameter accepts natural language and providing examples (e.g., 'analyze housing market trends'). It also mentions the 'limit' parameter and defaults.

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 lists specific domains (SEC filings, financials, etc.) and distinguishes it from sibling tools by positioning it as a meta-tool for discovery, not a specific data retrieval 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?

Explicit instructions: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and alternatives.

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

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

Beyond the annotations (read-only, idempotent), the description explains it fans out to multiple sources in one parallel call, notes the USPTO patent API sunset and soft-fail behavior, and lists the return fields. No contradictions with annotations.

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

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

The description is front-loaded with trigger examples and structured logically: purpose, usage priority, data sources, return fields, parameter guidance. It is slightly verbose but 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?

Despite no output schema, the description details all return fields (cik, company_name, filings with URIs, fundamentals, patents, news, LEI). It addresses limitations (patent API, name not supported) and assumes no additional context is needed 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?

Input schema has 100% coverage with descriptions. The description reinforces that only ticker or CIK is accepted, names are not supported, and suggests using resolve_entity for names. This adds usage context beyond the schema, but the schema already adequately describes the parameters.

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 clear trigger phrases and explicitly states it provides a full cross-source profile of a US public company in one call. It lists the specific data sources and output fields, making the tool's purpose unambiguous and distinguishing it from sibling tools like get_company_news.

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 prefer this tool over chaining individual lookups for holistic views. Clearly states that company names are not supported and recommends using resolve_entity first, 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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful beyond the annotations. 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 two sentences, front-loaded with purpose, and every sentence adds value without unnecessary words.

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

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

Given low complexity (one required parameter, no output schema, annotations provided), the description fully covers what the tool does, when to use it, 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?

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description does not add additional parameter meaning, so baseline 3 applies.

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

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

The description clearly states the verb 'delete' and the resource 'a previously stored memory by key'. It distinguishes from sibling tools like remember and recall, which are explicitly mentioned.

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 specific when-to-use guidance ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember and recall.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context beyond these: it fetches the page, extracts title/description/key links, emits standard markdown, and outputs a text blob ready for deployment. No contradictions.

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

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

Four sentences front-loaded with purpose, then method, output format, and use cases. Every sentence adds value without redundancy. Highly efficient.

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

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

With full schema coverage, annotations present, and no output schema, the description fully explains tool behavior (fetch, extract, emit), output format, and deployment suggestion. It is complete for an AI agent to use correctly.

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

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

Schema description coverage is 100% with both parameters already well-documented. The description repeats default/max for max_links but adds no new parameter-level semantics. 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 'Generate', the resource 'llms.txt file for any URL', and the purpose 'so AI crawlers can index the site cleanly'. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating a specific file format.

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: getting a client's site indexed, drafting for own project, auditing competitor. However, it does not include exclusions or when not to use this tool versus alternatives, missing some guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds return format details (headline, summary, source, URL) but these are likely covered by the output schema.

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

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

Two sentences plus an example. Front-loaded with the core purpose. No unnecessary words.

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

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

Given the annotations, schema, and output schema, the description covers the essential: action, parameters, and return format. It lacks mention of API source (Finnhub) but the schema covers the API key parameter.

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 provides full descriptions for all 4 parameters (100% coverage). The description adds an example but no new parameter semantics beyond what is already structured.

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 ('Get recent news articles'), the resource ('a company'), and the date range. It includes a concrete example. While not directly distinguishing from siblings, the purpose is unmistakable.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., deep_research or entity_profile). The description only defines functionality, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's addition is minimal. It correctly states 'get' as a read operation but does not elaborate on any behavioral traits beyond what annotations provide.

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 sentences and an example, no wasted words, and front-loads the core purpose effectively.

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, the description covers the essential functionality. An output schema exists, so return values are addressed elsewhere. Minor improvement could mention the output briefly, but overall it's 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 descriptions for all three parameters. The description adds an example usage, which helps illustrate usage but does not provide significant new meaning beyond the schema.

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

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

The description clearly states the tool retrieves 'upcoming and recent earnings reports across the market' with optional date filtering, which is specific and distinct from sibling tools like 'get_company_news' or 'get_quote'.

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

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

The description implies usage by mentioning optional date range filtering and providing an example, but it does not explicitly specify when to use this tool over alternatives or any context about exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns real-time data with price, change, volume, but does not disclose error handling, rate limits, or consequences of invalid inputs. Annotations cover the safety profile adequately.

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: one stating purpose and one providing an example. No redundant information, front-loaded with the core functionality.

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

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

Given the presence of an output schema (declared but not shown) and annotations, the description covers essential functionality. Lacks mention of error handling or behavior for invalid symbols, but for a simple quote tool, it is reasonably complete.

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

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

Input schema covers 100% of parameters with descriptions. The description adds an example demonstrating proper parameter format, which reinforces usage but does not add new semantic meaning beyond the schema.

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

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

The description clearly states the tool retrieves a real-time stock quote including current price, change, and volume. It does not explicitly distinguish from sibling tools, but the sibling list contains tools for different purposes (news, earnings, etc.), so differentiation is implicit.

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

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

No explicit guidance on when to use this tool versus alternatives. The example shows typical usage, but there is no mention of prerequisites or when not to use it. Implied usage based on context, but it lacks direct instructions.

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 readOnly, idempotent, non-destructive hints; description adds return fields and default behavior (active only) but does not significantly extend behavioral disclosure 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: purpose, return fields, usage guidance. No unnecessary information, front-loaded effectively.

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

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

No output schema, but description lists all return fields. Usage context is provided. Could mention pagination or limitations, but for a simple list tool it is adequate.

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

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

Schema covers the sole parameter (include_inactive) with full description; description adds no further parameter detail, but baseline score is appropriate given 100% schema coverage.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools subscribe and unsubscribe by listing what is returned, making it unique.

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 context: use to review monitoring before adding more or to find an id to cancel. Does not explicitly state when not to use, but adequately guides 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 rate limit (5 per identifier per day), free usage, and that it doesn't count against tool-call quota, going beyond annotations which are all false.

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

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

Every sentence serves a purpose, front-loaded with core action and usage rules, 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?

Covers purpose, usage, rate limits, free nature, and what to include in each field, fully adequate for a feedback tool with no 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%, but description enriches each parameter with examples (e.g., enum values explained) and optional context, adding value beyond the schema.

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

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

Explicitly states the tool sends feedback to Pipeworx team, enumerates categories (bug, feature, data_gap, praise), and distinguishes from sibling tools that are query/investigation oriented.

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

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

Clearly specifies when to use each feedback type and what not to do (don't paste end-user prompt), providing actionable guidance.

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

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

Adds caching info (5min-1h) and data source details (CF analytics-engine, no PII) beyond annotations. Already covered by readOnlyHint and 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 concise (4 sentences), front-loaded with purpose, then use cases, then technical details. No redundant 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?

Explains outputs (top tools, packs, volume) and caching. Adequate for a simple read-only tool with one optional parameter, though output structure could be more explicit.

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

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

Schema description coverage is 100% and fully documents the 'window' parameter. The tool description does not add additional semantics 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 returns top tools, packs, and call volume over a window. It uses specific verbs and resources, distinguishing it from sibling tools like discover_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?

Lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use case). However, it does not provide explicit when-not-to-use or alternative tool suggestions.

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 semantic anchor (Jaccard threshold 0.30), partition filter (placeholder slugs), fill check integration, 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?

Description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with purpose. Slightly verbose for the mode definitions, but justified by complexity.

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

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

Covers all modes, input options, internal logic, edge cases (placeholder filtering, Jaccard similarity), and output structure (opportunities[], partition_check, fill check). No output schema, but response fields are 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?

Schema description coverage is 100%; description adds concrete examples (event slugs like 'fed-decision-may-2026', topic seeds like 'Fed rate decision') and explains mode behavior 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. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly describes when to use each mode (no args for trending scan, event for specific market, topic for cross-event scanning) and when not to (e.g., when realizable_edge_pp ≤ 0 after fill check). Also refers to sibling tool for custom sizing.

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

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

The description provides extensive behavioral context beyond annotations, including model details, caching behavior (1h KV-level cache keyed on knobs), diagnostic output for empty segments, and the edge calculation methodology. It does not contradict any annotation (all annotations are safe/read-only).

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 densely packed with technical details. While every sentence adds information, it lacks concise front-loading and could overwhelm agents scanning for the core purpose. Restructuring with a brief summary followed by details would improve usability.

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 (9 parameters, no output schema), the description covers the response structure (by_segment, fed_candidates, diagnostics) and all critical edge fields. It explains filter behaviors and caching, making the tool's behavior fully understandable without an 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?

With 100% schema coverage, the schema already thoroughly describes each parameter. The description adds value by explaining nuances like why min_kelly does not filter partition arbs and why slippage_pp default is 0.3, providing practical usage guidance that exceeds 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 scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, targeting the 'what should I bet on today' use case. It distinguishes from sibling tools by describing its unique model-driven, structural arbitrage, and concentrated longshot segments.

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 frames the tool for daily betting opportunity discovery and explains the three segments with their triggers, guiding when to expect results. It does not explicitly exclude alternatives but provides enough context to infer proper use; however, no direct comparison to sibling tools like polymarket_arbitrage is given.

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. The description adds significant behavioral context: reads from daily snapshots, computes trend and decay, includes expired opportunities, notes gaps due to cache-miss. 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 a single paragraph that is dense but not overly verbose. Every sentence contributes useful information. Structure could be improved with bullet points or sections, but overall it's 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?

Given no output schema, the description thoroughly explains the response structure: tracked[], expired[], snapshot_dates[]. It also covers limitations and edge cases (snapshot gaps, TTL). This makes the tool's behavior fully understandable.

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

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

The schema already covers parameter descriptions (100% coverage). The description adds value by clarifying defaults (days=14, window='1wk'), the clamp for days (2-30), and explains how days and window affect the data selected.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and trend. It distinguishes from sibling 'polymarket_edges' by focusing on historical time-series and trend computation.

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: to determine if an edge is fresh or old. It implies usage for historical analysis but does not explicitly state when not to use or mention alternatives. It provides context about limits (60-day TTL, snapshot gaps).

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

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

Despite annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds substantial context: it explains ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), basket mechanics (per-leg fill detail, thin_legs), and critical risk warnings (forced directional risk, dominant loss mode). 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 thorough and well-organized, starting with core purpose, then requirements, then detailed mode breakdowns, and concluding with usage guidance. While every sentence adds value, it is somewhat verbose; a slight tightening could improve conciseness without losing substance.

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 provides a comprehensive list of return values for both modes (single-market: top_of_book, vwap_fill_price, slippage_pp, etc.; basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, etc.). It also covers edge cases like partial fills and thin books, making the tool's function and limitations fully understandable.

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

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

Schema description coverage is 100%, and the description adds further meaning: it explains default values (side, size_usd), context for each parameter (e.g., 'max spend on buys, target proceeds on sells'), clamping range (10–1,000,000), and the auto-detection logic for basket side. This enriches the 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It differentiates between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making its distinct 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 provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills cause unhedged directional risk) and states the input requirement ('REQUIRES one of market or event').

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: compatibility warning triggers, temporal alignment checks, skipped cross-type/subtype counters, and the token-overlap matching logic. This goes well beyond what annotations provide, fully disclosing internal behavior and edge cases.

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

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

The description is well-structured, front-loading the purpose, using bold for key terms, and breaking into logical sections. While lengthy, the complexity of the tool justifies the detail; every sentence contributes to understanding.

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

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

Given the tool has no output schema, the description fully describes the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases. It covers all necessary information for correct invocation and interpretation, making it 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 coverage is 100% with descriptions for all three parameters. The description adds value by explaining the two modes, providing examples, and clarifying that explicit tickers override the topic mapping. This contextual information helps agents use parameters correctly.

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 the same resolving question. It uses a specific verb ('cross-venue spread') and resource ('Kalshi and Polymarket'), distinguishing it from sibling tools like 'polymarket_arbitrage' which likely focus on within-venue arbitrage.

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

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

The description explains two usage modes (topic shortcuts and explicit tickers) and sets expectations that most pre-mapped topics currently return compatibility warnings, helping agents understand when results are meaningful. However, it does not explicitly contrast with alternatives like 'polymarket_arbitrage' or other research tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping and pairings but does not detail behavior for missing key. Bar is lower due to annotations, so score 3.

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 with clear front-loading of primary purpose. 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 tool with one optional param and no output schema. Covers purpose, usage, scoping, and related tools.

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 adds value by explaining that omitting key lists all keys, providing behavior semantics beyond the schema.

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

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

Description clearly states tool retrieves a saved value or lists keys if omitted, with specific verb 'retrieve' and resource 'previously saved via remember'. Distinguishes from siblings like remember 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 mentions using it to look up stored context without re-deriving, scoping to identifier, and pairing with remember/forget. Could be slightly more explicit about when not to use, but adequate.

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

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

The description states that setting mark_read:true flags events as read, implying a state change. This contradicts the annotation readOnlyHint: true, which indicates no modification. The contradiction is a serious inconsistency.

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, front-loaded with purpose, and covers return fields, parameters, and alternatives in a well-structured paragraph without 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?

The description explains return fields, filtering, mark_read behavior, and alternative access method. However, the contradiction between readOnlyHint and mark_read effect reduces reliability, and unread_only is not elaborated beyond 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% and description adds value by providing usage examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explaining the effect of mark_read. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states it retrieves recent alerts from a subscription feed, using specific verbs like 'Pull fired events'. It distinguishes from siblings like 'list_subscriptions' by focusing on events rather than subscription management, though no explicit sibling comparison is given.

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

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

The description mentions polling is appropriate and provides an alternative API endpoint for scripts/dashboards, giving some usage context. However, it does not explicitly compare against sibling tools or state when not to use this tool.

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

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

Beyond annotations (readOnlyHint, etc.), description details data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback logic, and output structure. 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?

Description is comprehensive but slightly lengthy; could be more structured with bullet points. However, every sentence adds value and front-loads with example queries.

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

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

Given no output schema, description adequately explains return format (changes[], total_changes, URIs) and references sibling tool for alternative use cases.

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% description coverage, but description adds examples and explanations for `since` (ISO vs relative) and `value` (ticker vs CIK), enhancing 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?

Description explicitly states purpose as a change feed for a company over a time window. It uses specific verbs ('fans out', 'returns') and distinguishes from sibling tool entity_profile for static profiles.

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

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

Provides clear when-to-use examples ('What's new with X', 'latest on Y') and when-not-to-use guidance ('Use entity_profile instead'). Also recommends typical 'since' values like '30d'.

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

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

Adds behavioral context beyond annotations: data persistence (24h for anonymous, persistent for authenticated) and scoping. Annotations already cover non-destructive and idempotent, so not repeated. No contradictions.

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

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

Four sentences, front-loaded with core purpose, no unnecessary words. Every sentence adds value.

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

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

Given simple schema (2 strings), no output schema, and good annotations, the description covers all necessary context: usage, pairing, lifetime, and scope.

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 params fully; description adds examples for key naming conventions and clarifies value can be any text, aiding interpretation.

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 saves data for reuse across conversations/sessions, using specific verbs and resource. It distinguishes from siblings like 'recall' and 'forget' by mentioning them as alternatives.

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'), mentions scoping by identifier, persistence differences for authenticated vs anonymous, and pairs with recall/forget for retrieval/deletion.

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, and destructiveHint=false, which already convey a safe, non-destructive operation. The description adds value by revealing that each call cascades through several lookup endpoints and replaces 2-3 manual lookups, giving insight into internal behavior.

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 examples and clearly structured with supported types listed. However, it is slightly verbose with internal details (e.g., 'pipeworx://edgar/company/{cik}') that might not be essential for selection.

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 tool has two entity types with different outputs, and no output schema. The description compensates by explaining return values for each type (ticker, CIK, RxCUI, etc.), making it sufficiently complete for an agent to understand what to expect.

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 basic descriptions for both 'type' and 'value' parameters. The description greatly enriches this by detailing the return format for each entity type (e.g., 'returns ticker + 10-digit CIK + company_name from SEC EDGAR'), which helps the agent understand the output context and usage.

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

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

The description opens with concrete examples ('What's the ticker for…' / 'find the CIK for…') that immediately clarify the tool's purpose. It explicitly states it resolves a name to a canonical identifier required by other tools, which distinguishes it from sibling tools that work with already-resolved 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 explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke this tool. It lacks an explicit 'when not to use' statement, but the context makes it clear this tool is for resolution, not for other tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. This enriches understanding without contradiction.

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

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

The description is concise: 3 sentences, front-loaded with purpose. Every sentence adds value—no fluff. Perfectly sized for 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?

With no output schema, the description adequately describes return fields (ranked list, score, confidence, signal density). All 4 parameters are documented. For a 4-param comparison tool, this is sufficient and complete, leaving little 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 coverage is 100%, so baseline is 3. The description adds meaning beyond schema: clarifies that 'entities' expects brand/business/product names, first entry as subject, and explains context disambiguation and the role of models and _apiKey. This helps agents use parameters correctly.

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: comparing AI visibility across multiple entities side-by-side. It specifies the verb 'compare' and resource 'AI presence', and differentiates from sibling tools like ai_visibility_check (single probe) and compare_entities (likely 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 clear use case: competitive AI-marketing audits, with an example question. It implies when to use (multi-entity comparison) but does not explicitly exclude or mention alternatives. Still, the context is strong enough for an agent to infer 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?

Annotations already declare safe/idempotent. Description adds key behavioral traits: fans out across two external services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

Single paragraph with dense information; efficient but could be better structured (e.g., bullet points for return values). No wasted sentences.

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

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

No output schema, but description lists exact return fields (summary block, advisories, links, alternatives) and behavior (partial failures). Fully adequate for a composite tool with good annotations.

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 completely (100% coverage). Description adds contextual details: scoped packages accepted, version defaults to latest. 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?

Clear verb+resource: 'scan_dependency' composite check for npm packages, covering licenses, advisories, bundle size, etc. Distinct from siblings like deps.dev:version for other ecosystems.

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

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

Explicitly states when to use ('agent asks is X safe/popular/small') and alternatives (other ecosystems go to deps.dev:version). Includes note on partial failures and timing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side effects. The description states that it returns matching symbols with descriptions, which adds some return structure context but does not disclose additional behavioral traits like rate limits or required authentication beyond what's in the schema.

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

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

The description is two sentences: the first clearly states the purpose, the second gives a concrete example. No wasted words, and the essential information is front-loaded.

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

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

For a simple lookup tool with only two parameters and a clear purpose, the description is complete. It covers what the tool does, how to use it via example, and what to expect in return. The presence of an output schema means the return structure doesn't need to be detailed in the description.

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

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

Schema coverage is 100% with both parameters described in the input schema. The description adds an example but no additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches for stock ticker symbols by company name or keyword and returns matches with descriptions. The verb 'search' and resource 'stock ticker symbols' are specific, and the purpose is unambiguous. It distinguishes from sibling tools that deal with already-known symbols like get_quote or get_company_news.

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 includes an example that implies usage, and the purpose is straightforward. However, it does not explicitly mention when not to use the tool or provide alternatives, though none are necessary given the narrow scope.

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 and idempotent; description adds concrete details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation and flagging. No contradictions with annotations.

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

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

Single dense paragraph front-loading purpose, usage, behavior, and limitations with no wasted words. 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?

Despite no output schema, description explains returns (top-N passages with offsets and scores), model, windowing, truncation policy. For a 3-param tool, this is thorough and addresses likely agent questions.

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 enhances understanding with examples for query (e.g., 'supply-chain risk') and specifies limit's range (1-20, default 5). Adds 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 'Semantic search INSIDE a fetched record' with concrete examples like SEC 10-K body and article. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and explaining when to use (record too big for prompt).

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

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

The description explicitly states 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. It provides clear context but does not explicitly exclude other scenarios or list alternatives beyond the pair.

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 this is a write, non-destructive, idempotent operation. The description adds context such as OAuth requirement, SMS cap (10/day), and phone verification needed. It does not mention side effects like costs, but the annotations already cover safety.

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 clear sections for types and delivery channels. It front-loads the purpose. However, it is slightly verbose, especially in the webhook details, which could be condensed.

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

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

Given 3 parameters, required 2, nested objects, and no output schema, the description covers all necessary information: explains each type, its params, and delivery options with constraints. It is complete for the agent to understand and 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?

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it explains each type with examples (e.g., sec_8k items codes), clarifies params structure per type, and details delivery channel semantics (email, SMS, webhook) including requirements and limitations.

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 and returns the new subscription id. It distinguishes 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 for when to use (to subscribe to alerts), lists supported types with examples, and mentions prerequisites (Pipeworx OAuth account). It does not explicitly state when not to use, but sibling tools exist for unsubscribing and listing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral details: the tool returns category-bucketed example questions with tool+argument shapes drawn from a live catalog, and is meant for discovery. This enriches understanding beyond annotations.

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

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

The description is multi-sentence but front-loaded with key phrases and structured logically: example queries, purpose, output, usage. While it could be slightly trimmed, every sentence earns its place and the structure aids readability.

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

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

Despite lacking an output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes). For a discovery/onboarding tool, this is sufficient and leaves no critical gaps given the annotations and simple parameter.

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 optional parameter 'topic' is described in the schema with coverage at 100%. The description adds value by giving examples of valid values (finance, pharma, betting) and explaining the effect (focusing the output), which helps the agent use it correctly.

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 the onboarding entry point for new agents, listing example user queries and explaining it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its role as a first step for learning what Pipeworx can do.

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 advises to use this tool FIRST when you do not know what Pipeworx can do, or to learn how to call meta-tools. It also explains calling with no arguments for full spread or with topic for focus, providing clear usage context and alternatives.

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

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

Discloses critical behaviors beyond annotations: ownership enforcement, deactivation vs deletion, and historical availability. No contradiction with annotations (destructiveHint=false, idempotentHint=true).

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-load the core action and then provide essential behavioral details. Every sentence serves a purpose with no waste.

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 mutation with one parameter and annotations present, the description fully covers purpose, ownership, side effects, and historical impact. No output schema is needed.

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

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

Schema provides full coverage (100%) and includes description for the 'id' parameter. The description does not add meaningful semantic detail beyond what the schema already conveys.

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 ('Cancel a subscription by id'), specifies the resource (subscription), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and explains that deactivation preserves history via recent_alerts, providing clear when-to-use and alternative 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 discloses key behavioral traits: returns a verdict (confirmed/refuted/etc.), extracted structured form, actual value with citation, and percent delta. It mentions relying on SEC EDGAR + XBRL. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, but the description adds value by explaining the return format and data sources.

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 somewhat long but well-structured: trigger phrases first, then usage guidance, then specifics about supported claims and return values. Every sentence adds value, though a bit wordy. Could be slightly more concise but still effective.

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

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

Given the tool's complexity (single NLP call replacing multiple steps) and absence of an output schema, the description is remarkably complete. It explains the domain, data sources, return values, and replaces sequential calls. No gaps are evident for the described functionality.

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?

Only one parameter 'claim' with 100% schema coverage. The description adds examples and clarifies the natural-language format, going beyond the schema's simple description. This helps the agent understand what constitutes a valid input.

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: natural-language claim verification against authoritative sources. It provides specific verb+resource (validate claim) and distinguishes itself from siblings by noting it replaces multiple sequential calls. The inclusion of trigger phrases like 'Is it true that…' and 'fact check' makes the purpose unmistakable.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims) and provides example triggers. It does not explicitly state when not to use it, but the context is clear enough. Missing explicit exclusions for other claim types.

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