Prozorro

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

Annotations already state readOnly, openWorld, idempotent, and non-destructive. The description adds that it is free for workers-ai and requires BYO key for Anthropic, and outlines the return structure partly. No contradictions, but could mention rate limits or error handling.

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

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

Three sentences front-loaded with purpose, then options, then use cases. No wasted words. Highly efficient and well-structured.

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

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

Given no output schema, the description partially covers return structure (score, confidence, signals, raw_response). It explains parameters and usage well. Could mention error cases or missing output details, but overall sufficiently complete.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds value by explaining the default model, that _apiKey is optional only if probing Anthropic, and that context helps disambiguate. This guidance is helpful beyond schema.

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

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

The description clearly states the tool probes LLMs for entity visibility and scores it 0-100. It specifies the verb ('probe'), resource ('LLMs'), and outcome ('score visibility'). This distinguishes it from sibling tools like 'ask_pipeworx' or 'deep_research' which serve different purposes.

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

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

The description explains when to use the tool (AI-marketing audits, brand checks, competitive monitoring) and notes the default model with optional Anthropic probing. It does not explicitly exclude use cases or name alternatives, but the context is clear for an 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 indicate readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds valuable context about internal routing across 4,774 tools, returning structured answers with stable citation URIs, and working on every tier. 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 lengthy but each sentence adds value. It is well-structured, starting with a strong preference statement, followed by explanation, examples, and guidance on alternatives. Could be slightly more concise, but content justifies length.

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

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

For a complex tool with no output schema, the description sufficiently explains the return type (structured answer with citations), covers when to use it, provides examples, and addresses alternatives. It is complete for an AI agent to select and invoke.

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 all parameters clearly documented and aliases listed. The description provides example questions but does not add additional parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes questions to a vast array of authoritative sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly advises to prefer this tool over web search for factual questions, marks it as the default entry point, and provides clear transition guidance to alternatives (ask_pipeworx_grounded, deep_research). Includes example queries to illustrate appropriate usage.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses the process (routing, extraction from tool result), return format with fields and refusal reasons, and cost (one extra LLM call). 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 dense but well-structured: opening defines purpose, follows with process, then usage guidelines, then cost trade-off. Every sentence adds value without redundancy. Front-loaded key concept.

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 (routing across 4,774 tools, extraction, refusal reasons), the description fully covers what the agent needs: return format, failure modes, when to use, cost implications. No output schema exists, so description carries the burden and does so 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% (6 parameters all documented with descriptions). The description adds that the question is in natural language and mentions aliases, but schema already covers aliases. 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?

The description clearly states the tool's purpose as 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from ask_pipeworx by explaining the extra LLM call and refusal mechanism. The verb 'extracts' and resource 'answer' are specific, and it differentiates from sibling tool ask_pipeworx by mentioning cost and use case.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' Lists concrete domains (financial verdicts, legal claims, medical lookups, public statements) and provides a clear when-not-to-use rule.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral details: resolver contract (match confidence, alternatives), parent event extractor, news fallback, safety (low-confidence short-circuit, closed/dead markets, wide spreads), and cancellation rule risk. This goes far 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 long but densely packed with essential information. It is front-loaded with the main purpose and then details classifiers, fan-out examples, response shapes, resolver contract, etc. Every sentence earns its place given the tool's complexity, though it could benefit from more structured sections.

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 (many classifiers, fan-outs, response fields, safety mechanisms), the description is exceptionally thorough. No output schema exists, but the description extensively covers return values (market, analysis, evidence, resolver contract, parent event, news fields). The agent receives 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?

Schema coverage is 100% (3 parameters, all described). The description adds meaning: market param accepts slug, URL, or question text; depth param explains quick vs thorough; include_raw clarifies response size impact. This adds helpful 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 researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). It distinguishes from siblings like ask_pipeworx and polymarket_edges by focusing on bet-specific research with classification and fan-out.

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

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

Explicit use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. The depth parameter (quick/thorough) guides when to use. No explicit 'when not to use', but the clarity of use cases compensates. No direct alternatives mentioned, but sibling tools provide context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of fiscal years, sorting by primary metric, and output format (paired data + citation URIs). No contradictions.

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

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

The description is front-loaded with common examples and uses concise statements. It is slightly dense but well-organized. Every sentence adds value, though it could be trimmed slightly for brevity.

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

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

Given no output schema, the description explains the return format (paired data + citation URIs). It covers all necessary context: what each type returns, number of entities, sorting, and data freshness. Complete for a tool with simple parameters.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds context beyond the schema: what data each type retrieves, examples of values, and that results are sorted. While helpful, the schema already provides clear meaning, so a slight deduction applies.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It includes trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger') and distinguishes itself from sequential single-entity lookups, aligning with sibling tools like entity_profile.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also specifies the allowed types (company/drug) and the number of entities (2-5). No alternative tools are mentioned, but the context is clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: it runs in parallel, returns findings with citations and gaps, and warns that it returns empty gaps for unstructured news. It also notes expected duration (15-60s) and account requirements.

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

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

The description is front-loaded with critical account info, well-structured, but slightly verbose. Every sentence adds value, and it is organized logically from requirements to usage to alternatives.

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

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

Despite no output schema, the description fully covers input, behavior, output format (findings packet with gaps), usage context, caveats, and time expectations. It is comprehensive for a tool with only two parameters.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces that the question can be broad and multi-part, adding value beyond the schema. However, it does not provide additional details on format or constraints.

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

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

The description clearly states the tool performs multi-source research across structured data sources, distinguishing it from siblings like ask_pipeworx. It uses specific verbs and resources ('grounded multi-source research', 'decomposes your question into focused facets').

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 tells when to use this tool vs alternatives: for a single lookup use ask_pipeworx, for breaking news prefer ask_pipeworx, and if not signed in use ask_pipeworx instead. It also clarifies that this tool is not for open-web search.

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 a safe, idempotent operation. The description adds valuable detail: returns top-N tools with full schemas and curated examples, ready to call directly. 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 the core purpose. Each sentence adds essential information without waste. The list of domains is compact yet informative.

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

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

Although there is no output schema, the description fully explains what is returned (top-N tools with names, descriptions, schemas, examples) and that results are directly callable. This is sufficient for the agent to understand and use the tool effectively.

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 modest value by confirming that 'task', 'q', 'description', and 'search' are aliases for 'query', which is already in the schema but usefully consolidated.

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 'Find tools by describing the data or task' and lists numerous domains, making the purpose specific and distinguishing it from sibling tools which are domain-specific.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. It does not explicitly state when not to use, but the context is strong.

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

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

Description explains the parallel fan-out across multiple sources, soft-fail for patents (USPTO sunset), and return data structure. Annotations already mark it as read-only and idempotent, and description adds 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?

Single dense paragraph is front-loaded with natural language examples. It packs a lot of information efficiently but could benefit from slight structuring (e.g., bullet points for return fields).

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 covers return fields and sources well. However, it could explicitly state that only US public companies are supported (implied by SEC). Still quite complete.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by explaining that value can be ticker or CIK (format examples) and that names are not accepted. Adds context beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes from sibling tools like resolve_entity (names) and 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups' and provides natural language triggers. It also tells when not to use: names not supported, use resolve_entity first.

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

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

Annotations already indicate destructive and idempotent nature. Description adds 'Delete' but does not elaborate on idempotency (e.g., safe to delete nonexistent key) or return behavior, so minimal added value beyond annotations.

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

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

Two sentences, no redundant information, essential details front-loaded.

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

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

For a simple tool with one required parameter, no output schema, and comprehensive annotations, the description sufficiently covers all needed information.

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

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

Single parameter 'key' with description 'Memory key to delete' mirrors the schema. Schema coverage is 100%, so description adds no extra 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 'Delete a previously stored memory by key.' Action and resource are specific, and it distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with related tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and 'Output is a single text blob ready to drop at site-root/llms.txt.' This adds context beyond the annotations.

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

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

The description is concise with two clear sentences followed by bullet points of use cases. It is front-loaded with the core purpose. Minor redundancy (e.g., 'production-ready' and 'standard' could be simplified), but overall well-structured.

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

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

Given no output schema, the description adequately explains the output format and purpose. It covers context for AI crawlers and the output location. Parameter details are complete from schema. The tool is simple, and the description provides 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?

Schema coverage is 100%, so both parameters (url, max_links) are already well-documented. The description does not add significant new semantic information about the parameters beyond their schema definitions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb ('Generate') and resource ('llms.txt file'), and distinguishes itself from all sibling tools by its unique function.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It lacks explicit when-not-to-use or alternative tools, but given the uniqueness of the tool, the guidance is still effective.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. Description adds behavioral context about returned fields and parameter 'include_inactive', which goes beyond annotations without contradicting them.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. Every sentence adds value with no waste.

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

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

Given the tool has no output schema, description adequately explains return fields. It covers all needed context for a simple list tool with one optional parameter.

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

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

Schema coverage is 100% (parameter 'include_inactive' has description). Description does not add additional meaning beyond the schema; the 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?

Description clearly states 'List the caller's active subscriptions' with specific verb 'list' and resource 'subscriptions'. It enumerates return fields and distinguishes from sibling tools subscribe/unsubscribe by mentioning 'review what you're monitoring' and 'find an id to cancel'.

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

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

Description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. It implicitly suggests when not to use (not for creating or deleting subscriptions, which are covered by siblings subscribe and unsubscribe).

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

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

Annotations provide limited info (readOnlyHint=false, destructiveHint=false). Description adds key behavioral traits: rate-limiting (5 per identifier per day), non-quota impact, and that submissions affect roadmap. 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?

Five sentences, no wasted words. Front-loaded with purpose, then usage, then constraints. Perfectly sized for the tool's simplicity.

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 params, no output schema, and nested objects, the description is complete: it explains all feedback types, required context, rate limits, and what not to do. Nothing essential is missing.

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 detailed descriptions for all 3 parameters. The description restates the enum categories but adds usage context (e.g., 'bug = something broke'). Baseline 3 is appropriate; minor added value.

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

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

The description clearly states the tool's purpose: collecting feedback (bug, feature, data gap, praise) for Pipeworx. It distinguishes itself from sibling tools, which are all for querying or acting on data, not for submitting feedback.

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

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

Explicitly describes when to use each feedback type (bug, feature, etc.), what to include (tool/pack context, not user prompt), and constraints (rate-limited to 5/day, free, doesn't count against quota). No other tool provides this feedback channel.

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 behavioral details: data source (CF analytics-engine), privacy (no PII), caching strategy (5min-1h), and self-aggregating nature—beyond what annotations provide.

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

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

The description is concise with minimal waste. The first sentence delivers the core purpose, followed by bullet-like usage tips and a note on privacy/caching. Could be slightly more succinct but strikes a good balance between clarity and completeness.

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 covers purpose, usage context, behavioral traits, and parameter nuance thoroughly. No gaps remain for an AI agent to select or invoke correctly.

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

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

Schema coverage is 100% with a single parameter 'window' and enum description. The description adds meaning by explaining that shorter windows surface hot trends and longer windows show steady-state demand, providing practical 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 it returns 'top tools, top packs, and total call volume' over a window, with a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx right now'). It distinguishes from siblings by focusing on trending signals rather than search or entity profiles.

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

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

The description explicitly enumerates three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It does not contrast with sibling tools directly but provides clear contextual triggers for 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?

Description adds extensive behavioral context beyond annotations: explains algorithms (monotonicity violations, partition-sum checks), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check with book depth, and response structure. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint all consistent).

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 lengthy but well-structured with clear separation of modes, semantic anchor, partition filter, and fill check. It is front-loaded with core purpose and uses paragraphs effectively. Could be slightly more concise, but every sentence adds value.

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

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

Despite no output schema, the description thoroughly documents the return structure (opportunities[] with fields, partition_check object in event mode, fill check details). It also covers edge cases (low similarity, placeholder fractions, book depth check) and references sibling tools for further needs.

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

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

Input schema has 100% description coverage with clear descriptions for both parameters. The description adds extra value by providing examples of event slugs and topic seeds, and clarifying the behavior difference between single-event and cross-event modes.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) with specific examples, making its purpose precise and differentiating it from siblings like polymarket_edges.

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

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

Explicitly states when to call with no args for a trending scan, to pass `event` for a specific market, or `topic` for cross-event scanning. Recommends `event` for specific markets and provides guidance on when not to trade (realizable_edge_pp ≤ 0). Also references sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: it describes the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with technical specifics, explains that Fed bets are excluded from ranking due to signal unreliability, and mentions caching behavior ('Cached 1h at the KV level keyed on all knobs'). 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 verbose (~300 words) but well-structured: it front-loads the purpose, breaks down into segments, then covers response fields and knobs. While some technical detail (e.g., specific alpha values per sport) could be pruned, the structure is logical and each section earns its place by adding necessary context for an AI agent.

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 compensates by detailing the response structure: top-level by_segment with three segments, _diagnostics with funnel counters, and caching info. With 9 parameters, it explains all capabilities, including the Fed bet exclusion and segment-specific filters. The description is thorough enough for an agent to use the tool effectively.

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 grouping parameters into 'Tradeable-Edge knobs' and providing usage hints (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model' for slippage_pp). It also explains the interplay between parameters like min_kelly and min_partition_leg_kelly. This exceeds basic 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return), resource (Polymarket markets), and outcome (opportunities). The title 'Polymarket Edges' and sibling tools like polymarket_arbitrage and polymarket_edge_tracker indicate differentiation, and the description reinforces this by focusing on model-disagreement 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 explicitly states it's built for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. While it doesn't explicitly list when to use alternatives, the context is clear. The 'Tradeable-Edge knobs' parameter section gives usage hints for filtering, implying when to adjust thresholds.

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

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

The description provides extensive behavioral disclosure beyond the annotations. It details the data structures returned (tracked, expired, snapshot_dates), how trend and decay are computed, and limitations (history depth, snapshot TTL, daily closes). Annotations already indicate read-only and idempotent, and the description adds 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 relatively long but efficiently packed with essential information. It front-loads the key question and provides structured output details. A minor improvement could be tightening some phrasing.

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

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

The description fully explains the tool's purpose, input parameters, output structure (tracked, expired, snapshot_dates), and limitations. Since there is no output schema, this burden is well met. It is complete for a tool of this complexity.

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

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

Schema coverage is 100% as both parameters are described in the input schema. The description adds minor context (default values, clamp range) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry from daily snapshots. It answers the specific question about how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges, which likely provide current edge data, not historical trends.

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

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

The description explains when to use it: for understanding edge duration and decay. It does not explicitly state when not to use it, but the context implies it is for historical analysis rather than real-time edge detection. The LIMITS section provides practical guidance on data availability.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing behavioral traits: walking the ladder, returning fill quality metrics (slippage, shares_filled), and warning about forced directional risk and thin legs. 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 long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It is front-loaded with the core purpose. While comprehensive, it could be slightly more concise; however, every sentence adds necessary value for such a complex tool.

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 thoroughly enumerates returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains key concepts like forced_directional_risk and max_clean_notional_usd. It leaves no major gaps given the tool's complexity.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning: it explains the dual-mode usage of 'market' vs 'event', the side parameter defaults and auto behavior in basket mode, and the nuanced interpretation of size_usd (spend vs target proceeds vs settlement notional). This goes well beyond the schema descriptions.

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

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

The description clearly states it is a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It also explicitly positions itself as a pre-trade risk check for sibling tools like polymarket_arbitrage and polymarket_edges, providing clear differentiation.

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

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

The description provides explicit guidance on when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale, such as theoretical overround not being capturable on thin books and the danger of partial basket fills. This is thorough and actionable.

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

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

The description goes far beyond annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/counters) and explaining scenarios where spreads are meaningless (bet shape mismatch, temporal misalignment). It also sets user expectations that 'pre-mapped ≠ tradeable'.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. It is slightly verbose in explaining safety fields but every sentence adds necessary context for correct tool usage.

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 absence of an output schema, the description fully explains all response components (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). It covers edge cases and provides enough detail for an agent to decide when spreads are meaningful and what warnings mean.

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 description coverage, the baseline is 3. The description adds value by explaining the two-mode logic, listing topic shortcut values, and clarifying that explicit tickers override topic-based mapping. This interaction detail is useful beyond the schema properties.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two input modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like `polymarket_edges` and `polymarket_arbitrage` by focusing on cross-venue comparison.

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

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

The description explains when to use each mode (topic shortcuts for common macro events, explicit tickers for custom pairings) and warns that most pre-mapped topics return compatibility_warning, meaning not all shortcuts yield tradeable spreads. It lacks explicit comparison to alternatives but provides strong contextual guidance on limitations.

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, so the description does not need to repeat safety. It adds valuable behavioral context: the API is 'keyless public', text is 'largely Ukrainian', and it lists the return fields. 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: 2-3 sentences with front-loaded purpose. Every sentence adds value (purpose, return fields, input format). 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 get-by-id tool with one parameter and no output schema, the description fully covers purpose, input, return fields, language, and usage context. It is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, but the description adds significant meaning: it specifies the format (32-hex) and explicitly distinguishes from the human-readable tenderID. This goes beyond the schema description.

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

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

The description clearly states 'Full detail for a single Ukraine ProZorro tender by id', specifying the verb (get detail), resource (tender), and scope (single by id). It distinguishes from sibling tools by mentioning it accepts the 32-char tender id from prozorro_recent_tenders / prozorro_search_tenders, differentiating it from list/search tools.

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

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

The description explicitly states it accepts the 32-char tender id from prozorro_recent_tenders / prozorro_search_tenders, giving clear context on when to use this tool (after listing/searching). It implies the input format and that it is not for human-readable tenderIDs, but does not explicitly mention when not to use alternatives, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as safe. Description adds value by stating the data comes from 'keyless OpenProcurement public feed' (no auth required) and lists output fields. No contradictions with annotations.

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

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

Three efficient sentences: source and scope, returned fields, usage guidance. No redundant words. Front-loaded with the most important information (recent tenders from ProZorro).

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 full annotations (readOnly, idempotent), complete schema coverage for the single optional parameter, and description listing all output fields (since no output schema), an agent has all necessary information to decide and 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?

The only parameter 'limit' is fully documented in the schema (default 20, range 1-50) with 100% coverage. Description does not add additional semantics beyond what schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool returns 'most recently updated tenders' from ProZorro, lists specific fields returned (id, tenderID, title, etc.), and explicitly distinguishes from sibling prozorro_get_tender by specifying use case. This provides a specific verb (returns) and resource (recent tenders) with clear differentiation.

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

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

Description explicitly says 'Use for browsing current Ukrainian public tenders; for a specific tender use prozorro_get_tender.' This gives clear when-to-use and an alternative. It does not mention prozorro_search_tenders sibling, but the context is sufficient for the main use case.

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, idempotentHint, and destructiveHint. The description adds value by explaining 'Best-effort' nature, scanning limited recent feed, and the technical limitation of unreachable ProZorro front-end API. It does not contradict annotations; it provides context beyond the annotations' structural hints.

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

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

The description is two paragraphs: first sentence states purpose clearly, second expands with caveats and alternatives. It is concise without redundancy, though could be slightly more structured with bullet points for readability. 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 no output schema, the description lists returned fields (id, tenderID, title, value, buyer, status) and explains limitations and alternatives. It covers the essential context for using the tool effectively, though it could mention pagination or result limits for completeness.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by stating 'Ukrainian recommended (e.g. "комп'ютер", "школа")', 'matches by substring', and explains 'scan' as depth from 1-200, adding practical usage context beyond the schema alone.

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

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

The description clearly states it performs 'Keyword search over recent Ukraine ProZorro tenders', specifying the verb 'search', resource 'recent tenders', and context 'Ukraine ProZorro'. It distinguishes from siblings by noting it filters the recent feed and is not a full-text index of all history, avoiding confusion with prozorro_get_tender or prozorro_recent_tenders.

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 'Best-effort: scans the recent public feed' and advises 'not a full-text index of all history — ProZorro's front-end search API is not reachable from datacenter egress'. It recommends using prozorro_get_tender for older/exact tenders and suggests using Ukrainian keywords for best recall, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that omitting the key lists all saved keys and that the tool is scoped to the agent's identifier, providing valuable 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 three sentences long and front-loaded with the primary action. Each sentence provides distinct value: action, use case, and scope. No unnecessary words.

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

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

Given the simplicity of one optional parameter and no output schema, the description covers the core behavior adequately. It could mention what happens if a key doesn't exist, but overall it is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reiterates the list behavior when omitted but adds no new syntax or formatting details. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if omitted. It distinguishes from sibling tools 'remember' (save) and 'forget' (delete) by specifying the retrieval action.

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 the tool: to look up previously stored context without re-deriving it. It does not explicitly state when not to use it, but the context and sibling pairing imply appropriate usage.

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

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

Description contradicts annotations: describes 'mark_read:true' which modifies read status, but annotations include readOnlyHint=true. This is a direct contradiction, requiring score 1.

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

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

Very concise: 5 sentences, front-loaded with purpose, then parameter details, then 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 return fields, filtering, mutating behavior (mark_read), and alternative API. However, contradiction with annotations undermines completeness slightly. Output details are adequate for a list 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?

Adds example values (e.g., 'sec_8k'), explains effect of mark_read on subsequent calls, and clarifies 'since' as ISO timestamp. Adds meaning beyond schema, but not exhaustive.

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, specifies returned fields (source, citation_uri, raw payload). Verb and resource are explicit, but does not explicitly differentiate from sibling tools like 'recent_changes' or 'list_subscriptions'.

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

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

Provides context for polling and alternative access (direct URL for scripts/dashboards). Implies usage for agentic feed queries, but no explicit when-not-to-use or comparison with 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds useful context (fans out to multiple sources, GDELT→GNews fallback, USPTO soft-fail) without contradiction.

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

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

Description is front-loaded with purpose and examples, then covers sources and parameter details. Each sentence adds value, though slightly longer than necessary but still well-structured.

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

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

Despite no output schema, description explains return structure (changes[] grouped by source, total_changes count, citation URIs). Given tool complexity and rich annotations/context, it is complete enough.

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 extra guidance: shows accepted formats for 'since' with examples, explains 'value' can be ticker or CIK, and notes 'type' is limited to company. Adds significant value beyond schema.

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

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

The description explicitly states the tool aggregates recent changes from SEC, GDELT/GNews, and USPTO for a company, with specific examples of use cases. It clearly differentiates from the sibling tool entity_profile.

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

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

Provides explicit 'when to use' with example phrases, explains fallback behavior, and tells when to use entity_profile instead. This is 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?

Description adds contextual details beyond annotations: stored as key-value scoped by identifier, persistence for authenticated vs anonymous sessions. Annotations already indicate mutation (readOnlyHint false) and idempotency (idempotentHint true), so description complements without contradiction.

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

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

Four sentences with no wasted words. Front-loaded with purpose, followed by usage, then technical details. Highly efficient.

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

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

Given simple schema (2 strings, no output schema), description fully covers usage, scope, and pairing. Could optionally mention storage limits, but not necessary for correctness.

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% with clear descriptions for key and value. Description reinforces key-value nature with examples, but does not add significant new meaning beyond schema.

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

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

Description uses specific verb 'Save' and resource 'data' with clear intent 'to reuse later'. Distinguishes from sibling tools recall and forget by explicitly pairing with them.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides pairing instructions with recall and forget. Also covers scope and persistence details.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by revealing internal cascading through multiple endpoints, reducing manual lookups, and detailing specific return data for each type.

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, front-loaded with example queries and primary use, then details types. Every sentence contributes value.

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

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

The tool's complexity (entity resolution with multiple types) is fully covered by description, annotations, and schema. No output schema exists, but description explains returns. The description is complete for an agent to use effectively.

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, baseline is 3. Description greatly enhances parameter understanding by providing examples (e.g., ticker, CIK, name for company; brand or generic for drug) and explaining the return values per type.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers. It distinguishes from siblings by noting it replaces 2-3 manual lookups and should be used first when needing an ID. The verb 'resolve' and resource 'entity' are specific.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example queries. However, it does not explicitly state when not to use it or mention alternative sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that each entity is probed with ai_visibility_check, results are ranked, and returns score, confidence, signal density per entity. 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?

Description is concise: three sentences front-loaded with main purpose and value, no unnecessary words.

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

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

For a multi-entity comparison tool with 4 parameters and no output schema, the description explains the return format (ranked list with score, confidence, signal density) and covers key usage aspects. Missing details like pagination or error handling, but sufficient for selection.

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

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

Schema coverage is 100%, so baseline is 3. Description adds narrative context (e.g., 'B2B SaaS' for context param, first entity as subject) but does not significantly extend schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and highlights most/least recognized. This differentiates it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides a specific use case ('competitive AI-marketing audits') and an example question. Notes that the first entity is treated as the subject. Does not explicitly state when not to use or list alternatives, but context is clear.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive) are supported by description which adds behavioral details: fans out across services, bundlephobia first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timeouts. 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?

Single well-structured paragraph front-loads the purpose, then details services, return format, and edge cases. Every sentence contributes meaning 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 (composite check, multiple services, partial failures, no output schema), the description fully covers what happens, what it returns (summary block, advisories, links, alternatives), and limitations (NPM only, bundlephobia delay).

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages are accepted and that version defaults to latest, which goes beyond 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: a composite check for npm packages covering safety, popularity, and size. It specifies the resources (deps.dev and bundlephobia) and distinguishes from siblings by focusing on npm ecosystem, which is unique among siblings.

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

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

Explicitly tells when to use ('is X safe / popular / small') and provides clear exclusion criteria ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also notes partial failures and graceful degradation.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K with truncation and flagging), and that results contain offsets for verification.

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

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

Three sentences, front-loaded with purpose and key features. Every sentence adds value. No redundancy.

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

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

Despite no output schema, the description explains the return format (passages with offsets and scores), covers the cap and truncation behavior, and mentions pairing with another tool. Complete for a 3-param 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 context: clarifies text max size, provides query examples, and mentions limit default (5). This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using a natural-language query, and returns top passages with offsets. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use: when the record is too big for the prompt. Describes the benefit (saves context) and mentions an alternative (ask_pipeworx_grounded).

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 non-read-only and non-destructive behavior. The description adds critical behavioral details: requires Pipeworx OAuth account, returns subscription id, delivery limitations (SMS 10/day cap), webhook auto-disabling after failures. 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?

Well-structured with action first, then auth, types, and delivery. Each sentence is necessary and informative. No wasted words while being thorough.

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 (5 types, nested objects, delivery configs, auth, rate limits), the description covers purpose, parameters, return value, delivery details, and limitations. Missing output schema is compensated by stating return is a subscription id. Highly complete for agent usage.

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

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

Schema coverage is 100%. The description enriches each parameter: explains enum values with specific examples (e.g., sec_8k items codes), clarifies type-specific params, and adds delivery behavior (email templating, SMS verification, webhook HMAC signing and one-time secret). Adds significant 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?

Clearly states the action: creating a proactive monitoring subscription. Identifies the resource (live-data event stream) and the outcome (returns new subscription id). Distinguishes from siblings like list_subscriptions and recent_alerts by focusing on creation.

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

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

Provides explicit context on when to use each subscription type (e.g., sec_8k for 8-K filings, polymarket_edge for cross-venue mispricings). Mentions delivery options and limitations. Does not explicitly compare with one-off query tools, but the purpose is clear for proactive monitoring.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds value by explaining the return format (category-bucketed questions from a live catalog), the optional topic filtering, and the tool's role as an onboarding guide. 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 well-structured with a front-loaded title that captures common queries, followed by purpose and usage details. It is slightly verbose (e.g., listing all categories), but each sentence adds value and the information is logically ordered.

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

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

Given the tool's simplicity (1 optional param, no required params, no output schema), the description fully covers purpose, return value, parameter usage, and when to invoke it. It satisfies the needs of an onboarding tool comprehensively.

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 enriches the topic parameter by listing example values (finance, pharma, betting) and explaining the effect (focus vs. full spread). This goes beyond the schema's one-line description.

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

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

The description clearly identifies this as the onboarding entry point for agents new to Pipeworx, specifying that it returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by its explicit 'use this FIRST' guidance.

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

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

Explicitly states when to use: 'Use 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 implies alternatives (e.g., ask_pipeworx, entity_profile) and explains how to narrow results with the topic parameter.

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 non-destructive write operation (readOnlyHint=false, destructiveHint=false). The description adds that the row is deactivated (not deleted) and historical events persist, which is valuable 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 two concise sentences with no wasted words. It is front-loaded with the core action and includes necessary behavioral details efficiently.

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 one parameter, no output schema, and annotations that already signal mutation safety, the description covers ownership enforcement, deactivation logic, and data persistence. It is sufficient for proper invocation.

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

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

Schema coverage is 100% with a clear description for the single 'id' parameter. The description does not add additional detail beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), the resource ('subscription'), and distinctively references siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly says ownership is enforced and that the row is deactivated, not deleted, providing context for when and how to use. It does not mention specific alternatives but is clear enough for most 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value by detailing the return structure (verdict, structured form, actual value with citation, percent delta) and noting v1 limitations (only company-financial claims). No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads the key action and examples. Every sentence adds value, no fluff, and it efficiently conveys purpose, domain, and output.

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 explicitly lists return values (verdict, structured form, actual value, citation, percent delta). It also states scope and limitations. For a single-parameter tool, this is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by providing example claims, clarifying the natural-language format, and specifying the domain. This helps the agent understand what constitutes a valid input.

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

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

The description uses specific verbs like 'verify', 'fact check', 'confirm or refute', and clearly states the resource: natural-language claim verification against authoritative sources, with a defined scope (company-financial claims for public US companies via SEC EDGAR + XBRL). It also distinguishes from siblings by stating it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It does not provide explicit when-not-to-use or contrast with alternatives, but the context is clear enough for an agent to decide.

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