Hnb Hr

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context beyond that: the default free model, that _apiKey is for Anthropic and costs are borne by the user, and the output structure. It 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?

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds necessary detail without redundancy.

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

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

Despite lacking an output schema, the description explains the return structure: per-model {score, confidence, signals, raw_response} + combined view. All four parameters are covered with usage notes. Minor omission: no mention of rate limits or response time, but overall adequate.

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

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

Schema coverage is 100%, with each parameter described. The description adds value by explaining the default model behavior, that _apiKey is only needed if 'anthropic' is in models, and that context helps disambiguate. This goes 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 uses a specific verb 'probe' and resource 'LLMs', clearly stating the tool probes AI models for knowledge about an entity and scores visibility. It distinguishes from siblings by focusing on AI marketing audits and brand checks, unlike other tools like 'ask_pipeworx' or 'compare_entities'.

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.' It also explains when to provide an API key for Anthropic. However, it lacks explicit when-not-to-use guidance or comparisons to alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds operational details: routes to 5008 tools across 1318 sources, returns structured answer with pipeworx:// citation URIs, one fast call, works on every tier, handles live news. 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?

Lengthy but well-structured: starts with strong directive, then coverage, usage patterns, examples, escalation path. Every sentence adds value. Could be slightly more concise, but no wasted words.

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

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

No output schema exists, but description explains return includes structured answer with citations. Covers sources, use cases, alternatives, and escalation. Complete for the tool's purpose.

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 schema already documents parameters. Description reinforces that 'question' is natural language and lists aliases, but adds no new meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states that this tool answers factual questions using structured data from verified sources, with citations. It uses specific verbs ('routes', 'returns') and distinguishes itself from sibling tools like web search, 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', lists when to use (any factual question) and when to step up to alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad questions). Provides concrete examples of query patterns and use cases.

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, idempotent, non-destructive. The description adds context about being a full working router, not a fallback, and details the source-preference ranking 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 informative and front-loaded with key differentiators (beta, identical, improvements). 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?

Given the sibling tools, the description fully differentiates this beta variant, explains the new behavior, and provides all necessary context for an agent to use it 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 aliases for 'question' described. The description does not add new parameter information beyond what is in the schema, 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 it is a beta version of ask_pipeworx with identical functionality but candidate routing improvements, specifically source-preference ranking. It distinguishes itself from the stable router and sibling tools.

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

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

The description explains to use it exactly like ask_pipeworx when wanting the newest routing and that results are compared to the stable router. It could explicitly state when not to use it, but the experimental label implies caution.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds significant detail: routing mechanism, tool selection across 5008 tools, extraction logic, and explicit refusal reasons. 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?

Well-structured: purpose, mechanism, return format, usage guidance. Concise for the complexity covered. One could argue slight redundancy (e.g., repetition of 'ask_pipeworx'), but every sentence earns its place.

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

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

Covers return format, error/refusal modes, cost, and selection guidance. Without output schema, description provides comprehensive return structure. Context about 5008 tools and 1318 sources adds useful 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 coverage is 100% with parameter descriptions already. The description briefly mentions 'question in natural language' but adds little beyond schema. Baseline 3 is appropriate as schema does the heavy lifting.

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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from ask_pipeworx by explaining the extra extraction step. The verb 'Extracts answer using ONLY the tool result' and the return format make the purpose precise and 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?

Explicitly states when to use ('high-stakes reads', 'when answer will be quoted, cited, or acted on') and when not ('prefer ask_pipeworx for casual lookups'). Also notes cost trade-off ('one extra LLM call'), guiding optimal selection.

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

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

Annotations indicate a safe, idempotent read operation. The description adds extensive behavioral context: how the tool resolves markets, fans out to data sources, response shapes (market, analysis, evidence), resolver contract, parent event extraction, news handling with fallbacks, and various safety mechanisms (low-confidence short-circuit, closed market handling, illiquid spread warnings, resolution-rule risk). 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 comprehensive but somewhat verbose (over 500 words). However, it is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Every sentence adds value, but could be slightly more concise.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response shapes, safety checks), the description is exceptionally complete. It covers all aspects an agent needs: how to use it, what to expect, edge cases, and caveats. No output schema exists, so the description must (and does) explain return values thoroughly.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains the flexibility of the 'market' parameter (slug, URL, or question text), clarifies depth enum (quick vs thorough), and details the include_raw parameter's effect on response size. Examples illustrate 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). The usage guidance ('Use for...') further clarifies the intended scenarios.

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

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

The description provides explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes detailed safety checks (low-confidence resolution, closed markets, wide spreads, resolution-rule risk) and instructs the agent to inspect certain fields before trusting results.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and 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?

The description is concise yet comprehensive. It front-loads the purpose with common query patterns, uses bullet-like structure for clarity, and every sentence adds relevant information without redundancy.

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

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

Given no output schema, the description adequately explains the return format (paired data with citation URIs) and behavior (sorting). All essential aspects are covered, making the tool's usage and results predictable.

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

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

Schema coverage is 100%, but description provides rich additional meaning: for type='company' it details the financial metrics pulled (10-K revenue, net income, etc.), and for type='drug' it lists adverse-event counts, FDA approvals, and trial counts. It also explains that results are sorted by the primary metric, adding value beyond the schema.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly defines the resource (2-5 companies or drugs). It provides example queries and differentiates from sequential single-pack lookups, establishing a distinct purpose.

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

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

The description explicitly states to prefer this tool over sequential lookups when comparing entities. It gives strong usage guidance ('ALWAYS PREFER') but does not mention scenarios where the tool should not be used, which would make it a 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?

Discloses behavior beyond annotations (readOnlyHint, etc.) including decomposition, parallel execution, findings packet structure (gaps, contradictions, hop field), semantic excerpting, expected response times, and that it doesn't invent answers. 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?

Long but every sentence adds value; occasionally repetitive. Structure is front-loaded with critical account/tier info, then core functionality, then detailed constraints. Could be slightly more compressed but well-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?

Despite no output schema, description fully explains return format (findings packet with verbatim evidence, confidence, source, gaps array). Covers all essential aspects: prerequisites, multi-hop iteration, contradictions, and time expectations, making it self-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%, but the description adds significant meaning: explains the depth enum with detailed breakdown of each level (quick=3 facets, standard adds gap recovery, thorough adds iterative hop) and clarifies that the question parameter accepts broad/multi-part natural language.

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

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

The description clearly states it performs grounded multi-source research across 1318 structured data sources in one call, and distinguishes from siblings like ask_pipeworx for single lookups or breaking news. The verb 'research' and specific resource 'structured data sources' is 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 advises when to use this tool vs alternatives: 'For a single lookup use ask_pipeworx' and for breaking news prefer ask_pipeworx. Also mentions account tiers and prerequisites, providing comprehensive 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, idempotentHint, destructiveHint. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond annotations.

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

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

The description is concise, front-loaded with purpose, and uses efficient listing of domains. 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?

Given the tool's complexity (aliases, examples, behavior), the description fully covers what the tool does, what it returns, and how to use it. 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%, but description adds value by clarifying the query parameter's purpose with examples and listing aliases, exceeding the baseline of 3.

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

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

The description starts with a clear verb+resource: 'Find tools by describing the data or task.' It then lists many specific domains (SEC filings, FDA drugs, etc.), and distinguishes itself from sibling tools as a discovery tool to be called first.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' giving clear when-to-use and implied alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds valuable context: fans out across multiple sources, details return fields, notes patents API sunset (soft-fails), and explains that only 'company' type is supported. 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 somewhat long but each sentence adds necessary detail. It front-loads usage patterns and then explains outputs. Could be restructured for slightly easier scanning, 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 no output schema, description thoroughly explains what is returned (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers edge cases like patent sunset and name resolution requirement. Comprehensive 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 descriptions for both params. Description adds extra clarity: type is restricted to 'company' despite enum listing only that, and value accepts ticker or zero-padded CIK (not names). 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?

Description clearly states the tool produces a 'full cross-source profile of a US public company' in one call, distinguishes from chaining individual lookups, and provides example queries. It is specific and 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 prefer this tool over chaining single-pack lookups when a holistic view is needed. Also advises using resolve_entity first if only a name is provided, and specifies supported inputs (ticker or zero-padded CIK).

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

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

Annotations already mark destructiveHint=true and idempotentHint=true, confirming it's a destructive but idempotent operation. The description adds context about clearing sensitive data, which is helpful, but doesn't 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?

The description is extremely concise—only two sentences—yet packs in purpose, usage, and pairing advice. 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 a single parameter, clear annotations, and no output schema, the description is complete. It explains when to use and what the tool does, with 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?

The schema covers 100% of parameters with a single 'key' string. The description doesn't add meaning beyond the schema (e.g., no format or constraints). Baseline of 3 is appropriate since schema is sufficient.

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 'Delete a previously stored memory by key,' which is a specific verb+resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by being the delete operation, and explicitly pairs with them.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall,' guiding the agent on alternative tools.

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

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

Annotations already declare safe, idempotent, and open-world behavior. Description adds context: fetches page, extracts data, emits markdown. Aligns with annotations. Could mention potential network dependency but not required.

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, each with distinct role: purpose, mechanism, use cases. Front-loaded with primary function. 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?

With 2 simple parameters, no output schema, and complete annotations, the description fully explains what the tool does, how it works, and what to expect. Output format is clearly described. No gaps.

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

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

Schema covers 100% of parameters with descriptions. Description adds minimal extra meaning beyond schema, only contextualizing the purpose. Baseline 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?

Specific verb 'Generate' and resource 'llms.txt' with clear output format. Distinguishes from siblings like 'ai_visibility_check' by stating the exact file produced and use cases for clients, own projects, and competitor auditing.

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

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

Lists three explicit use cases (client indexing, drafting, auditing). Does not directly contrast with sibling tools but implies appropriate contexts. Could be improved by stating when not to use (e.g., if only checking visibility).

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 the tool is read-only, idempotent, and non-destructive. The description adds value by clarifying that rate values are strings with comma decimal separators and dates are in YYYY-MM-DD format. 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 concise and well-structured, front-loading the purpose and then systematically explaining the three modes and data format. Every sentence is informative and necessary.

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

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

Given no output schema, the description adequately explains the return data (srednji_tecaj, rate format) and covers all input scenarios. It is 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?

Schema coverage is 100%, and the description enriches parameter meanings by explaining the three modes, currency code format, and rate decimal representation. This adds context beyond the schema.

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

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

The description clearly states the tool provides exchange rates for a single foreign currency vs EUR, with three usage modes. However, it does not explicitly differentiate from the sibling tool 'hnb_exchange_rates', which might cause confusion.

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

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

The description explicitly explains when to use each of the three modes: omit dates for latest, use 'date' for single historical, and use 'start_date'+'end_date' for time series. It does not mention when not to use the tool or alternative tools.

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

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

Annotations already declare read-only and idempotent behavior. The description adds useful context: rates are against EUR, output rows with specific fields, and comma decimal separator for values.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Includes all critical information compactly.

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

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

With only one optional parameter and no output schema, the description fully covers the return fields, decimal format, and usage of date parameter. No gaps 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 has 100% coverage with description for the 'date' parameter. The tool description adds an example and the omission behavior, providing 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 returns HNB official exchange rates for all foreign currencies on a given date, specifies the base currency (EUR) and output fields. It implicitly differentiates from the sibling tool 'hnb_currency_rate' by stating 'ALL foreign currencies'.

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

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

Provides clear guidance on omitting date for latest rates and explains the eurozone context. However, does not explicitly state when not to use this tool or mention alternatives like hnb_currency_rate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by listing returned fields and mentioning optional parameter for inactive subscriptions, but doesn't 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?

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

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

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

For a simple list tool with one optional param and no output schema, description explicitly lists return fields, making it complete enough. Annotations cover behavioral aspects.

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

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

Schema coverage is 100%, so description adds little beyond schema. Schema already describes include_inactive. Baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions', specifying verb, resource, and scope. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel', which implies when not to use (i.e., for adding or canceling directly).

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description adds important behavioral context: rate-limited to 5 per identifier per day, free, not counted against tool-call quota, and that feedback influences the roadmap. 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 yet comprehensive, with every sentence adding value. It is front-loaded with the core purpose, followed by usage context, constraints, and tips. No fluff or redundancy.

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

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

Given the tool has 3 parameters (2 required), a nested object, and no output schema, the description fully covers what the agent needs: purpose, when to use, how to structure feedback, behavioral constraints, and parameter semantics. 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%, so baseline is 3. The description reinforces parameter usage by explaining the enum values and emphasizing specificity in the message. It adds value by contextualizing how to fill parameters (e.g., describe issue in terms of tools/packs), raising the score 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 the tool's purpose: to send feedback about bugs, missing features, data gaps, or praise. It specifies the target audience (Pipeworx team) and the scope (tools/packs), distinguishing it from sibling tools like ask_pipeworx or 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?

The description provides explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and advises against pasting user prompts. It also mentions rate limits and quota-free nature. However, it does not explicitly state when not to use this tool, leaving room for improvement.

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 valuable context: self-aggregating, no PII, cached 5min-1h. 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 purpose, then use cases, then details. No wasted words, well-structured with clear listing.

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?

Low complexity (1 param, no output schema). Description covers return items, data source, caching, and use cases. Could mention sorting or format, but adequate given 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 has 1 parameter with enum and description (100% coverage). Description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' Enhances schema meaning.

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 returns top tools, packs, and call volume over a window. Uses specific verb 'Returns' and resource description. Distinct from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment). Clear context but does not explicitly mention when not to use or contrast with 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 declare readOnlyHint, idempotentHint, openWorldHint as true, and destructiveHint false. The description adds valuable behavioral context: fill check warns of unrealizable edges, partition filter drops placeholder slugs, and semantic anchor prevents mismatched pairs. These details go beyond the annotations and inform safe usage.

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

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

The description is lengthy but well-structured with clear sections (modes, semantic anchor, partition filter, fill check). It is front-loaded with the main purpose and modes. While every sentence adds value, some details (e.g., fill check formula) could be slightly shortened 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 the tool's complexity (three modes, multiple checks, reference to another tool), the description covers the essential behavioral aspects and response structure. Although no output schema is provided, the description explains 'opportunities[]' and 'partition_check' fields adequately. It compensates for missing output schema with detailed prose, making it sufficiently complete for an agent.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant meaning: explains event slug format with examples, defines topic as a seed question, and clarifies optionality. It also describes how each parameter triggers different scanning modes, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three modes (no args, event, topic) and distinguishes each with concrete examples. This provides a specific verb+resource and differentiates from siblings.

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

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

The description explicitly guides when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also mentions an alternative tool 'polymarket_fill_risk' for custom sizing. However, it does not explicitly exclude use cases or compare to other sibling tools like polymarket_edges.

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, and destructiveHint. The description adds extensive behavioral context: details of three model families, edge metrics, diagnostics, caching at KV level keyed on knobs, and explanation of why Fed bets are excluded. 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 long but well-structured: it starts with purpose, then details model families, response structure, and parameter guidance. Every sentence adds value. It is not overly concise for a complex tool, but the organization is good.

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 is highly complete. It explains the response structure (by_segment, diagnostics), caching behavior, and edge cases like Fed bets. The agent can understand what the tool does and 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%, so baseline is 3. The description adds meaningful context beyond schema for several parameters, such as slippage_pp (explains Polymarket fees and bid/ask) and min_partition_leg_kelly (explains why it's needed). This justifies a higher score.

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

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

The description starts with a clear verb 'Scan top Polymarkets' and resource, and explicitly states it returns opportunities where Pipeworx data disagrees with market price. It also distinguishes itself from siblings like polymarket_arbitrage by focusing on 'what should I bet on today' and detailing three unique model families.

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 targets the use case 'what should I bet on today' and explains it avoids paging through hundreds of markets. It also provides guidance on tradeable-edge knobs and limits. However, it does not explicitly state when not to use this tool or contrast directly with 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?

The disclosure is extensive: it explains the data source (daily snapshots), output structure (tracked, expired, snapshot_dates), computed fields (trend, decay_pp_per_day), and limits (60-day TTL, no intraday). This far exceeds what annotations (readOnlyHint, idempotentHint, etc.) provide, adding significant value.

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

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

The description is well-structured: purpose first, then detailed response fields, then limitations. It is slightly verbose but front-loaded and free of fluff, earning a high mark for clarity and organization.

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 lack of output schema and the tool's moderate complexity, the description is highly complete. It thoroughly covers response schema, edge cases (gaps in snapshots), and limitations (no intraday data), leaving little ambiguity for invocation.

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

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

With 100% schema coverage, the description's parameter details (e.g., 'default 14, max 30' for days) add minimal value beyond the schema. It reinforces defaults and constraints but doesn't provide new semantic meaning.

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: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('answers') and resource ('edge persistence and decay'), and distinguishes itself from the sibling 'polymarket_edges' by focusing on historical trends rather than raw current 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?

The description provides strong contextual guidance by contrasting fresh vs. old edges and explaining the output fields. However, it does not explicitly state when not to use this tool or name direct alternatives, leaving some ambiguity for the agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral context: walks order-book ladder, returns verdict and risk analysis (thin_legs, forced_directional_risk), and warns about partial fill consequences. 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?

Dense but well-structured: purpose first, then mode details, then usage guidelines. Each sentence adds value. Could be slightly more scannable with bullets, but appropriate for complexity.

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

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

Despite no output schema, description comprehensively lists return fields (top_of_book, vwap, slippage, verdict, capture_ratio, profit_usd, etc.), edge cases (thin_legs, forced_directional_risk), and reasoning. Complete for a pre-trade risk check.

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 all 4 parameters (100% coverage). Description adds meaning: explains side auto-detection for basket mode, different interpretations of size_usd for buys vs sells and single vs basket, clamping range (10-1e6), and required relationship between market/event.

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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly distinguishes single-market from basket modes, naming specific outputs. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', with reasoning about non-capturable overround and directional risk from partial fills.

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 safe read-only behavior, but the description adds extensive detail: compatibility_warning scenarios, temporal_alignment, skipped cross-types, and the structure of spreads. This goes well beyond the annotations, providing 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 dense and well-structured with clear sections (purpose, modes, response, safety fields, caveats). Every sentence earns its place, though it is slightly long. Front-loaded with the core purpose.

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

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

Given the lack of output schema, the description comprehensively covers the response shape (leg-by-leg prices, spread array, safety fields) and temporal alignment. It provides all necessary context for an agent to interpret results 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%, and the description expands on each parameter by listing the 10 pre-mapped macros for 'topic' and explaining the override behavior for explicit tickers. Examples in schema are supplemented by the description's mode explanation.

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 a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue spreads rather than intra-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 modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics return compatibility warnings, advising against assuming tradeability. It provides context for when to use the tool but could more explicitly mention alternative tools for intra-venue spreads.

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 and non-destructive. Description adds scoping context and the behavior of listing keys when argument omitted, which is useful 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 sentences, each earning its place: core purpose, usage scenario, scoping and pairing. No redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately covers purpose, usage, and scoping. Could mention return format (value or list) but not essential.

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, description adds meaning by explaining the effect of omitting the key argument (list all keys), which is not explicit 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 uses specific verbs ('Retrieve', 'list') and resources ('value previously saved', 'saved keys'), clearly distinguishing from siblings '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 states when to use ('look up context the agent stored earlier') and scoping ('Scoped to your identifier'). Mentions pairing with 'remember' and 'forget', providing clear 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 declare readOnly, idempotent, non-destructive. Description adds that returned alerts can be marked as read (affecting future calls), mentions polling works fine, and provides an alternative access method. Adds meaningful behavioral context beyond annotations.

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

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

Four concise sentences front-loaded with purpose. Each sentence adds value: purpose, content details, filtering options, additional notes on polling and alternative access. 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 purpose, return content, filtering, state management (mark_read), and alternative access. Lacks explicit ordering/pagination details beyond limit parameter, but overall sufficient for a read-only 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 has 100% coverage with descriptions for all 5 parameters. Description adds a filtering example (sec_8k) and mentions mark_read, but does not substantially enhance understanding beyond 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 pulls fired events from subscription feed, returns recent alerts with specific fields (source, citation_uri, payload). Distinguishes from siblings like recent_changes and list_subscriptions by focusing on alerts with event payloads.

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?

Mentions polling and an alternative REST endpoint, but does not explicitly state when to use this tool versus siblings like list_subscriptions or recent_changes. Provides context for usage but lacks exclusion guidelines.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: it fans out to multiple sources in parallel, describes the fallback from GDELT to GNews, explains that USPTO soft-fails, and specifies the output structure (changes grouped by source, total_changes, citation URIs).

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 dense sentences that efficiently convey purpose, usage, behavior, parameters, and output. It is front-loaded with examples. While concise, it could be slightly more structured for readability, 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 lacking an output schema, the description explains the return format (structured changes, total_changes, citation URIs). It also mentions the soft-fail for USPTO. For a tool with three required parameters and complex multi-source behavior, the description is complete enough for an AI 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 descriptions for all three parameters. The description adds further context, such as acceptable formats for 'since' (ISO date or relative shorthand like '7d') and recommendation for typical monitoring ('30d' or '1m'), and explains that 'value' can be a ticker or CIK. This goes beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company, with multiple examples like 'What's new with X', and explicitly distinguishes from sibling 'entity_profile' by stating when to use that instead. It names specific data sources (SEC EDGAR, GDELT, GNews, USPTO) and 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 gives explicit examples of when to use the tool and contrasts it with 'entity_profile' for static data. However, it does not explicitly list when not to use it or other alternatives. The context provided is sufficient for an AI to decide, but full exclusion criteria are missing.

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 behavioral context beyond annotations: it discloses data is stored as key-value pairs, scoped by identifier, and explains persistence differences for authenticated vs anonymous sessions (24 hours). Annotations already indicate idempotent=true, which is consistent. No contradictions.

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

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

The description is concise (5 sentences) with the main purpose front-loaded in the first sentence. Every sentence adds meaningful information without redundancy.

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

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

Despite no output schema, the description fully covers what the tool does: storage mechanism, scoping, retention policy, and pairing with recall/forget. It is complete for a simple key-value store 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 clear parameter descriptions. The description adds value by providing naming conventions ('subject_property', 'target_ticker') and clarifying that value is arbitrary text.

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 purpose: 'Save data the agent will need to reuse later' and provides concrete examples like resolved ticker, target address, etc. It distinguishes from sibling tools (recall, forget) by specifying pairing actions.

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

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

The description tells when to use: 'when you discover something worth carrying forward' and mentions pairing with recall and forget. It provides context on session scope and persistence but does not explicitly state when not to use other than implicitly via pairing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups', which enriches transparency beyond the annotations.

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

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

The description is well-structured with two focused paragraphs: first on purpose and usage, second on supported types. It is front-loaded with examples and avoids unnecessary fluff. Could trim some repetition (e.g., 'from SEC EDGAR' could be merged), but overall concise and scannable.

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

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

Given no output schema, the description fully compensates by detailing return values for each type (ticker+CIK+company_name+URI for company; RxCUI+ingredient+brand+URI for drug). It also addresses edge cases like auto-disambiguation and accepts multiple input formats, providing a complete picture for tool invocation.

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

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

Schema coverage is 100% (both parameters documented). The description adds examples and clarifications for each type (e.g., for company: ticker, CIK, or name; for drug: brand or generic name), which provides meaningful context beyond the schema's concise 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 uses specific verbs ('resolve', 'look up') and resources ('name to identifier') with clear examples ('ticker', 'CIK', 'RxCUI'). It distinguishes from sibling tools like compare_entities that likely use these identifiers, making the tool's unique purpose evident.

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 FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. However, it does not explicitly mention when not to use or name alternative tools for related tasks, though the sibling list and context imply 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?

The description adds significant behavioral context beyond the annotations. It explains that the tool probes each entity with 'ai_visibility_check', ranks results, and returns a ranked list with score, confidence, and signal density. It also notes that the first entity is treated as the 'subject.' Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description does not contradict them.

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

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

The description is three sentences, each carrying crucial information: purpose, method (probing and ranking), and use case with return details. It is front-loaded, concise, and contains no filler.

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

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

Despite having no output schema, the description adequately explains the return format ('ranked list with score, confidence, signal density per entity'). It covers the tool's behavior comprehensively given its complexity. Annotations confirm safe usage, so no further behavioral disclosure is needed.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds value by explaining the 'entities' parameter in detail (2-8 entities, first treated as subject), the 'models' parameter (supported models, default, API key requirement), and the 'context' parameter (shared context to disambiguate). This goes 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 the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It differentiates from the sibling tool 'ai_visibility_check' by mentioning it probes each entity with that function and ranks them, and from 'compare_entities' by being specialized for AI visibility audits.

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: 'Useful for competitive AI-marketing audits' with a concrete example ('does Claude know about us as well as our competitors?'). It implies that for single-entity checks one should use 'ai_visibility_check' (since it mentions probing each entity with that tool). It does not explicitly list alternatives or when not to use, but the context is clear enough.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: composite fan-out, partial failure graceful degradation, bundlephobia first-measurement delay (5-30s), and listing of sources_failed. 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?

Well-structured with main purpose upfront, then details. Slightly verbose but each sentence contributes meaning. Could be tightened without losing info, 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 no output schema, the description details return structure: summary block with listed fields, per-advisory details, links, and alternative versions. Covers edge cases like partial failures and timing. Fully contextual for an agent to invoke and interpret results.

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 describes both parameters with full coverage. The description adds value: clarifies 'package' accepts scoped names, explains 'version' defaults to latest. This extra context justifies a 4 rather than a baseline 3.

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

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

The description clearly defines the tool as a composite check for npm package suitability, using specific verb 'scan' and resource 'npm package'. It distinguishes from siblings by specifying it's a one-call combination of deps.dev and bundlephobia, which no other sibling tool offers.

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 an agent asks about safety, popularity, size, or cost of a package. Also provides when-not-use info: only NPM ecosystem in v1, and points to deps.dev:version directly for other ecosystems.

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. The description adds significant behavioral details: uses BGE-base-en embeddings, cosine on 500-char windows, 200K char cap with truncation and flagging. No contradictions.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value: purpose, usage scenario, pairing, technical details. 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?

Despite no output schema, the description specifies that outputs include top-N passages with offsets and similarity scores. It also explains pairing and truncation cap, making it complete for a 3-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for the query parameter (e.g., 'supply-chain risk'), aiding 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 the tool does semantic search inside a fetched record, using specific verbs and resources. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining it works on already fetched text and returns passages with offsets.

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

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

The description explicitly says to use when the record is too large for the prompt, saving context. It suggests pairing with ask_pipeworx_grounded for grounding, providing clear context and an alternative, though it does not explicitly state when not to use 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?

The description adds significant behavioral context beyond annotations: auth requirements, rate limits (10 SMS/day), webhook auto-disable after 10 failures, and the one-time return of a signing secret. These details align with annotations (not readOnly, not destructive, idempotent) and provide actionable constraints for the agent.

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

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

The description is well-structured, starting with the main action, then requirements, type examples, and delivery options. Every sentence adds value, though it is somewhat dense. It could be slightly more concise but remains efficient.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types), the description covers auth, types, delivery, constraints, and return value (subscription id). It does not explain how to use the id later, but sibling tools likely cover that. The lack of output schema is compensated by stating the return value explicitly.

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 already provides full coverage of parameter descriptions. The description enriches this with real-world examples for each subscription type, specific constraints (e.g., phone verification, webhook URL restrictions), and delivery channel behaviors. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It uses a specific verb ('Create') and resource ('subscription'), distinguishing it from sibling tools like list_subscriptions (list) and unsubscribe (delete).

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

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

The description specifies that a Pipeworx OAuth account is required and lists supported subscription types with examples. It does not explicitly contrast with alternatives like list_subscriptions or recent_alerts, but the context is sufficient for a capable agent to decide when to use this tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns a structured set of example questions with exact tool and argument shapes, drawn from a live catalog of thousands of tools. This goes beyond annotations by describing the return format and the scope of the tool's output.

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 efficient. It front-loads common user questions as aliases, then states the purpose and return structure. Every sentence adds value. Minor redundancy (e.g., both 'what can I ask' and 'what is Pipeworx good for') but overall well-organized.

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

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

Given the tool's role as an onboarding entry point, the description fully explains what it returns (category-bucketed example questions with tool calls), when to use it (first interaction), and how to narrow by topic. Annotations cover safety, and schema covers the parameter. No output schema exists, but the description adequately describes the return structure.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by providing examples of valid topic values ('finance', 'pharma', 'betting') and explaining that omitting it gives a cross-category spread. This adds semantic context beyond the schema's enum 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?

Description clearly states it is the onboarding entry point for suggesting questions about Pipeworx. It lists numerous aliases ('what can I ask', 'give me ideas') and explains what it does (returns category-bucketed example questions). It distinguishes itself from siblings like 'ask_pipeworx' which answers questions, and explicitly tells the agent to use this first when unsure.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic argument to focus the results. While it doesn't list when not to use it, the context is clear that it's for onboarding and exploration.

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?

Goes beyond annotations by explaining ownership enforcement, deactivation (not deletion), and linkage to recent_alerts. Annotations already indicate idempotent and non-destructive, but description adds operational details.

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 focused sentences with no redundant information. Action and key constraints 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?

Complete for a simple tool: explains ownership, side effects, and relation to other tools. No output schema needed; description covers all necessary context.

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

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

Only one parameter 'id', fully described in schema. Description adds no extra meaning, but schema coverage is 100%, meeting 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?

Specific verb 'Cancel' with clear resource 'subscription by id'. Distinguishes from sibling 'subscribe' and 'list_subscriptions'. Mentions ownership enforcement and deactivation.

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

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

States ownership constraint, implying only the subscription owner should use it. Lacks explicit when-not-to-use or alternatives, but context is clear enough for proper selection.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context about the two processing paths, return values, and the tolerance parameter, extending 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 well-structured with trigger phrases upfront, followed by detailed processing explanation and return values. Each sentence contributes value, though slightly verbose.

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

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

Given no output schema, the description adequately explains the verdict types, citation format, and reasoning. It covers the tool's complexity and typical use cases but lacks error handling or limitation 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% with descriptions for both parameters. The description adds meaning for tolerance_pct (override and default behavior) and explains the nature of the claim parameter.

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 fact-checking of natural-language claims against authoritative sources, with specific trigger phrases and two processing paths. However, it does not explicitly differentiate from sibling tools like ask_pipeworx_grounded which may also handle factual queries.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' No exclusion criteria or mention of alternative tools, but the context is clear.

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