Uuid

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

Annotations already indicate readOnly, openWorld, and idempotent hints, but the description adds valuable context: it explains the probe mechanism, return structure (per-model objects and combined view), and notes billing implications for Anthropic calls. No contradictions with annotations.

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

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

The description is concise (4 sentences), front-loaded with the core action, and well-structured. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description sufficiently explains the return format (per-model score, confidence, etc. plus combined view). It covers key aspects but could mention any limits or pagination if applicable. Overall, it is complete for a read-only probing 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?

With 100% schema description coverage, the description adds further clarity by explaining the default model for 'models' and the dependency of '_apiKey' on including 'anthropic'. This goes beyond the schema's basic 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 probes LLMs for knowledge about an entity and outputs a visibility score (0-100). It specifies the default model and how to include Anthropic, distinguishing it from potential sibling tools like 'scan_competitor_ai_presence' by focusing on general visibility rather than competitors.

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 mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context. However, it does not specify when not to use this tool or offer alternatives, which would improve guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds useful behavioral context: routing to 4,552 tools, returning structured answers with citation URIs. No contradictions; slightly redundant with annotations but still adds value.

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

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

Description is detailed yet well-structured with clear sections (guidelines, examples, alternatives). Mild verbosity from listing multiple alias names but front-loaded with most critical info.

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

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

Given the tool's complexity and many siblings, the description fully covers purpose, usage, alternatives, and examples. No output schema but return characteristics (citations, structured answer) are described. Complete for effective use.

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

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

Schema coverage is 100% with detailed alias descriptions. The description reiterates 'natural language question' and lists aliases but adds no significant meaning beyond the schema. Meets baseline for full coverage.

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

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

The description clearly states the tool's function: answering factual questions about current/historical data from authoritative sources. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research through explicit comparisons.

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

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

Provides explicit usage guidelines: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists specific query types. Clearly states when to use alternatives (grounded or research) and gives examples.

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 (readOnly, idempotent), description adds refusal reasons, output format, and extra cost. No contradictions. Minor omission: no mention of rate limits or auth, but not needed given context.

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

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

Well-structured, front-loaded with purpose, then details on behavior and use. Slightly verbose but every sentence earns its place. Could be trimmed slightly, but still effective.

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

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

Despite no output schema, description fully explains both success and failure return formats. Covers all refusal reasons. Adequate for a complex, high-stakes tool.

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

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

Schema coverage is 100% with descriptions for each alias. Description adds no new parameter meaning beyond the schema, which is acceptable. Baseline 3 applies.

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

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

The description clearly states this tool is for hallucination-resistant answers, extracting from tool results only. It distinguishes from sibling ask_pipeworx by specifying the extra LLM call 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?

Explicitly says use when answers will be quoted or acted on (high-stakes), and to prefer ask_pipeworx for casual lookups. Provides 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: it details the resolution process, fan-out, response shapes, safety mechanisms (low-confidence short-circuit, closed market handling), spread warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is long but well-structured with bolded section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) making it scannable. Every section adds meaningful information. Some details could be condensed, but the complexity of the tool justifies the 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 tool with 3 parameters and no output schema, the description is remarkably complete. It covers input handling, resolution logic, fan-out, response structure, safety checks, cancellation risks, and even performance tips (include_raw). Nothing critical 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%, but the description adds value beyond the schema. For the market parameter, it explains the three input formats (slug, URL, question text). For depth, it contrasts quick vs. thorough with examples. For include_raw, it explains size implications and use cases. This enriches 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 starts with a specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on data pull for research rather than arbitrage or 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?

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence before trusting analysis. It lacks explicit when-not or alternative tools, but the guidance is strong overall.

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 read-only, idempotent, and non-destructive. Description adds details on sorting by primary metric, return of paired data and citation URIs, handling of off-calendar fiscal years, and entity-specific data sources.

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

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

The description is well-structured with example queries upfront, but slightly verbose. Each sentence adds value, though some redundancy could be trimmed.

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

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

No output schema exists, but description adequately explains return values (paired data, citation URIs) and sorting behavior. Given low parameter count and high schema coverage, it is 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 semantic value by explaining what each entity type returns (e.g., 'LATEST 10-K revenue' for companies) and acceptable value formats.

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 side-by-side comparison of 2-5 companies or drugs, with example queries. It distinguishes from sibling tools like entity_profile by specifying that it handles multiple entities in one call.

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 preferring this tool over sequential single-pack lookups, and mentions it replaces 8-15 lookups. However, does not specify when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds important context: account required, paid plan for thorough, parallel decomposition, return structure with gaps[], latency (15-60s), and citation format. 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 well-structured, front-loading critical constraints (account, alternative) and then detailing functionality. Every sentence provides value, though some pruning could improve conciseness.

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, the annotations, and the lack of an output schema, the description is remarkably complete: it covers account requirements, alternative tools, use cases, limitations (breaking news), performance expectations, and output format.

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

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

Schema coverage is 100% with both parameters described. The description adds minor context (depth enum values explained, question accepts broad queries) but does not significantly extend beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, not open-web search. It distinguishes itself from siblings like ask_pipeworx and specifies the output format (findings packet with evidence, confidence, source, etc.).

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 (broad/multi-part questions) and when-not-to-use (single lookup, breaking news) with specific alternatives like ask_pipeworx. Also mentions account requirements and paid tier for thorough depth.

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

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

Annotations already declare readOnly, idempotent, nondestructive behavior. The description adds useful output context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... each result is ready to call directly, no second schema lookup needed.' 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?

Approximately 5 sentences, all front-loaded with the essential purpose. Each sentence provides new information without redundancy. The structure is logical and compact.

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 purpose (discovering other tools), the description explains what is returned (top-N with schemas and examples) and how to use the results (directly callable). Although no output schema, the description sufficiently covers the output behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema by noting aliases: 'Accepts task, q, description, search as aliases' and provides examples like 'analyze housing market trends'. This enhances understanding of the primary parameter.

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

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

The description clearly states 'Find tools by describing the data or task', using a specific verb and resource. It lists many example domains, distinguishing it from sibling tools 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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also provides context like 'Use when you need to browse, search, look up, or discover what tools exist', giving clear when-to-use and implicit when-not.

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?

Detailed description of what is returned (cik, filings, fundamentals, patents, news, LEI) and limitations (patents API sunset, news fallback, name restriction). Annotations already indicate read-only and idempotent, but description adds significant 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 relatively long but well-structured with trigger phrases upfront and detailed breakdown later. Some redundancy (e.g., mentioning 'names not supported' twice) but acceptable for 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?

No output schema exists, so description fully explains return values and structure. Covers all key aspects: inputs, outputs, limitations, fallbacks, and alternative tools. Very complete 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?

Input schema has 100% coverage with descriptions. The description adds meaning by clarifying value format (ticker or zero-padded CIK) and reiterating that names are not supported, which goes beyond the schema's description.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies, with specific examples and sources (SEC, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings like resolve_entity by explicitly stating it does not support names.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity first if only a name, 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 declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but doesn't significantly expand 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?

Very concise: two sentences, no wasted words, information 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?

Given simple delete operation with one parameter and no output schema, description fully covers purpose, usage, and relation to siblings.

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

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

Schema has 100% coverage for the only parameter 'key'. Description does not add extra meaning beyond the schema.

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

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

Description clearly states verb 'delete', resource 'memory', and method 'by key'. Distinguishes from sibling tools by mentioning 'remember' and 'recall'.

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

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

Explicitly tells when to use: when context is stale, task done, or clearing sensitive data. Also suggests 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the workflow (fetch page, extract content, emit markdown) and specifying the output location (site-root/llms.txt). No contradictions.

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

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

The description is moderately sized with a clear front-loaded purpose. It efficiently covers process, output, and use cases in a few sentences, though could be slightly more terse without losing clarity.

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

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

Given the tool's simplicity (2 parameters, no output schema, read-only), the description is complete. It explains inputs, processing, output format, and real-world applicability, leaving no significant gaps for an agent.

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

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

Schema coverage is 100% with both parameters documented. The description echoes the purpose ('URL of the site to summarize') but doesn't add new semantics beyond the schema. This meets the baseline for high coverage.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying it fetches the page, extracts title/description/key links, and outputs markdown. This distinct purpose is well differentiated from sibling tools like scan_competitor_ai_presence.

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 lists three use cases: getting a client's site indexed, drafting your own llms.txt, or auditing competitor visibility. It lacks explicit when-not-to-use guidance but the provided examples are clear and actionable.

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

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

Annotation idempotentHint=true contradicts the description's claim of generating 'random' UUIDs, which are inherently non-idempotent. This misalignment undermines behavioral transparency.

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

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

The description is a single concise sentence that front-loads the key action and resource. Every word is necessary.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers functionality. Annotations further cover safety traits, though the idempotency contradiction is noted.

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 of the 'count' parameter. The description adds no further semantic detail beyond what the schema provides, so baseline score 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?

Description clearly states the verb 'Generate' and the resource 'random v4 UUIDs', and specifies the ability to generate one or more. This is specific and distinguishes from sibling tools like validate_uuid.

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

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

The description implies usage for generating UUIDs but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing default behavior (only active subscriptions) and returned fields. No contradictions.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. Minimal waste, front-loaded with key info.

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

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

The description covers the tool's purpose, return fields, default filter, and usage context. With no output schema, the returned fields are explained. Complete for a simple list tool with good annotations.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). The tool description does not add additional parameter semantics beyond what the schema provides, earning the baseline score.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies returned fields, and distinguishes from siblings like subscribe/unsubscribe by indicating its use for review before adding or finding 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?

The description explicitly provides use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' It does not explicitly state when not to use it, but the context from sibling names is sufficient.

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

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

Description adds significant behavioral details beyond annotations: team reads digests daily, impact on roadmap, rate limit of 5 per identifier per day, free usage not counting against quota. Annotations are less informative (all false), so description carries full burden and does so well.

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, each serving a distinct purpose: purpose, usage, content guidance, impact, limitations. Front-loaded with main action, no superfluous 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?

Tool is simple (3 params, no output schema). Description covers when, what, how, and constraints. Output is not described but likely a confirmation; given simplicity, this is sufficient.

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

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

Schema coverage is 100% with good descriptions for each parameter and enum values. Description outside schema adds little new parameter detail but reinforces the guidance. Baseline 3 is appropriate.

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

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

Description clearly states the action ('tell the Pipeworx team'), resource (feedback about tools), and scope (something broken, missing, or praise). It distinguishes from sibling tools like ask_pipeworx which are for asking questions, not providing 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 specifies when to use: for bugs, feature requests, data gaps, or praise. Provides guidance on not pasting end-user prompts and mentions rate limits and cost. Lacks explicit 'when not to use' but covers key scenarios.

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

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

Adds context beyond annotations: data source (CF analytics-engine), no PII, caching duration, and self-aggregating nature. 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?

Concise paragraph with bullet-pointed use cases; 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?

For a simple read-only tool with one parameter, description covers purpose, parameter semantics, use cases, caching, and data origin completely.

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

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

Schema covers parameter well (100% coverage with enum). Description adds behavioral guidance on when to use each window (hot vs steady-state).

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

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

Description clearly states it returns trending tools/packs and call volume over recent windows, distinguishing it from siblings like 'discover_tools' which are likely for discovery of available tools.

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

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

Lists three explicit use cases for when to use this tool, but does not mention when not to use it or alternatives like 'discover_tools'.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds substantial behavioral context: SEMANTIC ANCHOR with Jaccard similarity, PARTITION FILTER for placeholder slugs, FILL CHECK against live CLOB depth, and explanation of response structure. It over-discloses behavior beyond annotations.

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

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

Description is long but well-structured: first sentence overview, then mode explanations, then technical details (semantic anchor, partition filter, fill check). Front-loaded with key information. Could be trimmed slightly but each section adds value.

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

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

Despite no output schema, the description explains the response structure (opportunities array, partition_check, fill check). It covers both parameters, modes, and important constraints. Minor missing: no mention of error handling or rate limits, but overall complete for selection and 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 description coverage is 100% but description goes further: for event parameter it explains single-event mode, recommended usage, and gives examples like 'fed-decision-may-2026'. For topic, it explains cross-event mode and provides seed question examples. Adds 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args for trending scan, event for specific market, and topic for cross-event scan. The verb 'Find' and resource 'arbitrage opportunities' are specific and indicative.

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for specific market (recommended), and topic for cross-event scanning. It provides examples of event slugs and seed questions. It does not contrast with sibling tools, but within the tool's own modes, guidelines are clear.

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

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

The description extensively details behavioral traits beyond annotations: caching (1h KV keyed on knobs), model families, exclusion of Fed bets from ranking, and diagnostic output. Annotations already indicate read-only and idempotent, but description adds significant depth.

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

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

The description is very long and contains excessive detail on model families. While front-loaded with the main purpose, it could be more concise to improve agent scanning.

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

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

Despite no output schema, the description fully explains response structure (by_segment, diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.), ensuring agents understand the return format.

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 parameter descriptions. The tool description does not add new meaning beyond mentioning knobs; 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). This distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool (discovering opportunities) and explains configurable knobs (min_liquidity, max_spread_pp) for filtering. However, it does not explicitly compare with sibling tools or state when not to use it.

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

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

The description adds context beyond annotations: explains bounded history depth (60-day TTL), decay computation from daily closes, snapshot creation triggers (cache-miss), and data gaps. 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 front-loaded with the core question. It efficiently packs many details, though the structure is somewhat lengthy. Every sentence serves a purpose.

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

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

Despite no output schema, the description thoroughly explains the return structure: tracked[], expired[], snapshot_dates[] with each field's meaning. Covers all expected outputs and behaviors.

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

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

Schema coverage is 100%, and the description adds extra context: clarifies the 'days' parameter's maximum (30) and 'window' options (24hr, 1wk, 1mo). Provides defaults and constraints beyond what schema offers.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question about how long an edge has existed. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical tracking vs. current snapshots.

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

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

The description implies use when historical persistence is needed, and distinguishes from current snapshot tools. However, it does not explicitly state when not to use or provide alternative tool names for comparison.

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

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

The description adds context beyond the annotations: it discloses that the tool walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which are consistent with the description's read-only check behavior. No contradictions.

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

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

The description is dense and packed with useful information, but it is quite lengthy (over 200 words). It uses all-caps for emphasis and is front-loaded with the main purpose. While every sentence adds value, some technical jargon might make it less accessible. A slightly more structured format could improve conciseness without losing detail.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description thoroughly explains what each mode returns: for single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and for basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers the risk of partial fills, making it complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how size_usd is interpreted differently in single-market vs basket mode (e.g., 'max spend on buys, target proceeds on sells' for single-market, 'settlement notional' for basket). It also clarifies the side parameter's auto-default for basket mode. This justifies a score of 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific return fields. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns against partial basket fills converting arb into an unhedged directional position, effectively telling the agent when not to use it.

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

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

Annotations already show readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral context: compatibility reasons, temporal alignment, skipped cross types, and rarity of real spreads. 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 detailed but front-loaded with key info (modes, response structure, safety fields). Length is justified by complexity; each 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?

No output schema, but description explains response structure (leg prices, spreads, safety fields) comprehensively. Covers compatibility, temporal alignment, skipped counters. Fully contextualized.

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

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

Schema coverage is 100% with good descriptions. Description adds meaning by explaining modes, listing macro shortcuts, and clarifying that explicit tickers override topic. Extra 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 the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on two-venue comparison and mentions modes and safety fields.

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 (comparing prices across venues for equivalent outcomes) and when not (compatibility_warning indicates non-equivalent bet shapes or temporal misalignment). Warns that pre-mapped topics often return warnings, managing expectations.

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

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

Annotations already declare safe read (readOnlyHint, idempotentHint). Description adds scope and pairing context. No contradictions. Adds value beyond annotations.

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

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

Three sentences, main action in first. No redundant information. 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?

Tool is simple (one optional param, no output schema). Description covers purpose, usage, and scope. Could hint at return format for list case, but not necessary given simplicity.

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

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

Schema covers parameter with 100% coverage. Description adds crucial usage pattern: 'omit the key argument to list all keys', which is not in schema. Provides 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?

Description states specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. Clearly distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says to use for context lookup without re-deriving. Mentions pairing with remember and forget as alternatives. Could be stronger with explicit when not to use, but adequate.

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

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

Annotations declare readOnlyHint=true, but the description describes mark_read parameter that modifies state (flags events as read), contradicting the annotation. Score 1 per rule.

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

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

Four sentences, front-loaded: purpose, return details, filtering/side effect, alternative access. No unnecessary words, 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?

Comprehensively explains return data, filtering options, mark_read behavior, and provides alternative access method. No output schema needed; all essential information present.

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

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

Schema covers all parameters (100% coverage). Description adds value with examples ('sec_8k') and explains mark_read's effect on future calls, going beyond basic 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 'Pull fired events from your subscription feed,' specifying the action and resource. It details return fields (source, citation_uri, raw payload), distinguishing it from siblings like 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 on filtering by type/since, mark_read behavior, and notes polling suitability. Mentions alternative API endpoint but does not explicitly compare to 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?

Even though annotations declare readOnlyHint and idempotentHint, the description adds rich behavioral context: it fans out to multiple sources with fallback behavior (GDELT→GNews, USPTO soft-fail), explains the output structure (changes grouped by source, total_changes, citation URIs), and mentions edge cases like PatentsView API sunset.

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 effective but slightly on the longer side (5-6 sentences). It front-loads purpose and usage, but some details (like the PatentsView sunset) could be moved to a separate section. Still, it's well-structured and every sentence adds value.

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

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

Given there is no output schema, the description compensates fully by stating it returns 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers multiple data sources with fallback logic, making the tool's behavior fully comprehensible.

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

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

Schema coverage is 100%, and the description adds value beyond the schema: it explains 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'); it clarifies 'value' accepts ticker or zero-padded CIK; and it notes type only supports 'company' today.

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

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

Description starts with example queries that clearly define the tool's purpose: 'What's new with X' / 'latest on Y' etc. It explicitly states it returns a change feed for a company in time windows, and distinguishes from 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?

The description provides a list of concrete example queries showing when to use it ('what happened to Z this week / month / quarter'). It also explicitly states when not to use it: 'Use entity_profile instead when you want the static profile ... regardless of window.' This is excellent 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 indicate idempotent, non-destructive write. Description adds persistence details (24hr vs permanent) and scoping by identifier. No contradictions. Could mention overwrite behavior but idempotent hint covers it.

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, each purposeful: purpose, usage, persistence, companion tools. Front-loaded and 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?

Simple tool with two required params and no output schema. Description covers purpose, usage, scope, persistence, and pairing with siblings. Complete for an agent to understand 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?

Schema coverage is 100% and already includes examples for key and value. Description repeats 'key-value pair' but adds no new semantic detail beyond the schema. Baseline score 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?

Clear verb and resource: 'Save data' with key-value pairs. Distinguishes from siblings 'recall' and 'forget' by mentioning them. Provides concrete examples like 'resolved ticker, target address'.

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'. Provides alternatives: 'Pair with recall... forget'. Also covers scoping and persistence.

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, and destructiveHint=false. The description adds significant behavioral context: it reveals internal cascading lookups, auto-disambiguation, and citation URIs, which go well beyond the annotations and help the agent understand side effects and output format.

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

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

The description is front-loaded with example queries, which is effective. Every sentence adds value: examples, supported types, input-output details, internal behavior. It is slightly long but well-organized; a minor trim (e.g., repeating 'Use FIRST') could improve conciseness without losing clarity.

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

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

Given the tool's two distinct entity types, 100% schema coverage, no output schema, and comprehensive annotations, the description fully covers what the agent needs: inputs, outputs, internal behavior, and use case. It is complete and leaves no obvious gap for successful 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% for both parameters, but the description adds rich semantic detail: for 'type', it explains what each enum value returns (ticker+CIK for company, RxCUI for drug) and acceptable input formats (ticker, CIK, or name). For 'value', it provides examples and clarifies input variations, greatly augmenting 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 specifies a clear verb 'resolve' and resource 'entity name to identifier', with concrete examples (ticker, CIK, RxCUI). It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', which sets it apart from other tools like entity_profile or compare_entities that are for 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?

It explicitly says when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also hints at efficiency by noting it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or direct to alternative tools for other post-resolution needs, leaving slight room for improvement.

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

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

The description explains the internal process (probing each entity with ai_visibility_check, ranking by score) and output format (ranked list with score, confidence, signal density). Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description adds value by detailing the workflow without contradicting annotations.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence earns its place: first states the action, second explains the mechanism, third provides use case and return format. No redundant words.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It explains the tool's reliance on ai_visibility_check. However, it does not address error scenarios or timeout behavior, but overall it is sufficiently complete for a wrapper 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%, but the description adds extra meaning by stating that the first entity in 'entities' is treated as the subject for narrative purposes. This is beyond what the schema provides, enhancing parameter semantics.

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: comparing AI visibility across multiple entities side-by-side, using a specific verb (compare, probes, ranks, surfaces). It differentiates from sibling 'ai_visibility_check' by focusing on multiple entities and mentions the use case (competitive AI-marketing audits) with an example query.

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

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

The description provides clear context for when to use the tool (competitive audits, comparing multiple entities) and implicitly contrasts with the sibling 'ai_visibility_check' for single-entity probes. It mentions that the first entity is treated as the subject, but does not explicitly list alternative tools or state when not to use it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds crucial info about partial failures and the 5-30s delay for first bundlephobia measurements, enhancing transparency.

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

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

Concise yet comprehensive, front-loaded with core purpose, then details on return values and edge cases. Every sentence contributes useful information without redundancy.

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

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

Given no output schema, the description fully enumerates return fields (summary block, advisory details, links, alternative versions) and handles partial failures. Covers all necessary context for an agent to use the tool.

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

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

With 100% schema coverage, the description still adds value by clarifying scoped package syntax and the default version behavior, 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 it's a composite check for evaluating npm packages, combining multiple data sources. It distinguishes itself from sibling tools, none of which perform dependency scanning.

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

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

Explicitly specifies when to use ('is X safe / popular / small') and notes ecosystem limitations (NPM only in v1, with others covered by deps.dev:version directly). Also mentions graceful degradation on slow bundlephobia measurements.

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

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

Discloses beyond annotations: uses BGE-base-en embeddings with cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that every passage carries a character offset for verification. 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?

Packed with valuable information in a short paragraph. Front-loaded with purpose, each sentence adds unique value: use case, benefits, technical details, pairing suggestions. No wasted words.

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

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

Despite no output schema, the description explains return type (passages with offsets and similarity scores) and covers edge cases (truncation, cap). Technical details about embeddings and windowing are sufficient for safe invocation.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaningful usage context: 'pass the text you already pulled' for the text parameter and 'natural-language query' for query, which enhances the schema descriptions. Limit parameter is well-explained in both.

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 semantic search inside a fetched record, provides concrete examples (SEC 10-K, article, tool result), and distinguishes from the sibling ask_pipeworx_grounded by explaining the pairing 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?

Explicitly says when to use: when the record is too big to cram into the prompt. Also mentions when not to use (e.g., for whole document grounding, pairs with ask_pipeworx_grounded) and highlights the benefit of saving 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?

Beyond annotations (readOnlyHint=false, etc.), the description discloses important behaviors: requires OAuth account, details on delivery channels (always-on feed, optional email/SMS with rate limits), webhook signing secret, and auto-disable after 10 consecutive 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?

The description is well-structured and front-loaded with the main purpose. It uses bullet points effectively. While fairly long, every sentence adds value. Minor tightening could be done, but overall efficient.

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

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

Given the complexity (nested objects, multiple types, delivery options), the description covers purpose, requirements, types, delivery channels, and rate limits. No output schema, but it specifies return value. Missing explicit idempotency handling, but overall complete enough for agent use.

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

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

Schema coverage is 100%, and the description adds significant meaning by explaining each subscription type's params with examples, and for delivery, it details SMS verification, email validation, and webhook HMAC signing. This goes well beyond the schema's bare descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation aspect.

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

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

The description provides explicit when-to-use guidance by detailing requirements (Pipeworx OAuth account) and supported subscription types with examples. However, it does not explicitly state when not to use or mention alternatives, though enough context is given for the agent to decide.

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

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

Annotations already indicate safe, non-destructive behavior. The description adds behavioral transparency by detailing the output format (category-bucketed example questions with exact tool+argument shape) and that it requires no arguments for full spread, fully disclosing what happens.

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

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

The description is appropriately sized and structured. It front-loads alternative phrasings, lists categories, and provides actionable guidance. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity and full schema coverage, the description is complete. It explains the purpose, usage, parameters, and output format thoroughly, even without an output schema.

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

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

The schema provides 100% coverage of the only parameter 'topic' with a description. The description enriches this by explaining the effect of omission ('cross-category spread') and listing valid topic values, adding 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?

The description explicitly states it is the onboarding entry point that returns category-bucketed example questions with tool+argument shape. It differentiates from siblings by instructing to use this FIRST, and lists specific categories, making it clear what the tool does.

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

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

The description provides clear when-to-use guidance: '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 mentions alternative meta-tools but does not explicitly state when NOT to use this tool, slightly reducing clarity.

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-destructive modification, but the description adds critical context: the row is deactivated (not deleted) and historical events remain available via recent_alerts. 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?

Two concise sentences, front-loaded with purpose, no wasted words. Efficiently communicates all necessary information.

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

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

For a simple 1-parameter tool with no output schema, the description is complete: it covers purpose, ownership, behavioral effect, and availability of historical data. No gaps remain.

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 of the 'id' parameter as a UUID returned by subscribe. The description reinforces this by saying 'by id', adding contextual meaning beyond the schema.

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

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

The description clearly states the verb 'cancel' and resource 'subscription', and adds specificity with ownership enforcement and soft deactivation. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description clearly states ownership enforcement ('you can only cancel your own subscriptions'), but does not explicitly mention alternatives or when not to use. However, the context strongly implies usage scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it uses SEC EDGAR + XBRL, returns a structured verdict with specific categories, and mentions version (v1) and scope. 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 front-loaded with trigger phrases and use case, then covers scope and return format. Every sentence adds value, though it is slightly verbose. It remains focused 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 the single parameter, rich annotations, and no output schema, the description adequately covers purpose, input, and output (verdict types, citation, delta). It could mention potential failure modes or limitations (e.g., only public US companies), but overall 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?

Only one parameter 'claim' with schema coverage 100% (including examples). The description adds further explanation: it provides context on the types of claims handled (e.g., company-financial) and examples, meaningfully expanding 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 verifies natural-language claims against authoritative sources. It provides specific verbs and examples ('fact check', 'verify the claim that...') and distinguishes from other tools by noting it replaces multiple 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.' It also specifies the scope (company-financial claims) and return format. It lacks explicit when-not-to-use scenarios or direct alternatives, but the context is clear.

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

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

The description fully discloses the tool's behavior beyond annotations: it returns version, variant, nil/max, and timestamp for time-based versions. Annotations already indicate safety and idempotency; the description adds key details about output.

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

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

A single, well-structured sentence that efficiently conveys all necessary information without redundancy. Every part is meaningful.

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 parameter and no output schema, the description is complete. It explains the purpose, what it checks, and what return values to expect, fulfilling all information 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?

The input schema already covers the only parameter with a clear example. The description adds no additional parameter-specific meaning beyond stating the tool is keyless and offline, which is not directly about the parameter.

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

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

The description clearly states the tool validates and parses a UUID, specifying the resource (UUID) and the action (validate/parse). It distinguishes from sibling tools like generate_uuid by focusing on validation and parsing.

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

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

The description provides clear context ('keyless, offline') and implies usage for UUID validation. While it doesn't explicitly exclude alternatives, the purpose is distinct enough to guide selection.

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