colorapi

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds value by disclosing the default model, the need for an Anthropic API key, and the cost implication ('you pay Anthropic directly'), which is beyond what annotations provide. It also reveals return structure.

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

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

The description is three sentences, front-loaded with the primary function, followed by model configuration details and use cases. No wasted words; every sentence contributes distinct 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?

The tool has 4 parameters with full schema coverage and no output schema. The description compensates for the missing output schema by describing the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also explains model options and use cases, though it does not cover error scenarios or edge cases.

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 each parameter explained (entity, models, _apiKey, context). The description largely restates what the schema already says, with the additional note about direct payment to Anthropic, but this adds marginal semantic value beyond the schema.

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

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

The description clearly states the tool's action ('Probe one or more LLMs'), the subject ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model LLM visibility scoring rather than general presence scanning.

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

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

The description gives concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention when to prefer this over sibling tools or any exclusions, so it doesn't fully meet the 'when/when-not/alternatives' bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it discloses that the tool routes to 5,358 sources, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier in one fast call. It does not mention rate limits or response format details, but with annotations covering safety, this additional context is strong.

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 most actionable guidance, and every sentence adds value: preferred usage, covered domains, routing behavior, trigger phrases, examples, and escalation paths. It is longer than a pure one-liner but justifiably so given the tool's broad scope and need to differentiate from siblings. Slightly repetitive in listing triggers and examples, but not bloated.

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 broad, complex tool with no output schema, the description is remarkably complete. It covers what queries to send, which tools to prefer over, when to step up to alternatives, what output to expect (structured answer with citation URIs), and gives concrete examples. The schema and annotations are rich, and the description fully compensates for the lack of an output schema by setting expectations for the response.

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% (all parameters are aliases of the single 'question' parameter, and the schema provides descriptions for each). The description reinforces that the tool accepts a natural language question and lists many example queries, which adds practical meaning beyond the schema's dry parameter names. While it doesn't describe aliases (the schema already does), the examples and the statement 'Your question or request in natural language' enrich the parameter semantics.

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

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

The description opens with an explicit directive ('PREFER OVER WEB SEARCH') and a specific verb+resource ('Routes the question to the right one of 5,358 tools... returns the structured answer'). It enumerates the exact domains (SEC filings, FDA data, FRED/BLS, etc.) and clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming when to step up to those alternatives.

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

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

The description gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current', factual questions about real-world entities/events/numbers') and explicit when-not-to-use instructions ('Step up only when needed' for ask_pipeworx_grounded and deep_research). It also states 'this is the default entry point' and even notes breaking-news routing, providing clear alternatives and exclusions.

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 beyond annotations by disclosing the experimental nature (candidate routing improvements), current state (no candidate active, so matches ask_pipeworx), and that results are compared to the stable router to decide merges. This provides meaningful context beyond the readOnly/idempotent hints. No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core purpose, then current state, then usage. Every sentence earns its place, with no fluff 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?

For a beta router that references an established sibling, the description covers the key aspects: what it is, how it differs, current behavior, and usage. It does not need to explain return values since it references the same response shape. A small gap is not explicitly stating when to choose this over the stable version, but overall it is complete enough.

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

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

Schema description coverage is 100% with clear aliases and a description for 'question'. The tool description adds no additional parameter semantics beyond referencing 'same arguments' as ask_pipeworx, so it relies on the schema's already thorough documentation. 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 identifies the tool as a beta version of a universal router with a specific verb+resource: 'identical universal router' routing to 5,358 tools. It distinguishes from siblings by highlighting it is the experimental variant with candidate routing improvements, and mentions the stable ask_pipeworx.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use. It also clarifies it is a full working router, not a fallback, but does not explicitly state when to prefer the stable ask_pipeworx over this beta, leaving the alternative guidance implied.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses the exact return shape, refusal reasons, and the extra LLM call cost. It also clarifies that the answer is extracted only from tool results, adding important behavioral context not present in structured annotations.

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

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

The description is dense yet efficient: it front-loads the core purpose, then covers process, return format, refusal behavior, use cases, and cost tradeoff in a logical flow. Every sentence earns its place 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 lacking an output schema, the description fully specifies success and failure return structures, lists all refusal reasons, and provides clear usage criteria and cost comparison. It is self-sufficient 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?

Schema coverage is 100% (question and aliases are fully described), so the baseline is 3. The description mentions auto-filling arguments but adds no parameter-specific meaning beyond what the schema already provides.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' with a specific process: routing to tools, fetching data, and extracting answers using only tool results. It distinguishes from the sibling 'ask_pipeworx' by focusing on evidence and refusal behavior for high-stakes reads.

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 when-to-use guidance is given ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), naming the alternative tool directly. This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: parallel fan-out, response shapes, resolver confidence levels, parent-event extraction, news fallback handling, low-confidence short-circuiting, closed-market status, wide-spread tradeability, and cancellation-rule risk. This goes far beyond the structured annotations and gives the agent critical operational knowledge.

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

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

The description is long but well-structured with clear uppercase section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) that make it scannable. Every section adds necessary detail for a complex tool with no output schema. It could be slightly condensed, but the density is warranted.

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

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

Given the tool's complexity (3 params, no output schema, many behavioral edge cases), the description is remarkably complete. It comprehensively documents return shapes, resolver confidence, parent-event data, news fallback behavior, safety statuses, and cancellation-rule risk. An agent has enough information to use the tool correctly and interpret results without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining input formats (slug, URL, question text) with examples, elaborating on the 'thorough' fan-out via the FAN-OUT EXAMPLES, and clarifying the impact of 'include_raw' on response size. This supplements the schema without redundancy.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (single bet research with evidence fan-out) from sibling tools like polymarket_edges or polymarket_arbitrage, and explicitly states the use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

The description provides explicit 'Use for' guidance with concrete example queries, and explains the fan-out process and safety short-circuits. It does not explicitly name alternative tools or state when not to use this tool, but the use cases are clear enough to guide an agent. Sibling differentiation is implicit via purpose rather than direct comparison.

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

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

With annotations already declaring readOnly, idempotent, and openWorld safety, the description adds substantial behavioral detail: type='company' pulls specific SEC EDGAR/XBRL fields (10-K revenue, net income, cash, long-term debt) with correct handling of off-calendar fiscal years; type='drug' pulls FAERS, FDA approval, and trial counts; results are sorted by primary metric; output includes paired data and citation URIs. This goes well beyond the annotation baseline.

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

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

The description is dense but well-organized, front-loading trigger phrases and immediately stating the tool's purpose. Every sentence carries meaningful detail (data sources, fiscal-year handling, sorting, citation URIs, efficiency claim). It's longer than ideal but earns its length given the tool's dual-type complexity. Slight reduction in verbiage could improve it, earning a 4 rather than a 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?

The description covers the tool's function, input semantics, data-fetching behavior, output format (paired data + citation URIs), and sorting logic. It also sets expectations about scale (replaces 8–15 lookups). Without an output schema, it doesn't fully specify the response structure but does give enough for an agent to infer. Missing minor details like pagination or error cases, but for its complexity, it's largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains what each type's data sources are (e.g., latest 10-K for company, FAERS/FDA/trials for drug), provides concrete examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"], and clarifies that sorting is by primary metric. This enriches the meaning of both 'type' and 'values' significantly.

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 explicit trigger phrases ("Compare X and Y") and defines the exact action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sibling tools by noting it replaces 8–15 sequential single-pack lookups, clearly positioning it as a batch comparison tool rather than a single-lookup 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?

Explicit guidance is given: "ALWAYS PREFER over sequential single-pack lookups when comparing entities," along with concrete use cases (ranking, head-to-head, which is bigger). However, it doesn't name alternative sibling tools like entity_profile or search_within directly, only refers to them generically as "sequential single-pack lookups," leaving some ambiguity for an AI agent unfamiliar with the sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description additionally discloses that it returns the closest named color and lists output formats, providing behavioral detail beyond the safety annotations. There is 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?

The description is a single sentence that front-loads the core purpose and output. It is concise with no redundant phrasing, achieving high information density.

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 (three integers) and the presence of an output schema, the description adequately covers the tool's behavior. It explains both conversion and color naming, and with annotations and schema, it is complete for effective use.

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

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

The input schema covers 100% of parameters with descriptions for r, g, b (0-255). The description adds no parameter-specific syntax beyond what the schema provides, but the schema itself is sufficient. 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 uses the specific verb 'Convert' with the resource 'color formats' and lists the exact conversions (RGB to hex, HSL, HSV, CMYK) plus a named color output. This clearly distinguishes it from siblings like identify_color, which focuses solely on color naming.

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

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

The description implies its use for color format conversion but does not explicitly state when to use it over siblings like identify_color or provide exclusions. It gives context but lacks explicit alternatives or 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 mark the tool as read-only/open-world/idempotent, and the description adds substantial context: account requirements, a paid plan for thorough depth, the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] and contradictions[] arrays, hop metadata, and latency expectations. There is no contradiction with 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 front-loads the critical auth requirement and packs many distinct, non-redundant behavioral facts. It could be better organized with paragraph breaks or bullets, but every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description fully explains return values (findings packet fields, gaps[], contradictions[], hop, citation_uri) and operational expectations (latency, semantic excerpting, auth). This is complete enough for an agent to correctly select and invoke the tool, even for a tool of this complexity.

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

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

The input schema already describes both parameters with 100% coverage, so the baseline is 3. The description enriches this by noting that depth:'thorough' requires a paid plan and by explaining the behavioral differences between depth values (gap recovery, contradiction scans, added latency), which helps the agent choose the right value.

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

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

The description clearly states the tool's verb and resource: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources in ONE call' and explicitly distinguishes it from open-web search and the sibling ask_pipeworx. It also gives concrete example questions, 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?

The description provides explicit when-to-use and when-not-to-use guidance: it names ask_pipeworx as the alternative for single lookups, breaking/current-news topics, and unsigned-in users. It also explains how depth choices (standard vs. thorough) affect behavior, so an agent can decide between them based on the question's complexity.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description goes beyond by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds valuable context about output and eliminates ambiguity.

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, followed by usage guidance, then return details, and closes with tactical advice. Every sentence adds distinct value, and no filler is present. Length is justified for a discovery tool that needs to convey its expansive scope.

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 compensates by explaining exactly what will be returned (names, descriptions, full schemas, curated examples) and the benefit of being call-ready. It also covers the broad range of supported data domains, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, and the schema already explains the 'query' parameter with aliases and examples. The description says 'by describing the data or task' which aligns with the schema but does not add new parameter-level details. Baseline 3 is appropriate since the schema carries the load.

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 verb and resource: 'Find tools by describing the data or task.' It distinguishes itself from siblings by positioning as a meta-tool for discovery ('Call this FIRST when you have many tools available'), which is unique among the listed sibling tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a when-not condition: 'not just one answer.' It also gives strategic advice to call this tool first when many tools are available, which serves as clear usage 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?

While annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral context: it fans out across multiple sources, returns specific fields, notes the USPTO PatentsView API sunset and soft-fail behavior, and mentions the return structure with URIs and sorted fundamentals. 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 information-dense, using a front-loaded list of example queries and then systematic detail about sources, outputs, and constraints. Every sentence adds value, though it is more verbose than the minimal two-sentence ideal. It earns a 4 rather than a 5 due to its length.

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

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

With no output schema, the description must explain return values, and it does thoroughly: CIK, company_name, recent_filings with URIs, fundamentals (with specific fields and sorting), patents (with soft-fail note), news mentions, and LEI. Combined with annotations and full schema coverage, the description is complete for a complex tool.

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

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

The input schema already provides 100% coverage of both parameters, including the enum for type and detailed descriptions of value (ticker or CIK, names not supported). The description repeats these details but adds no new semantics beyond the schema. Baseline 3 is appropriate per the rubric.

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 a specific verb+resource: 'full cross-source profile of a US public company' in 'ONE parallel call.' It includes concrete example queries ('Tell me about X', 'research Acme') and explicitly distinguishes itself from sibling tools by noting it should be preferred over chaining individual SEC/XBRL/news lookups for holistic requests.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: names are not supported, directing users to 'resolve_entity first if you only have a name.' This fully defines usage vs. alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the mutation and idempotency aspects. The description adds context about clearing sensitive data and stale context, but does not disclose additional behavioral traits such as error handling on non-existent keys. No contradiction with annotations.

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

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

The description is compact, consisting of two sentences. The first sentence front-loads the core purpose, and the second provides usage guidance and tool pairing. Every sentence earns its place with no redundancy or filler.

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

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

For a simple tool with one parameter, no output schema, and robust annotations (destructive, idempotent), the description is complete. It clearly explains what the tool does, when to use it, and how it relates to sibling tools. No critical information is missing.

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

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

Schema description coverage is 100%: the only parameter 'key' is described as 'Memory key to delete' in the schema. The description's 'by key' adds no new meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific action: 'Delete a previously stored memory by key.' This clearly states the tool's function and resource. It also distinguishes itself from siblings by explicitly pairing with 'remember' and 'recall,' making its role as the deletion counterpart unambiguous.

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions related tools via 'Pair with remember and recall,' but does not explicitly state when not to use this tool or name an alternative to choose instead, so it falls short of 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context by explaining the process: fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format, plus noting the output is a single text blob. This goes 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 three sentences, each earning its place: the main action, the process and output, and use cases. It is front-loaded with 'Generate a production-ready llms.txt file' and contains 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?

For a simple read-only tool with complete schema and annotations, the description covers the output format ('single text blob ready to drop at site-root/llms.txt') and usage scenarios. Minor details like error handling on invalid URLs are missing, but they are not critical given the tool's simplicity and annotation coverage.

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

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

The schema covers both parameters (url and max_links) with full descriptions, achieving 100% coverage. The tool description does not add significant parameter-specific detail beyond reinforcing that url is a site URL and mentioning the extraction of key links, but the schema already handles this sufficiently. 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 verb 'Generate' and the resource 'llms.txt file', and specifies the exact output format and purpose. It distinguishes itself from sibling tools like ai_visibility_check by focusing on generating a file for AI crawler indexing.

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 lists three specific use cases: getting a client's site indexed, drafting llms.txt for one's own project, and auditing a competitor's AI visibility. This gives clear context on when to use the tool, though it does not explicitly name alternative tools or exclusions, which prevents 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful behavioral context by specifying that it returns complementary, analogous, triadic, or monochromatic schemes with hex codes. However, the example input with a '#' prefix conflicts with the schema's requirement, slightly undermining clarity.

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 sentence that front-loads the purpose and includes a concrete example. Every word earns its place, with no redundant phrasing or unnecessary details.

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

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

For a simple tool with an output schema and good annotations, the description is mostly adequate. However, the input format mismatch regarding the '#' prefix and the inconsistent mode names create gaps that could lead to incorrect invocations.

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 no extra semantic value and actually introduces conflicting terminology (e.g., 'monochromatic' vs the schema's 'monochrome', and the example '#3498DB' with a '#' even though the schema expects no '#'). This could mislead an agent into providing invalid parameters, warranting a below-baseline score.

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

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

The description clearly states the tool's function with a specific verb ('Generate'), a defined resource ('harmonious color palettes'), and a required input ('seed hex color'). It distinguishes itself from sibling tools like convert_color and identify_color by focusing on palette generation.

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

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

The description implies the tool should be used for generating color schemes, but it provides no explicit guidelines on when to use this tool instead of alternatives such as convert_color or identify_color. No exclusions or alternative references are mentioned.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds transparency by detailing the returned data (color name, RGB/HSL/HSV/CMYK, WCAG contrast ratios), which goes beyond the annotations and helps the agent anticipate the tool's output.

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

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

The description is a single, well-structured sentence that front-loads the tool's purpose and includes a concrete example. Every word adds value, and there is no redundancy or unnecessary detail.

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

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

The tool is simple (one parameter, read-only), and the output schema exists to define return structure. The description covers what the tool does and what it returns, while annotations cover safety and idempotency. The combination leaves no significant gaps for an agent to safely 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?

The schema fully describes the only parameter 'hex' with format and example, achieving 100% schema coverage. The description repeats this information without adding new semantic value, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: identify a color by hex code. It specifies the exact input format and enumerates the outputs (name, RGB/HSL/HSV/CMYK, WCAG contrast ratios), making it distinct from siblings like convert_color.

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

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

The description provides clear context for when to use the tool: when you need to identify a color and obtain its name, color space values, or contrast ratios. It does not explicitly mention alternative tools or exclusions, but the use case is well implied.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds behavior beyond annotations: results are scoped to the caller, only active subscriptions are listed by default, and the exact return fields are enumerated. This is useful contextual information not present in 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?

Two concise sentences: the first states purpose and return fields, the second provides contextual usage guidance. No redundant words or formatting issues.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, scope, output fields, and usage context. The annotations cover safety semantics, making this complete.

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

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

Schema coverage for the only parameter (include_inactive) is 100% with a clear description. The tool description reinforces that active subscriptions are shown by default but does not add new meaning beyond the schema. Baseline 3 is appropriate when schema fully covers parameter semantics.

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

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

The description opens with 'List the caller's active subscriptions' – a specific verb+resource with clear caller scoping. It distinguishes itself from subscribe/unsubscribe siblings by framing it as a review step before adding or canceling.

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

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

Explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly states when to use the tool in relation to subscribe and unsubscribe.

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

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

Annotations are all false and provide no safety hints, so the description carries the burden. It discloses behavioral traits: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also notes that 'signal directly affects roadmap,' giving context about impact. However, it doesn't mention the action's persistence or confirmation behavior, though that may be obvious for a feedback 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?

The description is three sentences: purpose, usage scenarios, and key constraints/behavior. It is front-loaded with the main action and every sentence contributes actionable information. No fluff 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?

For a 3-parameter tool with no output schema, the description covers purpose, when to use, message formatting, rate limits, and cost. It fully addresses the task without needing to explain return values. The nested context object is optional and not critical to describe further.

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 baseline is 3. The description adds value by elaborating on the 'type' enum ('bug', 'feature/data_gap', 'praise') and by guiding message composition ('Describe the issue in terms of Pipeworx tools/packs'). This provides semantic depth beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific categories (bug, feature/data_gap, praise) and distinguishes it from sibling research/data tools by framing it as a feedback submission mechanism. The verb 'Tell' and resource 'Pipeworx team' are unambiguous.

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

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

The description explicitly provides when-to-use scenarios: '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 a negative instruction: 'don't paste the end-user's prompt,' which further clarifies appropriate usage. This goes beyond simple intent and gives actionable triggers.

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 this is a safe, read-only, idempotent operation. The description adds valuable context beyond that: data originates from CF analytics-engine, contains no PII, exposes only (pack, tool, count), and is cached for 5 minutes to 1 hour depending on the window. This gives the agent a good sense of freshness and privacy characteristics without overloading the description.

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 outputs, followed by use cases and a transparency note. It is slightly longer than minimal due to the three-item 'Useful for' list, but each item conveys unique guidance, and the overall structure makes it easy to scan. A minor trim could make it even tighter, but it earns its length.

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

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

This is a simple, read-only tool with one optional parameter and no output schema. The description adequately covers return value shape ('top tools, top packs, call volume', 'just (pack, tool, count)'), use cases, caching, and privacy. It could be more explicit about exact response formatting, but for a trend-reporting tool the essentials are present.

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

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

The single window parameter is fully described in the schema with enum values, a default, and semantic guidance about shorter vs longer windows. The tool description merely lists '24h, 7d, or 30d' without adding interpretive detail beyond what the schema already provides. With 100% schema coverage, 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 opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It then lists concrete outputs—top tools, top packs, and total call volume—making the tool's scope and value immediately obvious. This also differentiates it from siblings like discover_tools by focusing on cross-agent aggregate trends rather than direct tool discovery.

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

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

The description provides explicit use cases with the 'Useful for' list, covering discovery, validation, and alignment checks. This gives clear context for when to invoke the tool. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a perfect 5.

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

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

Discloses many non-obvious behaviors beyond annotations: semantic similarity threshold (Jaccard ≥0.30), partition placeholder filter (>20% returns null), fill-check logic (realizable_edge_pp ≤ 0 means do not trade), and response structure. Provides deep visibility into internal decision rules.

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?

Although long, it is structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence provides distinct, actionable information without redundancy.

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

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

With no output schema, the description compensates by detailing the response fields (opportunities[], partition_check, gap_pp, suggested_trade). It also covers filters, edge cases, and references to sibling tools for related needs. Comprehensive for a complex tool.

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

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

Schema coverage is 100% and both parameters already have strong descriptions. The tool description adds extra value with concrete slug examples, mode recommendations, and behavioral hints (e.g., topic catches cross-event patterns). Useful but not groundbreaking.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the exact detection methods and 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 describes three usage modes: no args for trending_scan, event for per-event partition checks, and topic for cross-event scanning. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' Clear when-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?

Even with strong annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral disclosure: the three-segment response structure, Kelly cap at 0.25, slippage handling, the 24h-move warning, placeholder-slug filtering, per-sport bias correction constants, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). This goes far beyond what annotations provide and gives agents a thorough mental model of the tool's behavior.

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 extremely information-dense and well-structured, with clear sections (model families, response structure, knobs, caching). It is front-loaded with the core purpose. While every sentence adds value, the sheer length (near 400 words) could be slightly overwhelming; a bit of tightening would push it to 5. Nevertheless, the organization makes it easy to scan.

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 (9 parameters, three segments, nested response fields), the description is remarkably complete. It explains the output structure including _diagnostics, why segments may be empty, the Fed bet exclusion rationale, and even the internal logic of the concentrated_longshot gate relaxation. No output schema is needed because the description effectively documents the return shape.

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 meaning well beyond the schema. For example, min_partition_leg_kelly explains that partition arbs always return kelly_fraction_half=0 at the parent level and how this knob applies per-leg instead. slippage_pp details why 0.3 is the default and when to adjust it. min_liquidity clarifies that for partition_overround it applies to 'at least one top_leg.' The description enriches every parameter with context that helps an agent choose appropriate 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on the 'what should I bet on today' use case and mentioning it avoids paging hundreds of markets.

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 context for when to use the tool ('Built for "what should I bet on today"') and gives concrete guidance on knob usage (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also notes that Fed bets are excluded from ranking due to unreliable signal, adding usage nuance. However, it does not directly name alternative sibling tools for comparison, so it misses the explicit 'when not to use' aspect.

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 substantial behavioral detail beyond annotations: history limited by 60-day snapshot TTL, snapshots written only on cache-miss causing gaps, decay computed on daily closes rather than intraday, and the meaning of expired opportunities. These are all non-obvious behaviors that help an agent understand limitations.

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 clearly structured into purpose, args, response, and limits sections. Every sentence carries useful information, but it is verbose and could be tightened without losing substance.

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 comprehensively explains the return format (tracked[], expired[], snapshot_dates[]) including field-level detail and edge cases. It also covers data gaps, TTL limits, and computation basis, making it fully self-contained.

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 documents both parameters. The description adds a bit of extra context ('snapshot family', 'lookback') but doesn't materially go beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge listing.

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

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

Provides clear context for when to use the tool: to answer 'how long has this edge existed and is it shrinking?' and explains why that matters (fresh vs. old wide edges are different trades). It doesn't explicitly name alternative sibling tools, but the context is strong enough for an agent to infer 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?

Even with annotations already marking the tool as read-only and idempotent, the description adds significant behavioral context beyond them: it walks the ladder, returns top_of_book/vwap/slippage, can result in partial fills, and warns that partial basket fills convert an arb into an unhedged directional position. It also explains that size_usd means different things for buys vs sells and basket mode. This richly discloses behavior and risk.

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

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

The description is long but well-structured with clear 'SINGLE-MARKET:' and 'BASKET:' sections, front-loading the core purpose and requirements. Every sentence is informative and not redundant, though it does restate some schema-level parameter details, making it slightly longer than strictly necessary. Still, given the tool's complexity, it earns a 4.

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

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

The description is remarkably complete given the tool's complexity and lack of an output schema. It not only lists return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, thin_legs, etc.) but also explains their meaning in context (e.g., forced_directional_risk names legs likely to strand the user unhedged). It covers usage timing, failure modes, and the dominant loss mode, leaving no major gaps.

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

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

Schema coverage is 100% and each parameter has a detailed description. The tool description adds the critical constraint that exactly one of `market` or `event` is required (not present in schema), and clarifies how `side` and `size_usd` vary by mode. This goes beyond the schema, though the schema already carries much of the load, so a 4 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk, and it enumerates two distinct modes (single-market and basket) with precise output metrics.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides a rationale (theoretical overround on thin books is not capturable) and clarifies prerequisites (REQUIRES one of market or event), offering strong guidance versus alternatives.

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

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

Even though annotations already mark this as read-only and idempotent, the description adds rich behavioral context: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype meaning, and the caveat that spreads may be meaningless. It fully explains what the tool does under unexpected conditions.

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 structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence adds operational detail. It is dense rather than concise, but given the tool's complexity, the length is justified and well-organized.

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

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

With no output schema, the description fully describes response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and covers failure modes. It is exceptionally complete for a 3-param tool with no required parameters.

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

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

Schema already provides 100% coverage with descriptions and examples, but the description adds valuable operational semantics: topic auto-fetches matching events, explicit parameters override the topic-mapped side, and the interaction between modes. This goes beyond the schema.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the tool's function and resource. It distinguishes itself from siblings by focusing on the Kalshi–Polymarket pair and explicitly discusses when the spread is a 'real signal' vs. when bet shapes differ.

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 details two modes (topic shortcuts vs. explicit ticker/slug pairings) and when each is appropriate, and warns that 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' However, it does not name alternative tools like polymarket_arbitrage for cases where this tool is unsuitable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context beyond annotations: scoping to identifier (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (retrieve/list). No contradiction.

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

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

Three sentences, each with a distinct purpose: operation, use case, and scoping/pairing. 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?

Given the tool's simplicity (one optional parameter, no output schema, annotations present), the description covers operation, use case, scoping, and sibling relationships. It is complete enough for correct invocation.

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

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

Schema description coverage is 100% for the single parameter 'key', which already states 'Memory key to retrieve (omit to list all keys).' The description echoes this but does not add new parameter semantics beyond the schema.

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

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

The description uses specific verbs and resources: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes from sibling tools by naming remember and forget as counterparts.

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 when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also mentions alternatives: 'Pair with remember to save, forget to delete.'

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 a state-changing operation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the readOnlyHint=true annotation, which implies no side effects. This is an annotation 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 compact and front-loaded, with four sentences each serving a purpose: explaining the core action, listing returned fields, describing filtering options, and covering polling behavior and an alternative endpoint. 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?

Despite lacking an output schema, the description explicitly mentions the return fields (source, citation_uri, raw payload), covers polling suitability, and cross-references an external endpoint. Combined with the fully described schema parameters, an agent has all necessary information for correct invocation.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying the since format as ISO timestamp, and explaining mark_read's effect on subsequent calls.

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 'Pull fired events from your subscription feed,' giving a specific verb and resource. It clearly distinguishes the tool from siblings like list_subscriptions and recent_changes by focusing on alert events.

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

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

The description explains when to use the tool (for polling alerts) and mentions filters, mark_read behavior, and an alternative REST endpoint. However, it does not explicitly name alternative tools or provide exclusionary '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?

Discloses rich behavioral detail beyond the readOnly/idempotent annotations: fans out to SEC EDGAR, GDELT→GNews fallback behavior, USPTO soft-fail due to PatentsView API sunset, and the exact return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is substantial added 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 front-loaded with user-intent phrases, then efficiently packs essential details—sources, fallbacks, date formats, return shape, and alternative tool—into a dense but well-organized paragraph. Every sentence earns its place; 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?

Given the tool's complexity (multi-source, fallback logic, date parsing, output schema absent), the description covers all critical aspects: source APIs, fallback strategy, error/soft-fail behavior, return format, and an explicit alternative. An agent can confidently decide to invoke this tool and know what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete date format examples ('7d', '30d', '3m', '1y') and a recommended default for typical monitoring, helping agents choose appropriate `since` values. It doesn't add much for `type`/`value` beyond the schema, but the extra usage guidance 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 defines the tool as a change feed for a company over a time window, with explicit examples ('What's new with X') and a concrete verb phrase. It distinguishes itself from siblings by explicitly naming entity_profile as the alternative for static profiles, 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?

Provides explicit when-to-use guidance via NLP-style examples, and directly states 'Use entity_profile instead when you want the static profile... regardless of window.' It also offers practical parameter advice ('Use "30d" or "1m" for typical monitoring'), going beyond a vague 'when needed'.

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

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

Beyond annotations, the description adds context about key-value scoping by identifier and retention policies (persistent for authenticated users, 24 hours for anonymous). It does not contradict the idempotentHint, and while it doesn't mention overwrite semantics, the idempotent hint covers that. The added details are meaningful.

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 primary action, followed by use cases and storage details. Every sentence adds value, and it is concise enough for quick comprehension without being terse.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, when to use, key-value format, scoping, persistence, and relationships with siblings. It is complete for 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 baseline is 3. The description mentions 'key-value pair' but does not add significant detail beyond the schema's field descriptions. It doesn't explain value length limits or special encoding, so it stays at the baseline.

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

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

The description clearly states the action ('Save data') and the resource ('data the agent will need to reuse later'), with concrete examples. It distinguishes itself from sibling tools by explicitly mentioning recall and forget as paired operations.

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 when' scenarios (discovering a resolved ticker, target address, user preference, research subject) and names alternatives ('Pair with recall to retrieve later, forget to delete'). This is clear guidance on when to use vs. alternatives.

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

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

Beyond annotations (read-only, idempotent), the description discloses that each call 'cascades through several lookup endpoints internally,' that company input is 'auto-disambiguated,' and that results include citation URIs. This adds meaningful context about internal behavior and output structure without contradicting annotations.

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

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

The description is well-structured: example queries first, then when-to-use, then per-type breakdown. It is information-dense yet every sentence adds value, with no redundancy or fluff.

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

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

With no output schema, the description fully explains return values for both entity types (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and includes citation URIs. It also describes input flexibility and internal cascading, making it 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?

Schema coverage is 100%, with detailed descriptions of both parameters. The description adds semantic nuance by explaining the auto-disambiguation behavior for company input and providing concrete value examples (AAPL, 0000320193, ozempic), going slightly beyond the schema.

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

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

The description uses a specific verb 'resolve' with a clear resource ('user-spoken NAME to the canonical/official identifier') and provides concrete example queries (ticker, CIK, RxCUI). It lists supported types (company, drug) with distinct return values, distinguishing it from siblings like entity_profile or compare_entities.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' giving clear priority guidance. It also notes that each call replaces 2-3 manual lookups, implying efficiency. However, it does not mention when NOT to use the tool or name specific alternatives, so it stops short of 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?

The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already cover safety, and the description adds behavioral detail: it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. It also discloses that it calls ai_visibility_check internally. No contradictions with annotations. Could give more detail on rate limits or API key handling, but the essential behavior is transparent.

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

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

The description is three sentences, front-loaded with the core purpose, followed by an illustrative example and a concise return summary. Every sentence earns its place with no redundant or filler content.

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

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

For a tool with no output schema, the description sufficiently explains the return format (ranked list with score, confidence, signal density). It also handles parameter nuance (models, _apiKey) via the schema. It could be more explicit about sorting direction or edge cases, but given the moderate complexity and rich annotations, it is reasonably complete.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters. The description reinforces the meaning of 'entities' (your brand + competitors) and the purpose of 'context' (shared disambiguation), but adds little new semantic value beyond what the schema already states. 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's purpose: 'Compare AI visibility across multiple entities side-by-side.' It identifies the specific verb ('compare') and resource ('AI visibility'), and distinguishes it from sibling tools like ai_visibility_check (single-entity check) by explicitly mentioning it probes multiple entities and ranks them. The example use case ('does Claude know about us as well as our competitors?') further clarifies intent.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits.' It also implies an alternative by referencing ai_visibility_check for probing individual entities. However, it does not explicitly state when NOT to use it or name alternative tools like compare_entities, though the distinction is implied.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: composite fan-out, graceful degradation of partial failures, bundlephobia's first measurement delay (5-30s), and the sources_failed field. 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 dense yet compact, front-loading the core purpose and then providing use cases, output fields, and limitations in a logical order. Every sentence carries useful information without redundancy.

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

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

Despite no output schema, the description enumerates the exact summary fields returned (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), plus per-advisory detail and alternative versions. It covers ecosystem scope, performance caveats, and failure behavior, making it complete for a composite tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning: scoped packages are accepted ('@types/node') and version defaults to latest when omitted. It also clarifies the npm-only ecosystem constraint, which is not fully captured by the generic 'npm package name' schema description.

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

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

The description opens with a specific composite check: 'should I add this npm package to my project' in one call, then names the fan-out sources (deps.dev, bundlephobia). This clearly identifies the tool's verb, resource, and scope, distinguishing it from all sibling tools.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. No ambiguity about when to invoke this tool.

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

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

The description goes well beyond the annotations by disclosing the algorithm (BGE-base-en embeddings + cosine), the windowing approach (500-char overlapping windows), the input cap (200K chars with truncation and flagging), and the output characteristics (passages with character offsets and similarity scores). This significantly enriches the agent's understanding of how the tool behaves.

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?

Every sentence in the description earns its place. The first sentence states the core function, the second gives the use case and benefit, the third provides a pairing with an alternative tool, and the fourth discloses technical constraints. There is no redundancy or filler; the description is dense but appropriately sized.

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 adequately covers the return format by mentioning 'top-N passages with character offsets and similarity scores.' It also covers limitations (200K cap, truncation) and the intended workflow. The tool is simple enough, and the description gives all necessary context for an agent to understand its capabilities and boundaries.

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 baseline is 3. The description adds meaningful context beyond the schema: it clarifies that 'text' should be a fetched record, explains the 200K character cap and truncation behavior, and reinforces the query as a natural-language question. These additions give a better sense of how to use each parameter effectively.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination. It immediately distinguishes itself from siblings by emphasizing that the text is already fetched and the search is conducted within that text, returning passages with offsets and scores. It even names the complementary tool ask_pipeworx_grounded, making the differentiation explicit.

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 'Use when' condition: 'when the record is too big to cram into the prompt.' It also supplies a clear alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both a positive trigger and a contrast with an existing tool.

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

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

The description goes well beyond annotations. It discloses account requirements (anonymous + BYO cannot persist), delivery channel specifics, SMS verification and cap, webhook HMAC signing and one-time secret, and auto-disable after 10 consecutive failures. This adds substantial behavioral context beyond readOnlyHint=false and 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?

The description is dense but front-loaded with the purpose and return. Every sentence carries necessary detail (types, delivery, constraints). It is relatively long but justified by the complexity of the tool. Slightly verbose, but not wasteful.

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

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

Given the complexity (nested params, multiple delivery channels, no output schema), the description is thorough. It covers account prerequisites, return value, subscription types with examples, delivery options with limits, and security details. It is effectively complete for the agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters by giving concrete examples (e.g., items:["5.02"] = officer change, params:{topic:"fed"}, series_id:"UNRATE") and clarifies return behavior ('Returns the new subscription id'), which is not in the schema. This adds meaningful value beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This names the resource (subscription) and the specific action (create), and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 context for when to use it: creating a monitoring subscription, with supported types like sec_8k, polymarket_edge, and fred_series. It also imposes a prerequisite ('Requires a Pipeworx OAuth account') and chain constraints (phone must be verified, 10/day cap). It does not explicitly contrast with alternatives like list_subscriptions or unsubscribe, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond this: it explains the response is 'category-bucketed example questions' drawn from the live catalog, and that each includes the exact tool and argument shape. It also notes the `topic` parameter's focusing effect.

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 thoughtfully front-loaded with natural user phrasings like 'What can I ask Pipeworx?' and 'give me ideas', then moves into a dense but well-structured explanation of behavior and use. Every sentence carries load, though the length is at the higher end; it earns a 4 rather than 5 due to slight redundancy in the category list.

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 simple one-optional-parameter schema and rich annotations, the description covers all necessary context: what the tool returns, how it can be scoped, when to use it, and how it relates to other meta-tools. Even without an output schema, the description sufficiently describes the return format and content.

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

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

The input schema already covers the only parameter (`topic`) with a description and allowed values, so schema coverage is 100%. The description adds illustrative examples ('finance', 'pharma', 'betting') and explains that omitting `topic` gives a cross-category spread, but this goes only slightly beyond the schema's own explanation.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses a specific verb ('suggest') and resource ('what to ask Pipeworx'), and it distinguishes itself from siblings by explicitly positioning it as 'Use this FIRST' and by detailing the unique output (category-bucketed questions with tool+argument mappings).

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also hints at alternatives by naming meta-tools like ask_pipeworx, entity_profile, and compare_entities, but it does not explicitly contrast with sibling tools such as discover_tools, so a small gap remains.

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 context beyond annotations: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This aligns with the idempotent and destructive hints while giving richer operational understanding.

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

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

Two sentences, front-loaded with the action, and every sentence provides essential behavioral or contextual information. No wasted words.

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

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

Given the single parameter, good annotation coverage, and absence of output schema, the description fully covers what the tool does, its constraints, and the post-effect. It is self-sufficient for an agent to use correctly.

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

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

The schema already fully documents the single parameter (id as a uuid returned by subscribe) with 100% coverage. The description adds no further parameter-specific semantics beyond 'by id', so it meets the baseline for high schema coverage.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from sibling tools like subscribe and list_subscriptions. The action is unambiguous.

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

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

Provides clear context about ownership enforcement and the soft-delete behavior, and references recent_alerts for historical events. However, it does not explicitly name alternatives or state when not to use it, just implies the context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail: the two verification paths (structured financial vs. grounded), the verdict categories returned, the inclusion of citations and reasoning, and the claim that it replaces 4–6 sequential calls. No contradiction with annotations.

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

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

The description is long but well-structured, opening with example user phrasings to aid intent recognition, then stating the use case, routing paths, and output. Every part serves a purpose, though the 'Replaces 4–6 sequential calls' claim is slightly tangential. It is dense but not wasteful.

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 fully enumerates the possible verdict values (confirmed, approximately_correct, refuted, inconclusive, unsupported) and the output structure (value, citation, reasoning). It also covers the two major claim categories and how they are handled, making the tool's behavior fully specified 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?

The input schema provides 100% parameter coverage with detailed descriptions for both 'claim' and 'tolerance_pct', including an example and the default tolerance behavior. The description does not add substantial parameter-level meaning beyond what the schema already states, so the baseline score of 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 explicitly identifies the tool as 'natural-language claim verification against authoritative sources' and provides concrete example intents ('fact check', 'verify the claim that…', 'confirm or refute'). It clearly distinguishes this from general Q&A/research siblings by focusing on returning a verdict on factual correctness.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear activation condition. It also explains the routing logic for two claim types (SEC EDGAR vs. grounded pipeline). However, it does not explicitly mention when not to use it or name alternative sibling tools for non-claim tasks.

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