ipinfo

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by disclosing that Workers AI Llama-3.3-70b is the free default, that using Anthropic requires a BYO key and direct payment, and that the return includes per-model score/confidence/signals/raw_response plus a combined view. This adds meaningful operational and cost context with no contradictions.

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

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

Four sentences, all information-dense: purpose, default model/cost, return format, and use cases. No filler or repetition. Front-loaded with the primary action and output.

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

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

The tool has moderate complexity (4 params, one required) and no output schema, but the description provides the return structure clearly and covers key operational details (model selection, API key, disambiguation via context). The tool is fully understandable without needing additional documentation.

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 each parameter (entity, models, _apiKey, context). The description adds marginal value by noting that '_apiKey' is passed straight through to api.anthropic.com and that models are optional, but it does not substantially enrich parameter understanding beyond the schema 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 opens with a specific verb ('Probe') and clearly defines the resource (LLMs), the action (score visibility 0-100), and the scope (business/brand/product/topic). It also adds model default and optional Anthropic, which distinguishes it from siblings like ask_pipeworx (direct Q&A) and scan_competitor_ai_presence (competitor-focused).

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to use the tool, though it does not explicitly name alternative tools or exclusion criteria. Still, the guidance is enough to help an agent decide.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds value by explaining the routing behavior, auto-filling of arguments, citation URIs, and the fact it works on every tier. It also discloses its handling of breaking news via live news feeds. This goes beyond the structured annotation fields.

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 the description is long, every sentence earns its place. It front-loads the primary directive ('PREFER OVER WEB SEARCH'), then explains mechanics, gives usage triggers, provides examples, and ends with an escalation path. There is no redundancy or filler; the structure is logical and 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?

The description covers use cases, alternatives, examples, and a high-level description of the return format (structured answer with citation URIs). Given the tool's broad scope and the absence of an output schema, it provides sufficient context for an agent to select and invoke it, though the exact structure of the returned answer is not detailed.

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

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

The schema already has 100% coverage with descriptions for 'question' and its aliases. The description adds value by providing concrete examples of well-formed questions ('current US unemployment rate', 'Apple's latest 10-K') and guidance on when to phrase queries as natural-language requests, which helps the agent craft effective input.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1,455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings by explicitly saying 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' making it the default entry point.

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: 'PREFER OVER WEB SEARCH for questions about current or historical data...' and lists example trigger phrases like 'what is', 'look up', 'find'. It also names alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'.

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

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

Goes beyond annotations by disclosing the beta nature, current state ('No candidate is active right now'), the date of last retirement, and that it falls back to nothing as a full working router. This adds significant behavioral context 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 a dense paragraph with each sentence contributing a distinct point (identity, current status, usage, and non-fallback assurance). It could be tightened, but there is minimal redundancy, and key information is front-loaded in the first sentence.

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

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

Covers beta status, current behavior, usage, and experimental context well. However, with no output schema, it only says 'same response shape' without detailing what the response contains, which is a minor gap for a tool without a schema.

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

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

The input schema already covers all six parameters with 100% description coverage (all aliases for 'question'). The description only repeats 'same arguments' without adding extra semantics, so it meets the baseline but does not enhance parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, with specific details (same 5,529 tools, same arguments, same response shape). It distinguishes from the sibling ask_pipeworx by emphasizing the experimental routing improvements, making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides context by mentioning comparison against the stable router and the current inactive status, which implies the alternative is the stable ask_pipeworx. This is 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?

Discloses beyond annotations: the grounded extraction mechanism, explicit refusal reasons (not_in_source, no_tool_match, etc.), return format with evidence and confidence, and the cost overhead (extra LLM call). This adds substantial context that readOnlyHint/idempotentHint alone do not provide.

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

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

The description is dense but well-organized: it opens with the core purpose, explains the mechanism, gives output/refusal contract, then usage guidance and trade-off. Each sentence adds value, no fluff. It is front-loaded with the most important distinction from ask_pipeworx.

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

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

Despite no output schema, the description fully specifies the return payload and refusal reasons. It covers when and why to use, the internal routing, and the extra cost. This is complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for 'question'. The description does not add parameter-specific meaning beyond this, but the baseline is 3 because the schema already fully explains parameters.

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 this as a 'Hallucination-resistant answer mode for high-stakes reads' and distinct from sibling 'ask_pipeworx' by adding grounded extraction with evidence. It specifies the resource (Pipeworx), the action (ask), and the key behavior (extract from tool result only).

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on... must not invent facts.' Provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This fully distinguishes from sibling tools.

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

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

Annotations already declare readOnly/openWorld/idempotent safe behavior; the description adds substantial operational detail: parallel fan-out to source-specific data packs, a resolver contract with match confidence and alternatives, parent-event extraction, GDELT/GNews fallback fields, wide-spread illiquidity warnings, and cancellation-rule parsing (e.g., refund_50_50). It even quantifies risk ('flat-50¢ void settlements are a recurring pure-rules loss'). This far exceeds the annotations and is exemplary.

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 deliberately organized with uppercase labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). It front-loads the core purpose and then layers edge cases without filler. Every sentence contributes operational value, and the structure makes scanning easy.

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 so comprehensively: result.market fields, result.analysis with edge warnings, result.evidence keying, resolver match_confidence/score/alternatives, parent_event extraction, news fallback fields, and blocking closed-market/low-confidence paths. For a tool with this complexity, the description is fully complete.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents `market`, `depth`, and `include_raw` (including defaults and rationale). The description's fan-out examples and response shapes provide context but do not add new parameter-level meaning beyond the schema. The baseline of 3 applies because 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 first sentence states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes the tool from generic research siblings by scoping it to Polymarket bets with one-call data aggregation. The 'Use for' sentence further reinforces the exact scenarios ('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 triggers for when to use the tool and includes detailed exception paths (closed markets, low-confidence matches, wide-spread illiquidity). However, it does not explicitly name alternative sibling tools to contrast with (e.g., ask_pipeworx, polymarket_edges), so it falls just short of a 5. The guidance is clear context without formal 'when-not-to-use' 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?

Despite comprehensive annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantive behavioral context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), explains handling of off-calendar fiscal years, states sorting by primary metric, and mentions citation URIs. This goes well beyond annotation hints and gives the agent a clear model of what the tool does under the hood.

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 every sentence earns its place. It front-loads trigger phrases and key action, then systematically covers data sources, parameter specifics, sorting behavior, and return value. While long, there is no fluff or repetition; it is efficiently structured for an AI agent to parse and act on.

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

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

Given the tool's complexity, the description is remarkably complete. It covers purpose, usage, data source provenance, edge-case handling (fiscal calendars), output ordering, and result format (paired data + citation URIs). No output schema exists, but the description sufficiently describes the return value. There are no major missing pieces for an agent to correctly use this tool.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. It explains what 'company' pulls (latest 10-K metrics) and what 'drug' pulls (FAERS counts, approvals, trials), provides concrete examples for the values array, and describes how results are ordered. This is far more informative than the schema's bare descriptions.

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

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

The description starts with specific trigger phrases and states the core function: side-by-side comparison of 2–5 companies or drugs in ONE parallel call. It clearly distinguishes itself from siblings by emphasizing it replaces sequential single-pack lookups, and it specifies the supported entity types (company vs drug).

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 with natural language trigger examples and an explicit preference statement: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates by entity type, explaining what data each type pulls, so an agent knows exactly when to invoke this versus a single-entity 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?

It adds rich behavioral detail beyond the annotations: account/payment requirements, the returned findings packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[]), the second-hop strategy for depth tiers, contradictions[] behavior, semantic excerpting, and expected latency (15-60s, up to ~90s for thorough). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false); the description reinforces and expands.

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

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

The description is dense and front-loaded with account requirements, but it is quite long. Every sentence provides unique, valuable information—timing, alternatives, output details, depth behavior—yet the wall-of-text format could be better structured (e.g., bullets). It is appropriately sized given the tool's complexity, but not maximally concise.

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

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

With no output schema, the description fully explains the return format, including the findings packet, gaps[], contradictions[], hop field, and citation_uri behavior. It also covers prerequisites (account), timing, and limitations (structured-source-only, no open-web/current news), making it a complete operational guide for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining depth options in operational terms: 'quick=3 (single hop), standard=5 (default; adds a gap-recovery hop...), thorough=8 (paid; adds a full iterative hop...)' and clarifies that thorough requires a paid plan. It also provides examples for the question parameter, exceeding what the schema alone 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 states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explains that it 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL.' It explicitly differentiates from sibling tools by instructing when to use ask_pipeworx instead, 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 gives explicit usage guidance: 'Best for broad/multi-part questions over structured data' with examples, and clearly states when NOT to use it: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also mentions the account required and the fallback if not signed in, covering both when and when-not scenarios.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context by explaining the return payload: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and helps the agent understand what to expect from the 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 well-organized: the first sentence states the core purpose, followed by usage context, return value, and invocation priority. The list of domains is lengthy but each item adds value by illustrating the tool's scope. Overall, it is efficient and front-loaded, with no redundant 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?

Even without an output schema, the description clearly explains what the tool returns (top-N tools with descriptions and schemas) and that results are directly callable. It also situates the tool in a workflow ('Call this FIRST'). For a simple discovery tool with well-documented parameters, this is sufficiently complete. It doesn't discuss errors or pagination, but these are not critical for the tool's primary purpose.

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

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

The schema description coverage is 100%, so every parameter (query, q, task, limit, search, description) already has a clear description and aliases. The tool description's only reference to parameters is 'describing the data or task,' which adds no new semantic detail beyond the schema. Therefore, the baseline of 3 for high coverage 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 'Find tools by describing the data or task,' which clearly states a specific action and resource. It goes beyond a simple definition by listing concrete domains (SEC filings, FDA drugs, etc.), and the phrase 'discover what tools exist' sets it apart from sibling tools that perform specific tasks. This unmistakably identifies it as a meta-discovery tool.

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

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

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This tells the agent when to choose this tool over directly invoking a specific sibling, and suggests it as a preliminary step. While it doesn't explicitly state when not to use it, the 'not just one answer' qualifier implies it's not for cases where a specific tool is already known.

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 declare readOnlyHint and idempotentHint, the description adds significant behavioral context: it explains the parallel fan-out across multiple APIs, the limitations ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), the GDELT→GNews fallback chain, and exactly which fundamentals are returned ('LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'). This goes well beyond the 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 and information-packed, front-loading with user intents and then systematically covering sources, return fields, and usage constraints. While it is long, every clause earns its place given the tool's many integrations. A more structured bullet list could improve scanability, but the prose is efficient.

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

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

With no output schema, the description compensates by enumerating all return fields (cik, company_name, recent_filings with URIs, fundamentals fields, patents, news mentions, LEI). It also covers edge cases like unsupported names and the patents soft-fail, and explains when to prefer this tool over alternatives. This is a fully self-contained explanation.

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 documents both parameters with 100% coverage, including the enum restriction on type and the ticker/CIK format for value. The description reinforces this with concrete examples ('AAPL', '0000320193') and clarifies zero-padding and the name limitation, adding practical value 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 concrete user phrasings ('Tell me about X', 'research Acme', 'brief me on Tesla') and then explicitly states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It lists the data sources and return fields (CIK, filings, fundamentals, patents, news, LEI), making the resource and action unmistakable. It also distinguishes itself from siblings like compare_entities and resolve_entity.

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 direct usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent when not to use it for names: 'names not supported (use resolve_entity first if you only have a name).' This explicitly names an alternative tool, satisfying the when/when-not criteria.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the core safety profile is known. The description adds usage scenarios but no additional behavioral details like side effects or persistence guarantees.

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 verb and resource, no filler. Every clause contributes purpose, usage, or sibling context.

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 single-parameter destructive tool with comprehensive annotations, the description is complete. It covers purpose, when-to-use, and relationship to related tools without needing to explain return values (no output schema).

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

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

Schema coverage is 100% with 'Memory key to delete' for the key parameter. The description's mention of 'by key' merely echoes the schema and adds no new semantic information.

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 'Delete a previously stored memory by key,' using a specific verb and resource. It clearly distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also names alternatives: 'Pair with remember and recall.'

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 that the tool fetches a page, extracts metadata, and outputs a text blob, adding behavioral detail beyond the readOnlyHint and idempotentHint annotations. It does not cover edge cases like invalid URLs or rate limits, but given the tool's simplicity and existing annotations, this is sufficient.

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

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

The description is two well-structured sentences plus a concise use-case list. It front-loads the core purpose and process, but the list slightly extends length without breaking clarity. Every sentence earns its place, though a slightly tighter list could improve conciseness.

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

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

For a tool with only two parameters and no output schema, the description covers the action, process, output format, and common use cases. It lacks details like error behavior or return value specifics, but these are not critical given the simple output (single text blob) and the schema already documenting input limits.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' clearly defined in the input schema. The description adds no extra parameter specifics, but the baseline of 3 applies since the schema already handles parameter semantics fully.

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 generates a production-ready llms.txt file for any URL, with specific detail on the process (fetches, extracts title/description/key links, emits markdown) and the intended output. It differentiates from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis or 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 provides explicit use cases: getting a client's site indexed, drafting for your own project, or auditing a competitor. However, it does not explicitly mention when not to use it or point to alternative sibling tools for related but different tasks, so the guidance stops short of full 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the return field list, which is useful but more about output than behavioral context like side effects or requirements. There is 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 a single, direct sentence front-loading the purpose and listing key return fields. Every word earns its place with no fluff or redundancy.

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

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

This is a simple, zero-parameter tool with comprehensive annotations and an output schema. The description fully captures the tool's purpose and the nature of the returned data, making it 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 tool has zero parameters, so the schema is fully complete and there is no need for parameter explanations. The description appropriately focuses on the return data instead.

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

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

The description clearly states the tool retrieves the caller's current IP address with geolocation data. It distinguishes itself from the sibling tool 'lookup_ip' by specifying 'my' (current IP), leaving no ambiguity about its 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?

The description implies usage for obtaining one's own IP address but does not explicitly state when to use this over alternatives like 'lookup_ip', nor does it mention exclusion criteria. This is a case of implied usage rather than clear 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the scoping to the caller's active subscriptions. It does not mention pagination or error handling, but for a simple list tool this is adequate.

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 composed of three short sentences that are direct and free of fluff. It front-loads the main action, then provides return fields and usage guidance, each sentence earning its place.

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

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

For a simple, read-only tool with one optional parameter and no output schema, the description is nearly complete. It covers the return values and provides usage context. However, it does not tie the description to the include_inactive parameter (leaving that to the schema), and it omits any caveats about subscription types or pagination, which could be relevant.

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

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

The only parameter, include_inactive, is fully described in the schema (default false, includes cancelled subscriptions). The description text does not add any additional meaning or mention the parameter, so it relies entirely on the schema, which has 100% 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 'List the caller's active subscriptions', specifying the action (list), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools like subscribe and unsubscribe, which modify subscriptions rather than list them.

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

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

The description provides concrete use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to invoke the tool in relation to subscribing/unsubscribing, though it does not explicitly name the alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds value by specifying the types of data returned and the 'any IP' scope. No hidden or unexpected behavior is disclosed, but none is present given 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?

One sentence that front-loads the purpose, provides a concrete example, and lists the return fields. No filler words, perfectly sized for quick comprehension.

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 lookup tool with full schema coverage, an output schema, and safe-read annotations, the description is complete. It tells the user exactly what to expect and how to invoke it without redundant detail.

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 documentation covers 100% of the single parameter, and the description's example ('8.8.8.8') reinforces it. However, the description doesn't add new semantic meaning beyond what the schema already provides (e.g., IPv4/IPv6 details).

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 ('Get') and the resource ('geolocation and network info for any IP address'), and the example differentiates it from siblings like get_my_ip. It is specific and instantly understandable.

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: this tool is for looking up geolocation info for any IP address. It doesn't explicitly name alternatives or exclusions, but the use case is unambiguous given the example and return fields.

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 richly discloses behaviors beyond the annotations: rate-limiting ('5 per identifier per day'), free usage, no tool-call quota impact, claim_token workflow, daily reading by the team, and the instruction to describe issues in terms of Pipeworx tools rather than pasting end-user prompts. No annotation contradiction exists.

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 a clear flow: purpose, use cases, exclusions, message guidance, claim token flow, and operational constraints. Every sentence contributes needed context, though it could be slightly trimmed without losing value.

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

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

Given no output schema, the description adequately explains return behavior (claim_token, later status checks) and covers constraints (rate limit, quota, scope). It also provides enough context for an agent to decide when feedback is appropriate, making the tool 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 coverage is 100%, so baseline is 3, but the description adds significant value beyond parameter descriptions. It explains the claim_token lifecycle (how to obtain it, how to use it later to check status), provides message guidance ('Be specific', '1-2 sentences typical'), and gives examples for context fields. This goes well 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 leads with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the feedback types (bug, feature, data_gap, praise) and distinguishes itself from siblings by focusing on the Pipeworx tool catalog, not general Q&A or research 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?

Provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data...'), a clear exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'), and a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists'). This fully guides 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 read-only, open-world, idempotent, and non-destructive. The description adds substantial context: self-aggregating signal, derived from CF analytics-engine, no PII, data shape (pack, tool, count), and caching behavior (5min-1h depending on window). This goes well beyond what annotations provide.

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

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

The description is appropriately sized and front-loaded: first sentence states purpose, then returns, then use cases, then technical caveats. Every sentence contributes value, with no fluff or repetition. The 'Useful for' list is concise and actionable.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers purpose, use cases, data origin, caching, and a hint at the result shape ('just (pack, tool, count)'). There are no critical gaps.

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

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

The schema covers 'window' at 100% with a clear description. The tool description reinforces the semantics but adds extra behavioral detail tied to the parameter: 'Cached 5min-1h depending on window' and the implication that shorter windows are for hot items, longer for steady-state. This adds value beyond the schema alone.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('what other AI agents are calling on Pipeworx right now'), and defines the scope (top tools, packs, total call volume over a window). It effectively distinguishes itself from sibling tools like discover_tools by focusing on collaborative usage data rather than general 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?

Provides three explicit use cases under 'Useful for', which gives clear context on when to use it. However, it does not explicitly mention when not to use it or name alternative tools like discover_tools, so it stops short of the full 5 for explicit alternatives/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?

Although annotations already indicate read-only, open-world, and idempotent behavior, the description goes far beyond by detailing internal logic: placeholder filtering with thresholds, Jaccard similarity requirements, fill check against live CLOB depth, and field-level output structure. This is rich behavioral context.

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

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

The description is long but well-structured with section headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear lead sentence. Some details are dense but each adds value; however, it could be trimmed slightly without losing essential 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?

Given no output schema, the description thoroughly explains response fields (opportunities[], partition_check, fill_check) and edge cases like placeholders, low similarity, and thin books. It covers both modes comprehensively and addresses failure/skip scenarios, making it highly 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 already covers 100% of parameters, but the description adds substantial meaning: examples of valid event slugs and topics, accepted URL format, mode-specific behavior, and what each parameter triggers. This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with distinct modes (event, topic). It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by specifying its unique approach and output.

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 guidance on when to use event vs topic modes, recommends event for specific markets, and notes when NOT to trade (realizable_edge_pp <= 0). Also directs to polymarket_fill_risk for custom sizing, giving clear alternative tool 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds a wealth of behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostic counters, the 24h-move warning when recent price movement exceeds edge, and the specific gate relaxations ('Run 8 from prior 85%/5%/50:1'). It is fully consistent with the read-only, idempotent nature and leaves no hidden surprises.

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 in the first sentence and uses all-caps section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) to organize dense content. It is quite long and includes granular details like sport-specific alpha values (tennis 1.02, soccer 1.10, MMA 1.15) that are not strictly necessary for tool invocation, but the structure prevents it from becoming unstructured noise. It earns a 4 rather than a 5 due to verbosity.

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?

There is no output schema, so the description takes full responsibility for explaining return values. It enumerates the top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), describes what each opportunity includes (edge_pp_net, kelly_fraction, market.liquidity, etc.), and even explains why a segment might be empty (funnel counters, filter_skips). This is a complete operational picture for a caller.

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 goes beyond the schema by explaining the cumulative intent of key knobs: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also clarifies the relationship between min_kelly and min_partition_leg_kelly, which is not obvious from the schema alone. Given full schema coverage, this added context 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on cross-data edge discovery rather than pure arbitrage or temporal tracking. It also gives an explicit use case ('what should I bet on today') that anchors the tool's purpose.

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

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

The description states when to use it ('agents discover opportunities without paging hundreds of markets') and includes a specific note about Fed bets being excluded from ranking, which hints at when not to rely on it for Fed-related signals. However, it does not explicitly name sibling tools or describe scenarios where an alternative tool would be preferred, so it falls short of full exclusions/alternatives 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?

The description discloses rich behavioral details beyond the annotations: snapshots are written on cache-miss, gaps mean no scan that day, history is bounded by a 60-day TTL, decay is computed on daily closes (not intraday), and edge_pp_net is signed with negative meaning SELL YES. This adds significant context and does not contradict the readOnly/idempotent hints.

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

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

The description is dense but every sentence earns its place. It is structured with a core question, parameter list, RESPONSE section, and LIMITS section, making it easy to scan without redundancy.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), the meaning of trend and decay fields, and important limitations. It covers all necessary context for a telemetry tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly repeats the schema's parameter info (days lookback, window family) but adds minor context around snapshot family and days having gaps. It does not substantially enhance the schema's parameter 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and explicitly contrasts fresh vs. old edges, distinguishing it from the sibling tool polymarket_edges which provides current edge data.

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 when to use the tool (to assess edge persistence and decay before trading) and provides context about snapshot gaps and history limits. However, it does not explicitly name alternative tools or state 'use this instead of X', so it falls slightly short of 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral transparency beyond those flags: it walks the order book ladder, returns a verdict of clean/degraded/cannot_fill, and explicitly warns that partial basket fills convert an arb into an unhedged directional position. It even names the dominant loss mode, giving the agent a clear mental model of what the tool does and what risks it surfaces.

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 densely packed but highly structured, using CAPITALIZED sections (SINGLE-MARKET, BASKET) and listing return fields in comma-separated groups. Every sentence adds new information—purpose, requirements, mode-specific behavior, return values, and usage guidance. Despite its length, there is no fluff; it earns its size by covering a complex tool comprehensively.

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 carries the full burden of explaining return values. It does so explicitly for both modes, listing every major field: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also provides practical context about when a user would need this tool. For a complex financial risk-check tool with 4 parameters and no output schema, this is exceptionally 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?

Although schema coverage is 100%, the description enriches the parameters significantly. For size_usd, it explains the dual interpretation: 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also clarifies the side parameter semantics for both modes, including the default auto-selection in basket mode based on partition sum. This goes well beyond the schema's brief 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 opens with a specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates the tool from siblings like polymarket_arbitrage and polymarket_edges by explaining that this is a pre-trade risk/fill-simulation tool, not a signal detector. It also names the two distinct operational modes (single-market and basket) and enumerates the outputs, 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 gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), providing both positive and negative usage context. This clearly distinguishes it from the sibling tools that produce the signals it checks.

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 read-only, idempotent, and non-destructive, but the description goes beyond by detailing the compatibility_warning scenarios, matched_pairs:0 interpretations, temporal_alignment implications, and the skipped_cross_type/subtype counters. It also warns that pre-mapped does not mean tradeable, fully disclosing behavioral nuances and failure modes.

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

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

The description is densely packed but verbose, with many nested clauses and repeated warnings (e.g., pre-mapped not tradeable appears essentially twice). While all content is relevant, the single-paragraph format and redundancy make it less concise than ideal for quick scanning.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains response elements (leg-by-leg prices, top_spreads_pp), compatibility warnings, temporal alignment, and skip counters. It anticipates common misinterpretations and provides enough detail for correct invocation and result interpretation.

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

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

Schema coverage is 100% with each parameter documented. The description adds meaningful context by explaining how `topic` triggers auto-fetching while explicit ticker/slug override the mapped sides, and clarifies the multi-mode interaction. It doesn't repeat schema minutiae but enriches the parameter purpose.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with explicit mention of two operating modes. It distinguishes itself from sibling tools by focusing on cross-venue price differences and compatibility checks.

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 `topic` mode versus explicit `kalshi_event_ticker` + `polymarket_event_slug` pairing, and cautions that pre-mapped topics are not necessarily tradeable. It provides clear context for when spreads are meaningful (equivalent bet shapes, aligned temporal periods), though it stops short of contrasting with alternatives like polymarket_arbitrage.

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=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context beyond safety: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the dual behavior of retrieving a specific value vs. listing all keys when the argument is omitted, which is not fully covered by the annotations. Minor omissions (e.g., data persistence or expiration) prevent a perfect score.

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 with zero filler: the first states the action, the second provides a concrete use case, and the third adds scoping and sibling links. Every sentence earns its place, and the structure is front-loaded with the core function. Excellent conciseness.

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

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

For a simple tool with one optional parameter, good annotations, and no output schema, the description is complete. It covers purpose, usage context, scope, and relationship to sibling tools. No critical information is missing for an agent to correctly select and invoke this 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 describes the 'key' parameter as 'Memory key to retrieve (omit to list all keys),' giving baseline 3 credit. The description reinforces this by saying 'omit the key argument' and adds context about the scoping and the relationship to remember/forget, enhancing understanding of the parameter's role in the workflow. 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 opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly identifies the tool's function and distinguishes it from siblings like remember and forget, which save and delete respectively. The mention of listing all keys further refines its purpose beyond a simple retrieval.

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 the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also pairs the tool with remember and forget, clarifying the workflow and implicitly guiding the agent away from alternatives. This provides strong usage 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?

The description states that setting mark_read:true will 'flag returned events read', which is a mutating side effect. This directly contradicts the annotations readOnlyHint: true, creating an annotation contradiction. The tool's own description reveals it is not purely read-only, so the transparency score must be 1.

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

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

The description is three sentences with a clear front-loaded purpose. It packs in return field details, filtering options, the mark_read effect, and a URL alternative without any fluff. Every sentence earns its place.

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

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

The description explains the return payload (source, citation_uri, raw event), filtering by type and since, the read-flag behavior, and an external mirror URL. It does not explicitly describe limit or unread_only in prose, but the schema covers those, and the overall context is sufficiently complete for a read-only (though contradicted) polling 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?

While the schema fully describes all five parameters, the description adds meaningful context: a concrete type example ('sec_8k'), the ISO timestamp format for since, and the downstream effect of mark_read on subsequent calls. This goes beyond the schema and enriches understanding of the parameters.

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: 'Pull fired events from your subscription feed' with details about return payload fields. However, it does not explicitly differentiate from sibling tools like list_subscriptions or recent_changes, so it stops short of a 5.

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

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

The description implies usage through 'Polls work fine' and offers an alternative HTTP endpoint for scripts/dashboards, but it does not explicitly state when to use this tool versus other MCP tools. There are no clear exclusions or direct alternates named, so guidance is implied rather than explicit.

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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds significant behavioral context: fan-out to multiple sources, fallback logic, USPTO soft-fail due to API sunset, and the structure of the returned data (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense but front-loaded with the core purpose and examples. It contains many details, but every sentence contributes necessary information about sources, fallbacks, parameters, or alternatives. Slightly long, 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?

Even without an output schema, the description provides a complete picture of what the tool returns and how it behaves. It covers all parameters, source logic, fallback conditions, limitations (USPTO sunset), and an alternative tool. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already covers all three parameters with descriptions, so the baseline is 3. The description adds valuable examples and clarifications, such as accepted ISO/relative date formats for 'since', ticker or zero-padded CIK for 'value', and a recommended default ('30d' or '1m'). This goes beyond the schema.

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

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

The description clearly identifies the tool as a 'change feed for a company' with a specific verb and resource, and lists the exact sources (SEC EDGAR, GDELT/GNews, USPTO) and return type. It also distinguishes itself from the sibling tool entity_profile, making the purpose 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 opens with natural-language usage examples ('What's new with X', 'latest on Y'), then provides explicit when-to-use guidance. It directly names an alternative (entity_profile) for static profile queries, and explains when GDELT vs GNews is used, giving clear context for selection.

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

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

Annotations indicate a write operation (readOnlyHint=false) and idempotency, but the description adds valuable context: storage as a key-value pair scoped by identifier, and retention rules ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). No contradiction with annotations.

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

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

Three sentences, all high-signal. The first sentence states the core purpose, the second gives usage context, and the third covers storage details and sibling tools. No fluff.

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

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

For a simple 2-parameter tool with no output schema, the description is highly complete: it covers what, when, how, and persistence, plus explicitly links to recall and forget. The agent has everything needed to use it correctly.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds meaning by clarifying the key-value relationship and giving examples of values to store (findings, addresses, preferences, notes), elevating it slightly above the schema baseline.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data). It also distinguishes from siblings by naming the paired tools: 'Pair with recall to retrieve later, forget to delete.'

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

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

Explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference, subject). It also explicitly contrasts with alternatives (recall and forget), making the choice clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses key behavioral traits: 'LEI/FIGI enrichment degrades gracefully' and 'Each call cascades through several lookup endpoints internally.' It also explains that unresolved identifiers are explicitly stated under `unresolved` rather than omitted, which is valuable behavioral context.

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

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

The description is well-structured with clear sections and each sentence adds value. However, it opens with a long list of example queries, which delays the core purpose statement. It is slightly verbose but appropriate for 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 compensates effectively by detailing returned identifiers, unresolved handling, and graceful degradation. It provides sufficient context for an agent to know what to expect, including the fallback behavior and internal cascading, making it complete for a 2-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: it explains the cross-source identity spine for companies, includes parent/ultimate-parent/children ownership, and specifies that company accepts ticker, CIK, or name. It also details the drug output (RxCUI + ingredient + brand), enriching both 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 explicitly states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides multiple natural-language examples and clearly differentiates from siblings by emphasizing that it produces identifiers needed by other tools, not profiles or comparisons.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, establishing it as a preliminary step. This is clear and strong directive for when to select this tool.

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

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

Annotations already establish read-only/open-world/idempotent safety. The description adds behavior: it calls ai_visibility_check per entity, ranks results by score, identifies most/least recognized, and returns score, confidence, and signal density per entity. This informs expected side effects (none) and output structure. No contradiction with annotations.

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

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

Three sentences: purpose, mechanism (probes/ranks), and use case/return. Every sentence provides unique information; no redundant fillers. Well-structured and front-loaded.

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

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

For a read-only comparison tool with good schema and annotations, the description tells the agent what it does, how (via ai_visibility_check), and what it returns (ranked list with score, confidence, signal density). That's adequate for correct invocation even without an output schema.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters (entities, models, _apiKey, context). The description does not elaborate on parameter usage beyond what the schema says, though it echoes the 'first entry as subject' concept from the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side' – a specific verb (compare) + resource (AI visibility) + scope (multiple entities). It differentiates from the sibling ai_visibility_check by explicitly mentioning it probes each entity and ranks them, making it the multi-entity comparison variant.

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

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

It provides a clear use case: 'competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. It implies this is the multi-entity counterpart to ai_visibility_check by stating it probes each entity with that tool. However, it doesn't explicitly say when not to use it or name other alternatives like compare_entities, so I give 4 rather than 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 description adds significant behavioral context beyond the annotations: it explains the composite fan-out into external services, reveals that bundlephobia's first measurement can take 5-30s, and describes graceful degradation with 'sources_failed' listing timeouts while the rest still returns. The positive annotations (readOnly, idempotent) are consistent, and the description enriches the operational expectations.

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

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

The description is somewhat long but every sentence earns its place: it front-loads the core purpose, lists the return fields, and covers failure modes and ecosystem scope. It uses dashes and semicolons for structure, making it scannable despite its length. No word is wasted.

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 composite nature, the description is remarkably complete: it explains the return summary block fields, per-advisory detail, links, and alternative versions, plus failure behavior and timing. With no output schema provided, the description carries the full burden of return semantics, and it does so thoroughly.

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

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

The input schema already provides 100% coverage for both parameters, including descriptions for 'package' and 'version', and the default for 'version'. The description adds no new parameter-specific meaning beyond that, so it stays at the baseline of 3. It does mention 'npm package' in the purpose, but that's context, not 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 states a clear, specific purpose: a composite 'should I add this npm package to my project' check. It names the exact resources (deps.dev and bundlephobia) and distinguishes itself from any sibling by being the only tool focused on npm package vetting. The verb 'scan' and the comprehensive return list make the scope 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states when NOT to use it, directing non-NPM ecosystems to 'deps.dev:version directly', giving a concrete alternative. This is ideal guidance for an agent deciding between tools.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral detail beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also discloses the return format (passages with offsets and similarity scores). 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 but information-dense. It front-loads the core purpose, then efficiently covers use case, pairing, algorithm, limits, and output characteristics—every sentence earns its place with no filler.

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

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

Despite lacking an output schema, the description clearly states what the results contain: 'top-N passages with character offsets and similarity scores.' It also covers the truncation behavior, the maximum input size, and how to use it with a companion tool, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters. The description adds contextual examples like 'a SEC 10-K body, an article, a long tool result' and query examples, but these are already mirrored in the schema. It does not add significant new meaning beyond what parameter descriptions provide, so the baseline of 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', giving a specific verb and resource that clearly distinguish it from the sibling tools like ask_pipeworx (which likely queries external data). It also explains the value proposition—saving context, returning only relevant passages—making its purpose 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?

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt' and it directly names a companion alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and alternative 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?

The description goes far beyond the annotations (non-read-only, open-world, idempotent, non-destructive). It details OAuth requirements, SMS verification with a 10/day cap, webhook HMAC signing and auto-disable after 10 failing runs, and the always-on feed behavior. This provides essential context for an agent to understand side effects and constraints, with no contradictions to annotations.

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

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

The description is a single dense paragraph, but the length is justified given the 5 subscription types and multiple delivery channels. It front-loads the primary action and return value, and each sentence adds necessary detail. Minor inefficiency exists in repeating some schema information, but it remains structured enough for an agent to parse.

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

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

For a complex tool with no output schema, the description covers all critical dimensions: OAuth prerequisites, all supported types with examples, delivery channels (feed, email, SMS, webhook), rate limits, verification requirements, and the returned subscription ID. It also explains how to consume the feed. There are no major gaps that would confuse 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 schema already has 100% coverage, but the description adds interpretive meaning beyond the schema. For example, it explains that items:["5.02"] corresponds to an officer change and clarifies what polymarket_edge mispricings are. These concrete examples help the agent construct valid params, even though much of the delivery schema is already self-explanatory.

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 is a specific verb+resource with a clear output. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and ongoing subscription behavior.

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: requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels. It mentions pulling via recent_alerts as part of the feed behavior, implying an alternative consumption mode. However, it does not explicitly compare against sibling tools like list_subscriptions or unsubscribe for management tasks, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. Beyond that, the description adds useful behavioral context by explaining the return structure: category-bucketed example questions with tool and argument shape, drawn from the live catalog. It also notes that no arguments returns the full spread, which is behavior not covered by annotations.

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

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

The description is front-loaded with example queries, quickly establishes purpose, and then details output and usage. Although slightly long, every sentence adds value—covering output content, parameter usage, and the recommended first-use scenario. It is well-structured and not redundant.

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 one-parameter tool with no output schema, the description is remarkably complete: it explains what the tool returns, how to invoke it, and when to use it. It even lists the major category examples. Minor gap: it doesn't specify the exact JSON response shape, but the description of each item's contents suffices for an agent to understand the return value.

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 `topic` parameter, and the schema already explains the allowed focus areas and the omit-for-full-spread behavior. The description reinforces this with examples ('finance', 'pharma', 'betting') but does not add meaningful new information beyond the schema, so it meets the baseline of 3.

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

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

The description states a specific verb and resource: it returns category-bucketed example questions from the live catalog, each with the exact tool and argument shape. It distinguishes itself from siblings by positioning as the onboarding entry point and explicitly referencing meta-tools like ask_pipeworx and entity_profile.

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

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

The description gives clear when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter for focusing. It implies when not to use it (if you already know what to ask), but does not name specific alternative tools as 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?

Annotations already cover read-only, idempotent, and destructive hints, but the description adds deeper context: ownership enforcement (only your own subscriptions) and the deactivation (not deletion) behavior, including how historical events remain accessible via recent_alerts. This goes well beyond what structured fields provide.

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

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

Three short sentences deliver purpose, a constraint, and a behavioral note without waste. Every sentence earns its place.

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

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

For a simple 1-param tool with robust annotations, the description covers the key behavioral aspects. It doesn't address error handling or return format, but the tool's simplicity and lack of output schema make this acceptable. Slightly more detail on outcomes would push it to a 5.

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 the id parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds no further parameter details beyond 'by id,' so the baseline of 3 is appropriate.

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

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

The description starts with 'Cancel a subscription by id,' clearly stating the action and target. It distinguishes from siblings like subscribe and list_subscriptions by defining the cancellation use case, and ownership enforcement adds specificity.

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

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

The description implies usage (use to cancel a subscription) and adds context about ownership and soft-delete, which guides when to use it. However, it doesn't explicitly name alternative tools or state exclusions, keeping it just short of 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?

Beyond the annotations (read-only, open-world, idempotent), the description discloses critical behavior: the exact verdict vocabulary, the semantic distinction between 'could_not_verify' (failure) and 'unsupported' (no source), the presence of verification_error details, and the structured vs grounded pipeline routing. These details materially help callers interpret results correctly.

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 front-loads natural-language trigger phrases and a clear use case, then moves through pipeline routing, return values, and important edge-case warnings. Every sentence carries distinct useful information, and the length is justified by 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?

There is no output schema, so the description carries the full burden of explaining returns—it lists all verdicts, citations, and reasoning, and explains error semantics. The tool's routing and fallback behavior are also described, making the description sufficient for correct invocation and interpretation.

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 both parameters with 100% description coverage, including tolerance_pct examples and semantics. The tool description adds context about percent-delta math for financial claims but does not need to repeat the schema, so the 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 uses specific verbs ('validate', 'fact check', 'verify the claim') and identifies the resource as natural-language claims against authoritative sources. It clearly distinguishes itself from sibling research tools by framing a single compound pipeline that replaces sequential NL parsing, entity resolution, data lookup, and comparison.

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

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

It gives explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and explains routing for company-financial vs other claims. However, it does not explicitly name alternative sibling tools as when-not-to-use options, so it falls 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.