Tomorrow Io

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating safe operation. The description adds value by explaining the default model, API key purpose, and that users pay Anthropic directly. 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 approximately 80 words, well-structured with the main action first, followed by model details, API key usage, return values, and use cases. No unnecessary words; every sentence earns its place.

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

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

Given the 4 parameters and no output schema, the description adequately explains parameters, return structure (per-model and combined view), and use cases. It could mention limits or pagination, but the level of detail is sufficient for an audit tool with strong 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 coverage is 100%, so the description is not required to repeat schema details. However, it adds useful context: the default model, API key necessity, and context disambiguation. This provides meaning beyond the raw schema.

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

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

The description clearly states the tool's action (probe LLMs for knowledge about an entity) and what it returns (score 0-100, per-model data). It distinguishes itself from other tools like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring, though it does not explicitly compare to siblings.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional API key. However, it does not list specific situations where this tool should be avoided or suggest alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=False. Description adds: routes question to the correct sub-tool among 3,586 tools, fills arguments, returns structured answer with stable citation URIs. No contradictions.

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

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

Front-loaded with the key priority statement, but the list of domains and examples is somewhat lengthy. Every sentence adds value, but could be slightly more concise without losing content.

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

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

Given the complexity (6 aliases, no output schema), the description covers purpose, behavior, input expectations, and output format (structured answers with citations). Missing explicit error handling info, but overall sufficient.

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

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

Schema coverage is 100% with all parameters described. The description goes beyond schema by explaining the input is a natural language question and providing examples, which adds meaning and guides usage effectively.

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 answers factual questions using authoritative structured data, lists specific domains (SEC filings, FDA drugs, etc.), and distinguishes it from web search. The verb 'answer' and resource 'structured data with citations' are precise.

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 provides clear when-to-use criteria: factual questions about real-world entities, specific query types ('what is', 'look up'), and examples. Implicitly indicates when not to use (non-factual), but still highly directive.

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, destructiveHint. Description adds details on refusal modes (not_in_source, no_tool_match, etc.), return format {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and extra LLM call cost. 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 dense but well-structured: starts with purpose, explains process, then usage guidelines. Every sentence adds value; not overly verbose 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 complexity (refusal logic, extra LLM call) and no output schema, description covers return object, refusal reasons, and usage context. Explains what happens on success and failure, making it mostly complete.

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

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

Schema coverage is 100% with 6 parameters all aliases for 'question'. Description states 'Your question in natural language' but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it selects the right tool, fills arguments, fetches data, and extracts answer using only the tool result. Distinguishes from sibling ask_pipeworx by noting extra LLM call 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 says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims). Also advises to 'prefer ask_pipeworx for casual lookups', providing a clear when-to-use and when-not-to-use.

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

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

The description extensively covers behavioral traits beyond annotations: fan-out logic, resolver contract, parent event extraction, news fallback mechanisms, safety blocking (low confidence, closed markets), and tradeability warnings. No contradictions with annotations.

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

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

The description is lengthy but well-structured, starting with core purpose and then detailing classifiers, examples, response shapes, and safety. While comprehensive, some details (e.g., full news fallback explanation) could be condensed or moved to external docs.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, resolver, parent event, news, safety), the description is remarkably complete. It explains return structure in detail despite no output schema, covers edge cases, and provides actionable guidance for agents.

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

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

Schema coverage is 100%, and the description adds substantial context for each parameter (market input formats, depth options, include_raw behavior and size implications). It explains defaults and usage recommendations 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 researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from sibling tools like ask_pipeworx and polymarket_edges by focusing on classification and fan-out behavior.

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

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

Explicit usage examples are given ('should I bet on X', etc.), and classifiers and fan-out scenarios are provided. However, it does not explicitly state when NOT to use this tool versus alternatives like ask_pipeworx_grounded or forecast, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it explains data sources (SEC EDGAR, FAERS), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. No contradictions with annotations.

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

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

The description is concise for the amount of information it conveys, with example queries front-loaded. However, it is slightly verbose in listing all financial metrics and could be tightened without losing meaning. Overall, every sentence adds value, earning a 4.

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

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

Despite lacking an output schema, the description explains the return format (paired data + citation URIs). It covers both entity types, data sources, sorting, and fiscal year handling. For a simple tool with 2 parameters, this description is fully complete.

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

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

Schema coverage is 100% and parameters are well-described. The description adds meaning by specifying what each type pulls (e.g., 'latest 10-K revenue + net income + cash + long-term debt' for company) and constraining the values array to 2-5 items with examples. This goes beyond the schema's enum and array descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It provides example queries ('X vs Y', 'which is bigger') and specifies distinct data sources for each entity type (SEC EDGAR/XBRL for companies, FAERS for drugs). It distinguishes itself from sequential lookups, making the purpose unambiguous.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states it replaces 8-15 sequential lookups. This provides clear when-to-use guidance and identifies the alternative (sequential lookups) to avoid.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds valuable behavioral details: returns top-N tools with full schemas and examples, and emphasizes no second schema lookup. This goes beyond annotation coverage.

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

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

The description is concise, front-loaded with purpose, then lists domains and output behavior. Every sentence serves a function with no redundancy.

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

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

Given the complexity of tool discovery and 100% schema coverage, the description explains the output (top-N tools with schemas, ready to call) and when to use. It lacks a specified default limit but is otherwise complete.

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

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

Schema description coverage is 100% with clear descriptions and aliases for parameters. The description reinforces the query purpose but does not add new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Find tools by describing the data or task') and distinguishes itself from sibling tools by being a meta-discovery tool, advising to 'call this FIRST' to see available options. It lists example domains, avoiding ambiguity.

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 clearly states when to use (browse, search, discover tools) and provides a strong contextual cue ('Call this FIRST when you have many tools'). It does not explicitly mention when not to use or alternatives, but the context makes it sufficient.

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

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

Annotations already indicate read-only, idempotent, safe. Description adds context about data sources (SEC, XBRL, USPTO, news, GLEIF), return fields, and patent soft-fail. Does not contradict annotations.

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

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

Well-structured with bullet points and examples. Slightly long but every sentence adds value. 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 no output schema and high complexity (multiple sources), description fully documents return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and limitations. Complete for agent to understand behavior.

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 100%, but description adds substantial meaning: explains type enumeration (only 'company'), value can be ticker or CIK with examples, and reiterates names not supported. This goes 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 explicitly states it creates a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific sources and return fields, and distinguishes itself from sibling tools by advising preference over chaining single-pack 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?

Clear guidance: use for holistic views, and explicitly says 'names not supported (use resolve_entity first).' Also mentions patents API sunsetting, soft-failing behavior.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral context by stating the returned data structure (list of periods with conditions, temperatures, precipitation, wind) and example usage. It does not contradict annotations. No mention of rate limits or auth details beyond the schema note, but sufficient given 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 two sentences plus a code example. It front-loads the main purpose and includes essential details without redundancy. Every sentence adds value, making it highly concise and well-structured.

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

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

Given 4 parameters with full schema descriptions and no output schema, the description explains the return values (list of periods with conditions, temps, precip, wind) sufficiently. It also covers location formats and an example, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example call and clarifies the location format (lat,lon or city name) which is already in schema but rephrased helpfully. It also implicitly shows that _apiKey can be omitted. The example provides practical usage context, raising score to 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 'Get a daily or hourly weather forecast for a location' with a specific verb and resource. It distinguishes from the sibling 'realtime' by implying future-oriented data, and lists returned fields (conditions, temperatures, precipitation, wind). No ambiguity.

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 does not explicitly mention when to use versus alternatives, but the word 'forecast' contrasts with 'realtime' in sibling tools. The context is clear, but explicit guidance on when not to use (e.g., for current weather) would improve it.

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

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

Annotations already indicate destructiveHint and idempotentHint. The description adds value by mentioning 'clear sensitive data' and aligns with the destructive behavior. No contradiction, and extra context is provided 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 two sentences, achieves efficiency by front-loading the core action, and wastes no words. Every sentence contributes meaningful information.

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

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

For a simple one-parameter tool with annotations and sibling context, the description is complete. It covers the function, usage guidelines, and relationship to other tools, without needing output schema details.

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

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

Schema coverage is 100% and the parameter description ('Memory key to delete') is already present. The tool description does not add further semantics beyond what the schema provides, meeting baseline expectations.

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

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

The description clearly states the action (delete) and the resource (memory by key). It also distinguishes from sibling tools 'remember' and 'recall' by explicitly pairing with them, making the purpose unambiguous.

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

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

The description provides explicit when-to-use scenarios: stale context, completed tasks, clearing sensitive data. It also suggests pairing with related tools, offering clear context for 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 indicate safe, idempotent, non-destructive behavior. The description adds valuable behavioral context: fetches the page, extracts specific elements, and outputs standard markdown format. It goes beyond annotations without contradicting them, but could be enhanced with details like error handling or rate limits.

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

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

Two sentences with no wasted words. The first sentence covers the core purpose and output; the second provides concrete use cases. Front-loaded and efficient.

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

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

For a simple fetch-and-transform tool with only 2 parameters and clear annotations, the description covers all necessary context: what it does, how it works, output format, and use cases. No output schema is needed because the description describes the output blob.

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 for 'url' adds 'or a specific landing page' beyond the schema's 'Full URL', and for 'max_links' adds default/max context. This is minimal added value; the schema already provides complete descriptions.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the action (generate), resource (llms.txt), and context (for AI crawlers). It distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on the specific output format and use case.

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 enumerates explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. It does not explicitly state when not to use, but given the tool's narrow purpose, the guidance is sufficient. A brief mention of alternatives or exclusions would push to 5.

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, read-only, non-destructive behavior. Description adds specifics about return fields and default behavior (active only), enhancing transparency without contradicting annotations.

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

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

Two concise sentences: first defines purpose and output, second gives usage guidance. No wasted words.

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

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

Despite no output schema, description enumerates return fields. With one optional parameter and clear annotations, the description fully covers what an agent needs.

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

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

Schema coverage is 100% and the schema description is clear. The tool description does not repeat parameter info but contextually implies the default (active only). Baseline score is appropriate.

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

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

Clearly states it lists active subscriptions and specifies the returned fields (id, type, etc.), distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context and alternative actions.

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 limits (5 per identifier per day), that it's free and doesn't count against tool-call quota, and how feedback is processed (digests, roadmap influence). Annotations are all false, so no contradiction.

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

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

Three dense sentences front-load purpose, followed by usage and behavioral details. No fluff; 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?

Covers all necessary aspects: what to send, when, how to format, rate limits, and impact. No output schema needed; tool is one-way feedback.

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

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

Schema coverage is 100%, but the description adds significant context: explains each enum value with concrete examples, instructs on message format, and clarifies the optional context fields' purpose.

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

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

Explicitly states the tool sends feedback to the Pipeworx team, covering bugs, feature requests, data gaps, and praise. Clearly differentiates from sibling tools which are for search, subscriptions, and 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?

Provides detailed when-to-use scenarios (bug, feature/data_gap, praise) and a specific when-not-to-use (do not paste user prompts). No alternative tool is needed for this purpose, making guidance clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, caching behavior (5min-1h). No contradiction.

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

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

Front-loaded with key function and return types, followed by structured use cases, then technical details. Every sentence is informative 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?

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, usage, behavior, and parameter semantics.

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 parameter with enum and description. Description adds value by explaining trade-offs between window lengths (short vs steady-state).

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 returns top tools, packs, and call volume, distinguishing it from siblings by focusing on other AI agents' usage on Pipeworx.

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

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

Three explicit use cases are provided (discovering hot data, confirming canonical choice, aligning use case). Lacks explicit when-not but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds significant context: algorithm details (monotonicity checks, partition sum), behavior on no args, Jaccard similarity filter, partition filter, and response structure. No contradiction with annotations.

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

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

Description is well-structured with requirement upfront, then two modes, followed by filters and response. Though lengthy, every sentence provides necessary information. Could be slightly more concise, but 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?

Given the complexity of two modes, filters, and response, the description is highly complete. It explains input requirements, algorithm, filtering logic, and output fields (opportunities array with gap_pp, suggested_trade, etc.). No output schema exists, so description adequately covers return values.

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

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

Schema coverage is 100% with descriptions. Description adds rich semantics: event mode walks child markets and checks orderings, topic mode searches related events and flattens markets. Also explains Jaccard threshold and partition filter, far exceeding 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?

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples of slugs and seed questions, making the purpose very clear even without explicit sibling differentiation.

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

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

Explicitly states that one of event or topic is required and calling with no args fails. Recommends event for specific markets and topic for cross-event scanning, explaining the advantage of cross-event mode. Lacks explicit exclusions but provides clear context for when to use each mode.

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?

Disclosures beyond annotations include caching behavior (1h KV-level), model family details (crypto_price, news_momentum, etc.), edge calculation (net of slippage), Kelly sizing caps, and 24h-move warnings. No contradictions with annotations (all readOnly/idempotent/not destructive).

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

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

Front-loaded with purpose and key output structure. Dense with information but each sentence adds value (model families, response segments, knob explanations). Slightly verbose in model detail, but overall well-structured.

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 comprehensively details output fields (by_segment, fed_candidates, _diagnostics, edge_pp_net, kelly_fraction, etc.) and explains how segments work. Given 9 parameters with 100% schema coverage, description fully compensates for missing output schema.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds extra context for knobs like min_partition_leg_kelly (explaining why min_kelly doesn't filter partitions) and max_spread_pp (suggesting value 2). Provides rationale 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly positions it for 'what should I bet on today' discovery. It distinguishes from siblings like polymarket_arbitrage by focusing on model-driven and structural arbitrage edges.

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

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

Provides explicit guidance on when to use (discover opportunities without paging) and explains configurable knobs (min_liquidity, max_spread_pp) for tradeable-edge filtering. However, lacks explicit when-not-to-use scenarios or direct comparisons to alternative tools like polymarket_kalshi_spread.

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

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

The description goes far beyond annotations to disclose behavioral traits: compatibility warning conditions, temporal alignment, skipped counters, and the rarity of real spreads. Annotations already mark it as read-only, but the description adds rich context about data quality and interpretation, with no contradictions.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the main purpose. Every sentence adds value, though it is somewhat long. It could be slightly more concise, but 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 having no output schema, the description adequately explains the response structure (leg-by-leg prices, top_spreads_pp) and safety fields. It covers key behavioral aspects like temporal alignment and compatibility warnings. Missing details like error handling are minor given the 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?

The description adds value beyond the schema by explaining the two modes and how parameters interact (explicit overrides topic). It lists the 10 topic values explicitly, which the schema only describes as a string. Schema coverage is 100%, so baseline is 3, but the description elevates it with mode semantics and override behavior.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same question, using the specific verb 'spread'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and explicitly mentions two modes (topic and explicit) with clear resource identification.

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

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

The description provides explicit guidance on when to use each mode: topic shortcuts for predefined macros and explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility warnings, implying limited usefulness. However, it does not directly compare to alternatives like using individual venue tools, though the uniqueness is implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds what data is returned (temperature, feels-like, etc.) but does not disclose additional traits like rate limits, caching, or data freshness. It is adequate but not outstanding.

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

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

Two sentences with an embedded example. Information is front-loaded: purpose first, then data fields, then parameter details. No wasted words.

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

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

Given three parameters and no output schema, the description explains input format and lists output fields. It lacks explicit output structure but is reasonably complete for a weather tool. Annotations cover safety, so description focuses on 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?

Schema coverage is 100% with descriptions for all params. The description adds example calls (e.g., `realtime({ location: 'new york', units: 'imperial' })`) and clarifies that location can be lat/lon or city name, which adds value beyond the schema.

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

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

The description clearly states 'Get current/real-time weather conditions for a location' and lists specific data fields (temperature, humidity, etc.). It distinguishes from siblings by focusing on real-time vs forecast (implicitly). The verb 'get' and resource 'weather conditions' are specific.

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

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

No guidance on when to use this tool vs siblings (e.g., 'forecast'). The description only tells what it does, not when to choose it over alternatives. No exclusions or prerequisites mentioned.

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

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

Adds scoping detail (identifier-based) beyond annotations' readOnlyHint/idempotentHint. 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?

Three sentences, front-loaded with action, then purpose, then scoping and pairing. No fluff.

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

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

Explains both operational modes, use cases, and scoping. Lacks return format but acceptable for a simple retrieval 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 already fully describes the key parameter; description reinforces the two modes (retrieve single vs list all) adding context.

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

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

Clearly states verb 'retrieve' or 'list', resource 'saved values/keys', and distinguishes from siblings remember and forget. Specific use cases provided.

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

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

Explicitly says when to use (look up context), mentions pairing with remember/forget, but no explicit when-not-to-use or alternatives beyond siblings.

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

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

Annotations already indicate read-only behavior, but the description adds valuable behavioral details such as the effect of 'mark_read:true' on subsequent calls, the returned fields (source, citation_uri, raw event payload), and that polling works fine. No contradictions with annotations.

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

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

The description is a single paragraph of five sentences, each serving a distinct purpose (purpose, return fields, filtering options, side effects, alternatives). It is efficient and free of fluff, though a bit more structure could improve 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?

Given that there is no output schema, the description adequately explains the return values (source, citation_uri, raw payload) and includes notes on polling behavior and external access. It covers all key aspects of the tool's 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?

Even though the input schema has 100% coverage with parameter descriptions, the tool description adds context beyond the schema by explaining what the returned data contains and how 'mark_read' affects future calls. This enhances the parameter understanding.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', making the purpose immediately obvious. It also distinguishes itself from siblings like 'list_subscriptions' by focusing on events rather than subscription management.

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

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

The description explains when to use the tool (to get recent alerts) and even mentions an alternative access method (the same feed at a URL for scripts/dashboards). However, it does not explicitly list situations where the tool should not be used or compare it to other sibling tools like 'subscribe' or 'unsubscribe'.

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 behavior beyond annotations: fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), describes fallback logic, and return structure (grouped changes, count, citations). 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 well-structured and front-loaded with examples, but it is somewhat verbose. However, every sentence adds value, so it earns its length.

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

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

Given the tool's complexity (3 required params, no output schema, multiple data sources), the description is complete. It covers behavior, parameters, return format, and alternatives.

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 meaningful context: explains 'since' formats with examples, notes only 'company' supported for type, and clarifies ticker/CIK for value. Adds value beyond the schema.

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

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

The description clearly states the tool's purpose: returning a change feed for a company over a window. It provides example queries and distinguishes from sibling 'entity_profile', which is for static profiles. The verb 'change feed' and resource 'company' are specific.

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

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

The description explicitly says when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile...'. It also gives usage hints for the 'since' parameter and typical monitoring values.

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: key-value pair scoping, persistence details (authenticated vs 24 hours), and intended use. Annotations (idempotentHint, readOnlyHint) are consistent with the description. 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 well-structured with clear front-loading of purpose and usage. Each sentence adds value, though slightly verbose. Could be slightly more concise, but overall effective.

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

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

Given the simplicity of the tool (2 required params, no output schema), the description covers purpose, usage, behavioral aspects, and sibling tools comprehensively. No significant gaps for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions and examples. Description reinforces purpose but does not add significant new parameter-specific meaning beyond the schema. However, it does tie parameters to the overall scoping and usage, earning a 4.

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

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

Description clearly states 'Save data the agent will need to reuse later' and distinguishes from sibling tools recall and forget. Verb 'Save' and resource 'data' are specific, and scope is well-defined.

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 ('when you discover something worth carrying forward... so you don't have to look it up again') and mentions alternative tools ('Pair with recall to retrieve later, forget to delete'). Also notes scoping and persistence differences between authenticated and anonymous sessions.

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 safe, idempotent read operations. The description adds significant behavioral details: internal cascading through multiple endpoints, auto-disambiguation for company (accepts ticker, CIK, or name), and specific return fields per type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). 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 appropriately sized and front-loaded with the most critical usage examples and guidance. Each sentence adds value: examples, purpose, supported types, internal behavior, and return details. No wasted words.

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

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

Despite no output schema, the description fully explains what the tool returns for each entity type (ticker, CIK, company_name + citation for company; RxCUI, ingredient, brand + citation for drug). For a 2-parameter lookup tool, this is complete. The internal cascading detail also sets expectations for response time.

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

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

Schema description coverage is 100%. The description adds value beyond the schema by providing concrete examples for the 'value' parameter (e.g., 'AAPL', '0000320193', 'ozempic') and explaining acceptance of ticker, CIK, or name for company type. This clarifies input flexibility.

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 resolves names to canonical identifiers, with specific verbs like 'resolve' and explicit examples of queries. It distinguishes its role as the first step when an ID is needed, contrasting with sibling tools like 'entity_profile' which would provide detailed profiles rather than identifiers.

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 gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It provides example queries and mentions it replaces 2-3 manual lookups. However, it does not explicitly exclude alternative tools or mention when not to use it, missing some depth in comparative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral traits: probes each entity, ranks by score, surfaces most/least recognized, returns ranked list with score/confidence/signal density. It could mention that multiple API calls are made, but the phrase 'probes each entity' implies this sufficiently.

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

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

The description is three sentences, each serving a purpose: first states the core function, second explains the process, third gives a concrete use case. Information is front-loaded with 'Compare AI visibility across multiple entities side-by-side.' No unnecessary words.

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

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

Given the tool has no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). The complexity (4 params, 1 required, no enums) is modest, and the description covers the essence. Minor omission: no mention of result limits or pagination, but likely not needed for this comparative 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 descriptions for all 4 parameters. The description adds semantic value beyond schema: clarifies that the first entity in the 'entities' array is treated as the 'subject' for narrative, and that omitting 'models' defaults to free 'workers-ai'. This helps the agent understand ordering and default behavior.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks results, and surfaces insights. It distinguishes from the sibling ai_visibility_check (single entity) by explicitly being a batch comparative tool. The use case for competitive audits is explicitly stated.

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 usage context: competitive AI-marketing audits and an example question. However, it does not explicitly state when to use alternatives like compare_entities or when not to use this tool. The implied comparison with ai_visibility_check (single vs. multiple) is present but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This informs the agent about potential delays and error handling.

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

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

The description is front-loaded with the core purpose and is efficient, but it is somewhat long. Every sentence adds value, so it earns its length, but could be slightly more concise.

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

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

The tool has only 2 parameters and no output schema, but the description thoroughly explains the structure of the return value (summary block, per-advisory detail, links, list of recent alternative versions) and handles edge cases (partial failures). This provides a complete picture for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages are accepted ('Scoped packages (e.g. "@types/node") are accepted.') and that version defaults to latest when omitted, which is not stated in the schema description.

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

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

The description clearly states it is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It uses specific verbs ('scan', 'check') and resource ('npm package') and distinguishes itself from sibling tools, none of which perform similar scanning.

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

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

Explicitly tells when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides scope limitations ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), guiding the agent away from inappropriate uses.

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, etc.), the description details truncation at 200K chars, embedding model (BGE-base-en), window size (500-char overlapping), cosine similarity, and return of offsets. This provides rich behavioral context.

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

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

The description is a concise single paragraph with three well-structured sentences. Front-loaded with purpose, no wasted words, and every sentence adds value.

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

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

Despite no output schema, the description explains what is returned (top-N passages with offsets and similarity scores), covers limitations (truncation with flag), and contextualizes within sibling tools. Nothing is left ambiguous.

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

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

Schema coverage is 100%, and the description adds valuable examples for the query parameter (e.g., 'supply-chain risk'), mentions character limits for text, and notes default for limit. This goes beyond what the schema provides.

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

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

The description clearly states the verb 'semantic search' and the resource 'INSIDE a fetched record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded. The purpose is immediately clear.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and advises pairing with ask_pipeworx_grounded. This provides clear guidance on when and how to use the 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?

The description adds significant context beyond annotations: returns a subscription id, requires authentication, details persistence, and describes delivery channels and SMS throttling. Annotations already indicate idempotent and non-destructive, but description enriches understanding.

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

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

The description is concise, front-loading the main purpose, and each sentence adds value. Minor redundancy (e.g., 'delivery channels' mentioned twice) but overall efficient.

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

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

Despite lacking an output schema, the description covers all essential aspects: purpose, parameters, auth requirements, limitations, delivery channels, and return value. Complete for a tool with 3 params and nested objects.

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

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

Schema coverage is 100%, yet the description adds meaning by explaining the structure of 'params' (e.g., ticker, items) and delivery fields, including defaults ('items defaults to all'). This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It specifies the supported type 'sec_8k' and distinguishes from sibling tools like 'unsubscribe' 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?

The description provides explicit guidance on prerequisites (Requires a Pipeworx OAuth account) and limitations (anonymous + BYO cannot persist subscriptions). It also explains delivery channels and caps (10 SMS/day). However, it does not explicitly contrast with alternatives like 'recent_alerts'.

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, the description adds critical behavior: ownership enforcement (only your own subscriptions), and that the row is deactivated not deleted, preserving history via recent_alerts. This fully informs the agent of consequences.

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

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

The description is two sentences, front-loaded with the verb 'Cancel', and every sentence adds essential information without 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 single-parameter tool with no output schema, the description explains the effect (deactivation vs deletion) and links to recent_alerts for historical events, making it complete for an agent to use correctly.

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

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

The input schema covers 100% of parameters, and the schema description for 'id' is clear. The tool description does not add further parameter details beyond what the schema provides, 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 action: 'Cancel a subscription by id.' It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation.

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 when to use this tool (to cancel a subscription) and provides constraints (ownership enforced). It does not explicitly state when not to use it, but the sibling context makes alternatives clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns a verdict with structured form, actual value with citation, and percent delta. It also mentions it replaces multiple sequential calls, which is beyond annotation scope. No contradictions.

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

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

The description is moderately long but well-structured: starts with examples, then states purpose, domain, and output. Every sentence adds value, though listing multiple example phrases could be more concise. Front-loaded with key information.

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

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

Given the tool's complexity (claim verification across structured financial data) and the absence of an output schema, the description adequately covers the returned verdict types, structured form, citation, and delta. It also specifies limitations (US public companies). Complete enough for an agent to understand behavior.

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 enriches the parameter by explaining it accepts any natural-language factual claim (e.g., 'Apple's FY2024 revenue was $400 billion') and provides interpretation guidance. This adds value beyond the schema's type/description.

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

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

The description uses specific verbs like 'validate', 'verify', 'confirm or refute' and clearly states it handles natural-language factual claims against authoritative sources. It distinguishes from siblings by specifying the domain (company-financial claims for US public companies) and explaining the output 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 explicitly states when to use the tool: whenever the agent needs to check factual correctness of a user's claim. It provides example query patterns but does not explicitly list alternative tools or when not to use it. However, the domain limitation (US public companies financial claims) is clear.

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