Take The Meeting

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

Annotations already indicate safe, non-destructive, and idempotent behavior. Description adds valuable beyond annotations: default model (Workers AI Llama-3.3-70b), optional Anthropic probe with BYO key, and return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 that efficiently convey purpose, default behavior, optional key usage, and return format. No wasted words. Front-loaded with main functionality.

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

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

No output schema, but description succinctly describes return fields. Parameter count is 4 with no nested objects, so the description is adequate. Could mention asymptotic behavior or limits, but not critical for functional understanding.

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

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

Schema coverage is 100% (4 parameters fully described). Description adds meaning: explains default model, clarifies _apiKey is only needed for Anthropic, and highlights context field for disambiguation. This provides useful nuance beyond raw schema.

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

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

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score. The verb 'probe' and resource 'LLMs' are specific. Distinguished from siblings by focusing on AI visibility scoring rather than general factoid queries or research.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not mention when not to use or directly compare to siblings like scan_competitor_ai_presence, so slightly lacking in exclusion 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, so no contradiction. The description adds valuable context beyond annotations: it routes to 5,529 tools, returns 'structured answer with stable pipeworx:// citation URIs', works on every tier, and is 'one fast call'. It does not discuss failure modes or rate limits, but for a read-only query tool, the safety profile is well covered by annotations and the added routing/citation detail is useful.

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 longer than minimal, but every sentence earns its place: it gives usage priority, domain coverage, trigger phrases, examples, alternative tools, and output characteristics. It is front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and structured to be quickly scannable. It is not padded, though it could be slightly more concise without losing 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 explains the return format ('structured answer with stable pipeworx:// citation URIs'). It covers supported domains (SEC, FDA, FRED/BLS, patents, real estate, etc.), examples, sibling differentiation, and default behavior. It even notes that it handles breaking news and routes to live news feeds. This is a complete picture for an agent to decide when and how to invoke 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?

Schema coverage is 100% with a clear description for the 'question' parameter and aliases listed. The description provides example questions that illustrate expected input ('current US unemployment rate', 'Apple's latest 10-K'), but these examples are also implied by the schema's examples. The description adds no new semantic meaning beyond what the schema already documents, so 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?

The description clearly states the tool answers factual questions about real-world entities, events, and numbers, routing to 5,529 tools across 1,455 sources. It differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with distinct behaviors. Specific verb phrases like 'PREFER OVER WEB SEARCH' and 'START HERE' establish a clear primary purpose.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It gives trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete examples. It also explains when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it states candidate routing improvements are enabled live when under test, clarifies no candidate is active as of 2026-07-26, and explains that results are compared against the stable router. It also clarifies that this is a full working router with no fallback, exceeding the annotation information.

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

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

The description is front-loaded with the core purpose and maintains a structured, informative tone. Though it includes a specific date and detailed explanation of the experimental status, each sentence contributes to understanding the tool's behavior. It is appropriately sized for a beta variant.

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 simple input schema (one required question, five aliases) and strong annotations, the description provides sufficient context: what the tool is, its current status, how to use it, and a note that its response shape matches ask_pipeworx. However, without an output schema, it does not describe the exact return format, though the reference to 'same response shape' compensates somewhat.

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% across 6 parameters, all of which are aliases for 'question' with full descriptions. The description adds no additional parameter-specific meaning beyond referencing 'same arguments' as ask_pipeworx, so it does not improve on 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 identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental routing status, making the purpose specific and non-tautological.

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 an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router and notes that current results match ask_pipeworx exactly, implying when to prefer stable. However, it does not explicitly name alternatives or when not to use it, so not a full 5.

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

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

While annotations already declare readOnly and idempotent behavior, the description adds valuable context: it explains that the tool uses only tool-result content, returns a specific refusal structure with reasons, and incurs an extra LLM call. These details go beyond annotation hints and inform the agent of expected constraints and failure modes.

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 longer than average but every sentence provides distinct value: purpose, mechanism, use cases, cost trade-off, and refusal behavior. It is front-loaded with the primary purpose and structured logically. Minor redundancy with annotations (readOnly, etc.) but not to a degree that harms 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?

Despite lacking an output schema, the description thoroughly explains the return format and all possible refusal reasons, resolving ambiguity about error handling. It also covers the trade-off with the sibling tool, making the overall context complete for an agent 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 input schema is fully self-documented (100% coverage), including aliases. The description adds minimal parameter guidance beyond 'question in natural language', but given the schema's clarity, this is acceptable. A baseline 3 is appropriate because the description doesn't need to compensate for schema gaps.

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 the tool as a hallucination-resistant answer mode for grounded, high-stakes reads, and explicitly distinguishes it from its sibling ask_pipeworx by describing its extraction-only behavior. The verb 'extracts' and resource 'answer using tool result' are specific and actionable.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to (prefer ask_pipeworx for casual lookups), with rationale (extra LLM call). This provides clear decision-making guidance beyond just a general description.

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 the annotations (readOnlyHint, etc.) by detailing internal behavior: market resolution, classification, parallel fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallback handling, and safety mechanisms. It explains blocking paths and the behavior of closed markets. 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 very long (multiple paragraphs) and includes extensive details, which is informative but not concise. It is front-loaded with a clear first sentence, but the length could be reduced for quicker comprehension. It is adequately structured with sections but verbose.

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

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

Given the complexity of the tool (no output schema, 3 parameters), the description is thorough. It covers all return shapes, edge cases, safety checks, blocking conditions, and even includes resolution-rule risk. The agent has enough information to use the tool correctly and interpret results.

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

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

Schema description coverage is 100%, so the schema already describes all parameters. The description does not add new semantic information about parameters beyond what the schema provides, though it reinforces the examples for the 'market' parameter. 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: research a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The use cases are given explicitly: 'should I bet on X', 'what does the data say about Y', etc. This distinguishes it from sibling tools by being a comprehensive research tool.

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

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

The description provides clear context for when to use (researching bets for edge detection) and includes safety warnings about inspecting market_match_confidence and cancellation rules before acting. It mentions blocking conditions like low_confidence_match and market_closed_or_inactive. However, it does not explicitly state when not to use the tool or mention alternatives among sibling tools, though the use cases are well-defined.

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, open-world, idempotent, non-destructive. The description adds significant behavioral detail: for companies it pulls latest 10-K financials with correct fiscal-year handling; for drugs it pulls FAERS counts, FDA approvals, trial counts. It notes results are sorted by primary metric and returns paired data with 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 comprehensive but slightly long. However, it is front-loaded with common natural-language triggers and every sentence provides unique value. Could be trimmed slightly but remains efficient.

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

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

The tool is moderately complex (2 entity types, multiple data sources, sorting, citation URIs). The description covers the core functionality, input examples, output structure, and when to use. It does not detail error cases or edge limitations, but given the clear schema and annotations, 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%, so baseline is 3. The description adds meaning beyond the enum labels: for 'type' it explains what data each enum value retrieves; for 'values' it gives concrete examples for both company (tickers/CIKs) and drug (names) and confirms min/max counts. This adds real-world context.

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

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

The description clearly states the action (side-by-side comparison) and the resources (companies or drugs). It distinguishes from sibling tools like entity_profile by emphasizing it replaces 8–15 sequential lookups and always prefers this tool over sequential single-pack lookups.

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

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

Explicitly provides natural language triggers ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies', 'head to head') and states 'ALWAYS PREFER over sequential single-pack lookups'. It also explains the entity types and what data each pulls, giving clear guidance on when to use.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account requirements, paid tier for thorough depth, latency expectations (15-60s, up to ~90s), and output behavior including gaps[] and contradictions[]. It states citations are always fetchable and large records are semantically excerpted, adding substantial behavioral context.

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

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

The description is long but information-dense; every sentence provides necessary context. It is well-structured with an account warning first, then purpose, usage cues, and operational details, though a few points (e.g., 'NOT open-web search') 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?

Given the tool's complexity and the absence of an output schema, the description compensates by describing the findings packet, evidence, citations, gaps, contradictions, hop fields, and latency. It also covers edge cases like topical relevance to structured catalog, making it fully self-sufficient.

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

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

Schema coverage is 100%, but the description adds value by clarifying the meaning of 'question' in context and elaborating depth behaviors ('standard re-angles unanswered gaps', 'thorough chases leads'). It also adds the caveat that thorough requires a paid plan, which is not in 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 opens with 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and then details decomposition and parallel routing, making the tool's purpose explicit and specific. It also distinguishes from ask_pipeworx, clarifying that this is for broad/multi-part structured questions, not single lookups or open-web search.

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

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

It explicitly states when to use this tool: 'Best for broad/multi-part questions over structured data' and gives concrete examples. It also lists exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING... prefer ask_pipeworx', plus a fallback if not signed in.

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 readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N tools with full schemas and examples, ready to call directly, which is useful behavioral context beyond annotations.

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

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

Concise and front-loaded with purpose. Uses bullet-like listing of domains efficiently. Could be slightly tighter but overall good structure.

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 clearly explains what is returned (tool names, descriptions, schemas with examples). For a search/discovery tool, this is complete enough given annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions result format but adds minimal parameter-specific meaning beyond the schema. Aliases are already in 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 tools by describing data or task, listing many domains. It uses specific verb 'find' and resource 'tools', distinguishing it from sibling tools which are more specific (e.g., deep_research, 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?

Explicitly says 'Call this FIRST when you have many tools available' and to see the option set, giving clear context. Does not mention exclusions or alternatives, but the guidance is strong for when to use.

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

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

The description adds extensive behavioral context beyond annotations: it lists data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), details return fields, notes the USPTO soft-fail, and specifies input constraints. It does not contradict any 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 detailed but front-loaded with examples and usage priority. Every sentence contributes value, though it could be slightly more streamlined. It is well-structured and easy to parse despite length.

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

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

Given the complexity of a cross-source profile tool with no output schema, the description comprehensively covers inputs, outputs, data sources, and limitations (e.g., patents soft-fail). It leaves no significant gaps for agent understanding.

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

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

Schema coverage is 100%, but the description adds value by explaining that type is only 'company' for now, value can be ticker or CIK, and names are unsupported. It provides examples and enriches the meaning beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs like 'brief me on' and 'research,' and distinguishes from siblings like resolve_entity 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?

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity first if only a name is available, 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. The description adds behavioral context by stating 'Delete' and implying safety (idempotent deletion by key). 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 with zero waste. The first sentence states purpose, the second provides usage guidance. Fully 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 low complexity (one required parameter, no output schema, no nested objects), the description fully covers what the tool does and when to use it.

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% for the single 'key' parameter. The description does not add extra detail beyond 'by key', so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by name.

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 when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with remember and recall, though no explicit 'when not to use' is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety profile is clear. Description adds process details (fetches page, extracts metadata, emits markdown) and output format, which enhance transparency 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 succinct, front-loaded with the main action, and includes a bullet list of use cases. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (2 params, no output schema), the description effectively explains the process, output, and use cases. It lacks details on error handling or edge cases, but overall is sufficient for agent 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 covers both parameters (url and max_links) with descriptions, achieving 100% coverage. Description does not add extra semantics beyond schema, 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 generates a production-ready llms.txt file for a given URL, specifying verb 'generate' and resource 'llms.txt file'. It distinguishes from sibling tools (e.g., ai_visibility_check) by listing specific use cases like drafting llms.txt for projects or auditing competitor AI visibility.

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 (client site indexing, personal project drafting, competitor auditing) helping the agent decide when to use. However, it does not mention when not to use or list alternative tools explicitly, so slightly below a perfect score.

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?

Descriptions adds return fields and optional parameter behavior, complementing annotations (readOnlyHint, idempotentHint). Does not contradict annotations. Minor lack of pagination/limits info but acceptable for simple tool.

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

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

Three concise, front-loaded sentences covering purpose, return fields, and usage recommendation without any 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?

Fully adequate for a simple tool with one optional parameter and no output schema. Lists all returned fields and provides usage guidance.

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

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

Schema covers 100% of parameters with description; description does not add significant meaning beyond stating 'active subscriptions' which aligns with default schema 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?

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. Distinguishes itself from siblings like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for invocation.

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

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

Discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later'), the fact that it is free and doesn't count against tool-call quota, and how the team processes feedback ('reads digests daily and signal directly affects roadmap'). This goes well beyond the sparse annotations (all false) and leaves no ambiguity about side effects or expectations.

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 longer than average but every sentence adds critical operational detail (scope, token flow, rate limit, quota). It is front-loaded with purpose and usage, then flows logically into mechanics and constraints. It earns the length, but could be tightened by moving the 'Not sure?' clause earlier—still highly 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?

For a 4-parameter, no-output-schema tool, the description covers all essential context: what to report, what not to report, scope exclusions, token-based follow-up, team workflow, and rate limits. No output schema exists, but the description explains the claim_token return behavior sufficiently. This is complete enough for an agent to invoke the tool correctly and follow up appropriately.

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 semantics beyond schema: it explains the claim_token round-trip pattern in detail, instructs on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and contextualizes the 'type' enum via the usage examples. Slight deduction because it doesn't directly walk through the nested 'context' object, but the schema already covers that.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also lists concrete categories (bug, feature/data_gap, praise) and distinct scope (only for tools served by this Pipeworx connection), which clearly distinguishes it from sibling research/subscription 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives exclusions: if the tool came from a different MCP server, 'file it with that server instead,' and offers a heuristic for uncertainty: 'Pipeworx tool names are the ones this connection lists.'

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 read only, idempotent, non-destructive hints. The description adds valuable context: self-aggregating from CF analytics, no PII, caching behavior (5min-1h), and data structure (pack, tool, count). No contradictions.

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

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

The description is two well-structured paragraphs: first sentence states output, then bullet list of use cases, then technical notes. No fluff, every sentence adds value. Front-loaded with the core purpose.

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

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

Despite having no output schema, the description explains exactly what is returned (top tools, packs, call volume), caching, and data source. With one optional parameter and no required fields, this is fully complete for an agent to understand the tool's 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% and the schema description already explains the enum values and their interpretation. The tool description does not add additional parameter details beyond what is in the schema, so baseline 3 is appropriate.

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

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

The description clearly states it returns top tools, packs, and call volume, using a specific verb ('Returns') and resource. It distinguishes from siblings like discover_tools by emphasizing it shows what other AI agents are calling right now.

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: discovering hot data sources, confirming canonical tool choice, and aligning use cases. It does not explicitly state when not to use or mention alternative tools, which would elevate it to a 5.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description goes far beyond by explaining the internal algorithms (monotonicity, partition-sum checks, Jaccard similarity filter, placeholder filter) and the fill check process. It discloses behavioral traits like response structure and trade signals, adding significant 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 lengthy (4 paragraphs) but well-structured and front-loaded with the main purpose. It contains dense, valuable information. Some redundancy could be trimmed, but every sentence contributes to explaining the tool's complex behavior.

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

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

Despite no output schema, the description adequately covers return values (opportunities array with fields like gap_pp, suggested_trade, reasoning) and mentions fill check behavior. It provides sufficient completeness for an AI to understand usage and output, though exact field types are not detailed.

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

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

Schema description coverage is 100% with both parameters having clear descriptions. The tool description adds extra semantics (e.g., that event accepts full URLs, topic uses seed questions, and how each mode works), enhancing understanding 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 the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) and what each does. While it doesn't explicitly differentiate from sibling 'polymarket_edges', the purpose is distinct and clearly articulated.

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 for each mode, including recommendations (e.g., 'event (recommended for a specific market)') and explanations of when cross-event mode is beneficial. It also warns when not to trade (realizable_edge_pp <= 0) and references polymarket_fill_risk for custom sizing, offering comprehensive when-to-use and when-not-to-use information.

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

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

The description discloses significant behavioral traits beyond annotations: it explains the three response segments with model details, caching behavior (Cached 1h at the KV level), and the diagnostic section. It does not contradict annotations; all align with readOnlyHint and idempotentHint.

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

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

The description is verbose but well-structured, with clear segmentation and bullet points. It front-loads the main purpose and uses formatting for readability. While some details could be trimmed, 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and the meaning of each field. It also covers parameter usage and behavioral notes fully, making the tool complete for an agent.

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

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

With 100% schema coverage, every parameter has a description. The tool description enriches parameter meaning by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and providing context like slippage_pp defaults and recommendations. This adds significant value 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 the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies its use case as 'what should I bet on today' and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on disagreement-based edges.

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

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

The description provides extensive usage context, including when to use this tool for opportunity discovery, how to adjust tradeable-edge knobs, and a note on Fed markets being excluded from ranking. However, it does not explicitly name alternatives or state when not to use this tool, so it misses the top score.

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 extensive behavioral context beyond annotations: explains data sources, time-series structure, trend computation, decay handling, and limitations like 60-day TTL and snapshot gaps. No contradictions with annotations.

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

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

The description is front-loaded with purpose and structured with clear sections (args, response format, limits). It is somewhat long but every sentence adds value, making it efficient.

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

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

Despite no output schema, the description fully explains response structure, trend classification, decay formula, and limitations. It covers all necessary information for correct 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%, so baseline is 3. The description adds minor context (e.g., 'snapshot family' for window) but mostly repeats schema info. Slight discrepancy in max vs. clamp is minor.

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: tracking edge persistence and decay from daily snapshots. It answers specific questions and distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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 on when to use (to differentiate fresh vs. old edges) and implies alternatives by noting limitations like daily close data and history depth. It does not explicitly list when not to use, but the context 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: live CLOB check, verdict output, forced directional risk, and effects of partial fills. Does not contradict annotations.

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

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

Description is dense but well-organized with clear sections for single-market and basket modes, and a usage guideline at the end. Every sentence adds value, though length could be slightly reduced with bullets.

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

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

Despite no output schema, description comprehensively explains return values for both modes, covers edge cases (thin legs, directional risk), and provides usage context. Sufficient for an agent to understand and invoke the tool correctly.

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

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

Each of the 4 parameters has schema descriptions (100% coverage). The tool description adds context: required one of market/event, default values, interpretation of size_usd for buys vs sells, and side auto-detection in basket mode. 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?

Description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes single-market and basket modes, lists specific outputs, and differentiates from sibling tools (polymarket_arbitrage, 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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills convert arb into directional position. Provides clear when-to-use and rationale.

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

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

The description provides extensive behavioral context beyond annotations: details on compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal alignment, skipped cross-type/subtype counters, and the rarity of real spreads. No contradictions with annotations (readOnlyHint, idempotentHint, openWorldHint).

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

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

The description is thorough and well-structured, using bold headers and bullet-style explanations (TWO MODES, RESPONSE, SAFETY FIELDS). While somewhat lengthy, every sentence serves a purpose. Minor redundancy ('matched_pairs:0' explained twice) prevents a perfect 5.

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 description covers all necessary aspects: modes, input parameters, response structure (spreads, compatibility_warning, temporal_alignment, skipped counters), edge cases, and limitations. No output schema exists, but the description compensates 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the two modes in detail, providing examples, and clarifying that using both explicit tickers overrides topic mapping. This extra context on parameter interplay justifies a 4.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (spread comparison), resources (two prediction market venues), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads.

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 which mode: topic shortcuts vs explicit event tickers. It warns that most pre-mapped topics currently return compatibility warnings, cautioning against assuming tradeability. This effectively guides the agent on 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?

Adds scoping detail (identifier-based) beyond annotations (readOnlyHint, idempotentHint). Discloses listing behavior when key is omitted. 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?

Three sentences, all essential. No fluff. Core action in first sentence, supplementary details follow logically.

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

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

Covers purpose, usage, scoping, and pairing. Lacks explicit mention of return format, but simplicity of tool and lack of output schema make this acceptable.

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 semantic context about omitting key for listing and gives real-world usage examples. Slightly elevates beyond baseline of 3.

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

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

Clearly states it retrieves a value saved via 'remember' or lists all keys. Distinguishes from sibling tools 'remember' and 'forget' by naming them explicitly.

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 examples of contexts to use (target ticker, address, research notes) and pairs with 'remember' and 'forget' for complementary actions. Implicitly tells when not to use.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description explicitly says setting mark_read:true will mark events as read, indicating a state change. This contradicts the readOnlyHint annotation. The description also mentions mark_read as a parameter but does not resolve the inconsistency.

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

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

The description is efficient and front-loaded with the core purpose. Each sentence adds meaningful information (e.g., what events carry, filtering options, mark_read behavior, alternative endpoint). It is not overly verbose, but could be slightly tighter.

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 tells the agent what fields to expect (source, citation_uri, raw event payload). It explains filtering, mark_read behavior, and even provides an alternative REST endpoint. This is comprehensive for a read-focused 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?

All parameters have schema descriptions, and the tool description adds extra context for 'type' (example value 'sec_8k'), 'since' (ISO timestamp format), and 'mark_read' (explains its effect). The explanation of 'mark_read' and 'since' goes beyond the schema. However, 'limit' and 'unread_only' are not elaborated further.

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 begins with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states the tool retrieves recent alerts and explains what each event carries (source, citation_uri, payload). This differentiates it from sibling tools 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?

The description mentions polling works fine and points to an external alternative endpoint for scripts and dashboards. However, it does not explicitly state when to use this tool versus other PipeWorx tools or 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses parallel fan-out to multiple sources, fallback logic, USPTO API status, and output format (grouped changes, total count, citation URIs). No contradictions with annotations.

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

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

The description is a single paragraph that is slightly long but every sentence adds value. It is front-loaded with examples and well-organized, though minor restructuring could improve scanability.

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 adequately explains the output format and sources. For a tool with 3 parameters and no output schema, the description provides sufficient completeness for agent understanding.

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

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

Schema coverage is 100%, but the description adds value: clarifies `type` as only 'company', provides examples for `since` (ISO date or relative shorthand), and explains `value` as ticker or CIK. Adds monitoring recommendation.

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

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

The description clearly defines the tool as a change feed for a company aggregating SEC filings, news, and patents. It provides example queries and explicitly distinguishes from sibling entity_profile, ensuring the agent can differentiate.

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

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

The description includes explicit usage patterns, fallback behavior (GDELT→GNews), soft-fail for USPTO, and directs to use entity_profile for static profiles. It also advises on typical `since` values like '30d' or '1m'.

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 valuable behavioral context beyond annotations: scoping by identifier, persistence details (persistent for authenticated, 24-hour for anonymous). Annotations already show idempotentHint=true and destructiveHint=false, which the description supports.

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?

Extremely concise and well-structured: first sentence states purpose, second gives usage context, third explains behavior. No wasted words, front-loaded with most important information.

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

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

Despite no output schema, the description covers purpose, usage, and behavioral details adequately for a simple store operation. It does not describe return values, but for a save tool this is acceptable. Lacks mention of error cases or overwrite behavior, but still 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%, so the description adds marginal extra meaning. It provides example key formats and clarifies that value can be any text, but the schema already conveys this. No new parameter semantics beyond examples.

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 ('Save data the agent will need to reuse later'), uses a specific verb ('save') and resource ('data'), and distinguishes from sibling tools like recall and forget by mentioning pairing.

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 examples of appropriate data types, and mentions scope differences (authenticated vs anonymous) without contradicting siblings.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral traits: it cascades through multiple lookup endpoints, handles GLEIF/OpenFIGI unavailability gracefully, labels all identifiers with their source, and explicitly reports unresolved identifiers under `unresolved`. These details are not present in the annotations and give the agent confidence in how the tool behaves under partial failures.

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

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

The description is long but well-structured: it opens with illustrative user queries, then a concise purpose statement, followed by a detailed breakdown of supported types and behavior. Every sentence adds either usage context or operational detail. The length is justified by the complexity of the tool, and the text is not redundant. It loses one point because some details (like the parent/ultimate-parent explanation) could be compressed, but overall it is efficiently organized and 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?

With no output schema, the description fully explains return values per type: company returns CIK, ticker, LEI, FIGI, and unresolved list; drug returns RxCUI, ingredient, brand, and citation. It also covers failure modes (LEI/FIGI enrichment degradation) and the fact that the tool replaces multiple manual lookups. This gives the agent a complete picture of expected inputs and outputs, making it exceptionally complete for a lookup 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?

Although the schema already describes both parameters at 100% coverage, the description adds substantial semantic value. It explains what each `type` returns (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and which input formats are accepted for `value` (ticker, CIK, or name for companies; brand or generic name for drugs). This goes far beyond the schema's enum and examples, helping the agent choose appropriate parameter values.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It specifies the verb 'resolve' and the resource (names to IDs), and it differentiates from sibling tools by emphasizing that it produces identifiers needed by other tools. Examples of user queries make the purpose immediately understandable and distinguish it from general lookup or profiling 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 gives an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported entity types (company, drug) and acceptable input formats. It does not explicitly state when not to use it or mention alternatives, but the 'Use FIRST' directive and the tool's specialization provide clear context. The graceful degradation note also helps set expectations during use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint as true. The description adds critical context: internal use of ai_visibility_check, ranking logic, return fields (score, confidence, signal density), and narrative treatment of first entity. 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?

Three sentences, each packed with information: purpose, mechanism, use case, and return details. Front-loaded with the core action. No filler or repetition.

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

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

Despite lacking an output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers the workflow and dependencies. Minor gaps like error handling or size limits are already addressed in the schema.

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

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

Schema coverage is 100% so baseline 3. Description adds value beyond schema: clarifies that the first entity in 'entities' is the 'subject' for narrative, and provides real-world examples for 'context' parameter. This extra detail informs proper usage.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clarifies the resource ('AI visibility across multiple entities'). It distinguishes from siblings by explicitly referencing ai_visibility_check and comparing multiple entities, contrasting with single-entity tools like ai_visibility_check itself.

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 concrete use case ('competitive AI-marketing audits') and implies when to use the tool. It hints at alternatives by mentioning it uses ai_visibility_check, but does not explicitly state exclusions or when to opt for a different tool.

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

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

Annotations already declare safe, open-world, idempotent, and non-destructive behavior. The description adds valuable context about partial failures, timeout for bundlephobia's first measurement, and graceful degradation, which exceeds annotation coverage.

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

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

The description is front-loaded with the core purpose and structured logically, covering summary, usage, and edge cases without unnecessary verbosity. Every sentence adds value.

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

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

Despite lacking an output schema, the description lists all return fields and explains ecosystem limitations, fallback, and error handling. It is 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds operational context (e.g., scoped packages accepted, default to latest version), which provides additional value beyond the schema.

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

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

The description clearly defines the tool as a composite check for evaluating npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying the NPM ecosystem and referencing fallback methods.

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 the tool (e.g., 'is X safe/popular/small') and provides context for when not to use it, noting that PyPI/Maven fall under a different endpoint. This guides the agent effectively.

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 embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), and character limit (200K with truncation flag). These go beyond the annotations which only state readOnly, openWorld, idempotent, not destructive.

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

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

Concise at ~100 words, front-loaded with purpose, followed by usage guidance, then technical details. Every sentence serves a purpose with no redundancy.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores), error handling (truncation flag), and tool relationships. Complete for a retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving natural-language query examples and reinforcing the text limit, but doesn't introduce critical new parameter info. A 4 reflects the slight improvement over baseline.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples and contrast to sibling tools like ask_pipeworx_grounded. It uses a strong verb-resource pair and clarifies the scope.

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 ('record too big to cram into the prompt') and mentions an alternative pairing (ask_pipeworx_grounded). Provides clear context for when this tool 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 indicate write, idempotent, non-destructive. Description adds: returns subscription id, account requirement, delivery details (webhook signing secret, auto-disable after 10 failures). No contradiction. Mentions rate limit for SMS but not idempotency explicitly.

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

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

Long but efficient, front-loaded with main purpose. Each sentence adds value. Could be slightly tighter, but 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?

Covers multiple subscription types, delivery channels, auth requirements, and references related endpoints. No output schema but mentions return value. Feels complete 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%, so baseline 3. Description adds significant value by explaining type-specific params (e.g., sec_8k item codes, webhook signature) and delivery options 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 specifies the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation and monitoring.

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

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

Provides detailed context: requires Pipeworx OAuth account, lists supported types with examples, and explains delivery channels with constraints. Lacks explicit 'when not to use', but the specificity makes usage clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: the output is category-bucketed example questions from a live catalog, and it's the onboarding entry point. This complements the annotations without contradiction.

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

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

The description is fairly long but well-organized, front-loading the core purpose and usage. Each sentence adds value, though it could be slightly more concise. The structure is clear with examples and usage instructions.

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 (category-bucketed example questions with tool/argument shapes). It covers the single parameter, usage scenarios, and fits the tool's role as an onboarding entry point. Complete for its purpose.

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

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

The single optional parameter 'topic' has schema description (100% coverage). The description explains valid values like 'finance' or 'pharma' and says 'Omit for a cross-category spread,' adding significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions and the exact tool/argument shapes. It specifies it's an onboarding entry point, distinguishing it from related tools like 'ask_pipeworx' or 'discover_tools'. The verb 'suggest' and resource 'questions' are well-defined.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides when to omit or pass the 'topic' argument. It also mentions learning meta-tools, giving clear context on when to use this tool vs siblings.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds useful context: heavy bias toward no and output includes a decline template. 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?

Two efficient sentences with no filler. First sentence states purpose; second adds key behavioral and output details. Front-loaded and complete.

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 output schema exists and all parameters are optional, the description adequately covers purpose and output, though it could hint at defaults. Overall sufficient for agents with access to output schema.

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

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

Schema covers all 5 parameters with 100% description coverage. The description does not add new parameter-level meaning but connects parameters to the overall evaluation logic. 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 evaluates meeting worth based on parameters, specifies bias toward no, and lists return values. It is distinct from sibling tools, none of which perform meeting evaluation.

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 purpose is clear, but the description does not explicitly state when not to use the tool or mention alternatives. However, given the unique function among siblings, the context 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 key context beyond annotations: row is deactivated not deleted, preserving history via recent_alerts. Also notes ownership enforcement. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

Two sentences, front-loaded with action and then behavioral detail. 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?

Tool is simple with one parameter and no output schema. Description covers purpose, ownership constraint, and side effects (deactivation). Annotations cover safety. Complete for effective 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%, so baseline is 3. Description adds minimal extra meaning: 'by id' and clarifies it's the subscription id returned by subscribe, which is helpful but not extensive.

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 'Cancel a subscription by id', using specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action is cancellation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. Implicitly suggests when not to use (for others' subscriptions), but does not name alternative tools directly.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description does not contradict them. It adds valuable behavioral detail: verdict taxonomy, the distinction between could_not_verify (check did not happen) and unsupported (no source), citation behavior, and the error payload. This goes well 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 long but every sentence earns its place. It opens with search-like examples, then states the trigger condition, explains the two routing paths, lists the verdict output, and ends with an important caveat and the efficiency benefit. No filler or redundancy.

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

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

Despite no output schema, the description fully explains what the tool returns (verdicts, value with citation, reasoning) and clarifies ambiguous verdict states. It also covers the underlying routing and the error case, making the tool self-sufficient 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 covers both parameters, but the description adds meaningful usage guidance: it explains tolerance_pct overrides the implied tolerance, suggests setting 1–2 for hallucination detection, and clarifies the default (capped at 5). This is exactly the extra semantic value expected.

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 the tool as natural-language claim verification against authoritative sources, with concrete example queries. It distinguishes itself from sibling search/ask tools by stating it replaces a 4-6 step pipeline and returns a verdict, making the purpose unmistakable.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the division of labor: company-financial claims use the SEC EDGAR path, all other claims fall through to a grounded pipeline. This gives clear when-to-use context and implies when not to use (non-claim queries).

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