Jsonplaceholder

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond these: the default free model, the BYO API key with direct pass-through to Anthropic, and the fact that the user pays for Anthropic calls. This informs the agent about external network calls and cost implications without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core function, then details of model selection and output structure, and ends with use cases. Every sentence earns its place with no fluff or repetition.

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

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

Given there is no output schema, the description effectively covers the return format with 'per-model {score, confidence, signals, raw_response} + a combined view.' It also explains the two model options and the context parameter. The combined view could be described further, but overall it is sufficiently complete for a moderate-complexity read-only tool with strong annotations.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful semantics: the default model when no models array is provided, the requirement of _apiKey specifically for Anthropic, the 'passed straight through' behavior, and the purpose of context for disambiguation. This enriches the schema's dry parameter definitions.

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

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

The description clearly states the tool's verb ('Probe'), the resource ('one or more LLMs'), and the specific output ('score visibility (0-100) per model'). It distinguishes itself from siblings by positioning as a broad brand/product/topic visibility check rather than a competitor-specific scan, such as scan_competitor_ai_presence.

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

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

The description gives clear context for when to use it: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternative tools or exclusions, but the use cases effectively guide the agent on appropriate scenarios, meeting the 'clear context, no exclusions' level.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: routing to multiple sources, returning citations, covering news/live feeds, and being fast. It does not contradict annotations. Minor gap: no details on error handling or ambiguous queries, but the description still provides meaningful transparency.

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

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

The description is longer than average but information-dense and front-loaded with the key instruction 'PREFER OVER WEB SEARCH.' It uses lists and examples effectively. Some redundancy exists (e.g., 'START HERE' and 'default entry point' express similar ideas), but every section earns its place by either clarifying scope, usage, or alternatives.

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

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

Given the complexity of a tool routing across 5,529 tools, the description covers all essential aspects: what it does, when to use it, examples, alternatives, and return format (citations). It explains the openWorldHint by listing knowledge domains. It also mentions tier availability and speed. No output schema exists, so the description carries the full burden of return-value explanation, which it fulfills.

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 every parameter already has a description. The description adds examples of natural language questions but does not add new semantic meaning beyond what the schema already states. It even mentions aliases in the schema itself. Thus, the baseline 3 applies without additional contribution from the description.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing their specialized roles. The verb 'routes' plus the resource (tools/sources) makes the purpose highly specific.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH... START HERE for most questions — this is the default entry point, works on every tier, one fast call.' It also lists when NOT to use it and names alternatives: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is model-tier 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, etc.), the description discloses the beta nature, live candidate testing, current inactive state, fallback behavior ('falls back to nothing — this IS a full working router'), and that results feed into a comparison process. This is rich, non-obvious 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 and front-loaded with the key fact that it's a beta version. Every sentence adds value: identity, current status, usage direction, and fallback guarantee. 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 router tool with no output schema, the description provides complete context: what it does, how it relates to the stable version, current active state, and how to use it. The lack of an output schema is mitigated by stating 'same response shape' as ask_pipeworx.

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 all parameters being aliases for 'question' and fully described in the schema. The description does not add parameter-level detail beyond saying 'same arguments' as ask_pipeworx, which is already implied by the schema. Baseline 3 is appropriate.

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

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

The description clearly states that this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being experimental with candidate routing improvements.

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

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

Explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, providing clear context for usage and the alternative stable ask_pipeworx.

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 critical behavioral traits: it costs an extra LLM call, extracts answers using ONLY the tool result, returns verbatim evidence, and explicitly enumerates refusal reasons. No contradiction with annotations; this is a substantial add.

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 clause earns its place: mode, cost, return shape, refusal reasons, and alternative suggestion. It front-loads the most critical information ('Hallucination-resistant answer mode') and remains scannable despite its length.

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

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

The description fully compensates for the lack of an output schema by detailing the success return fields and refusal reasons. It also explains routing across thousands of tools and the extra-call cost, covering all necessary context for a high-stakes tool.

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

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

Schema coverage is 100% — all six parameters are documented as aliases for 'question', and the schema explicitly says they are interchangeable. The description adds no additional parameter meaning, which is acceptable given the schema fully carries the burden. Baseline 3 is appropriate.

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

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

The description clearly identifies a specific mode ('Hallucination-resistant answer mode') for high-stakes reads, distinguishing it from the sibling ask_pipeworx by its grounded extraction behavior. It states the exact verb (answered via tool results only) and resource (Pipeworx tool routing). This is a specific, non-tautological 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?

Provides explicit use cases: 'whenever an answer will be quoted, cited, or acted on' with examples (financial verdicts, legal claims). It also contrasts with the alternative: 'prefer ask_pipeworx for casual lookups.' This is clear when/when-not guidance with a named alternative.

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 the tool read-only and idempotent. The description goes far beyond that, disclosing resolver confidence contracts, low-confidence short-circuits, closed-market status handling, wide-spread liquidity warnings, and cancellation-rule risk. This is exceptional behavioral transparency.

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

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

The description is heavily front-loaded with purpose and usage, but it becomes very long and dense with edge cases, examples, and detailed response shapes. It is structured with uppercase labels, yet many sentences could be trimmed without losing essential meaning. It earns a 3: structured but overlong.

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?

Because there is no output schema, the description carries full responsibility for explaining return values. It thoroughly documents response shapes, evidence structure, resolver confidence, parent_event extraction, news fallback behavior, safety statuses, and cancellation-rule nuances. This is about as complete as a tool description can get.

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

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

The input schema covers all three parameters with detailed descriptions, so schema coverage is 100%. The description repeats the market param formats and adds fan-out examples, but doesn't introduce new parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses a specific verb + resource and distinguishes itself from generic research tools by focusing on Polymarket bet research with explicit use cases ('should I bet on X').

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 triggers: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes the fan-out behavior by category, but it doesn't explicitly state when not to use it or mention alternatives by name, so it earns a 4 rather than 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, inclusion of pipeworx:// citation URIs, and estimated reduction of 8–15 sequential lookups. 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 every sentence provides value. It is front-loaded with the core purpose and usage triggers, followed by data-source details and return format. No fluff or repetition—each clause adds necessary information for correct tool invocation.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the lack of an output schema, the description is exceptionally complete. It covers what data is pulled, how results are ordered, what return artifacts to expect, and when to prefer this tool. No critical operational detail is left unspecified.

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

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

Although the schema already covers 100% of parameter descriptions, the description enhances meaning by explaining how 'type' determines the data source and output (company vs drug) and providing concrete examples for 'values' (e.g., ["AAPL","MSFT"], ["ozempic","mounjaro"]). It also clarifies size constraints and sorting behavior, adding context beyond the raw schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes itself from sequential lookups and sibling tools like entity_profile by explicitly positioning itself as the preferred alternative for comparison tasks.

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

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

The description provides explicit usage triggers ('Compare X and Y', 'X vs Y', 'which is bigger / better / larger / more profitable', etc.) and a strong directive ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). It also implies the alternative (sequential lookups) and clarifies when to use this tool versus those.

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 annotations, the description reveals key behaviors: returns a findings packet with verbatim evidence, confidence, source, fetched_at, and fetchable citation URIs; provides explicit gaps[] for unanswered facets; never invents data; returns contradictions[] at standard/thorough depths; and semantically excerpts large records. It also discloses latency, auth tier differences, and failure modes (empty gaps for non-catalog topics).

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 and dense, but every sentence contributes unique, actionable information. It is front-loaded with the most critical account/alternative guidance. It loses a point for being a wall of text that could be better structured with bullets or sections, though it remains consistently relevant.

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 covers return values (findings packet, gaps[], contradictions[], hop, citation_uri), performance expectations (15-90s), edge cases, and auth requirements. It even explains the citation resolvability guarantee, making it complete for an agent to invoke and interpret results.

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

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

While the schema already describes both parameters (100% coverage), the description enriches them significantly: it explains what 'depth' levels mean behaviorally (quick/standard/thorough with hop counts, gap recovery, contradiction passes) and confirms that broad/multi-part questions are fine for the 'question' parameter. This adds meaning beyond the raw schema.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1455 structured data sources in ONE call, decomposing questions into facets and routing them in parallel. It explicitly differentiates from siblings by noting 'this is NOT open-web search' and providing concrete example questions.

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 offers explicit guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking/current-news topics. It also details account prerequisites and a fallback if not signed in, making when-to-use unmistakable.

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=false. The description adds valuable behavioral context: it returns top-N relevant tools with full input schemas and examples, ready to call directly ('no second schema lookup needed'). This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with purpose and usage, followed by return value and priority instruction. The long list of domains is specific and useful, though slightly dense. Overall, every sentence contributes value without redundancy.

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

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

Despite no output schema, the description clearly states what the agent will receive: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Given the low complexity and rich annotations, the description is complete enough 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?

Schema description coverage is 100%, so the baseline is 3. The description says 'by describing the data or task,' which aligns with the query parameter, but it does not add extra semantic detail beyond what the schema's property descriptions already provide (including alias relationships).

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: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover). It also differentiates from siblings by framing itself as a meta-tool for discovery ('Call this FIRST when you have many tools available').

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 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 (not just one answer).' This clearly tells the agent when to invoke this tool instead of others.

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 behavioral context beyond annotations: parallel fan-out across multiple sources, specific return fields, the patents API sunset soft-fail, and the GDELT→GNews fallback chain. No contradiction with annotations.

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

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

The description is long but every sentence carries specific information. It is front-loaded with user intent examples, then strategic guidance, then structured output list, then parameter constraints. Slightly dense but not bloated; appropriate for a complex multi-source tool.

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

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

Given no output schema, the description fully enumerates the return structure (cik, recent_filings, fundamentals, patents, news, LEI) and addresses edge cases (patent API sunset, name resolution fallback). It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193'), clarifying zero-padding for CIK, and reinforcing that names are unsupported. This goes beyond the schema's 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 identifies the tool as a full cross-source profile generator for US public companies, with a specific verb ('profile', 'brief me') and resource ('US public company'). It distinguishes from siblings by explicitly stating to prefer this over chaining single-pack SEC/XBRL/news lookups for holistic queries.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clearly states when not to use it (if only a name is provided, use resolve_entity first), which acts as an alternative tool recommendation.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description reinforces 'Delete' and adds context about clearing sensitive data, but it does not disclose behavior such as what happens when the key does not exist—though idempotentHint covers that implicitly. Some value added beyond annotations, but not substantial.

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: it states the action, specifies when to use it, and relates it to sibling tools. Every sentence earns its place, is front-loaded with the verb 'Delete', and there is 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?

For a simple one-parameter tool with no output schema, the description is complete: the schema covers the key, annotations cover destructive and idempotent behavior, and the description explains purpose and usage clearly. Nothing essential is missing 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 schema fully describes the single 'key' parameter as 'Memory key to delete', achieving 100% coverage. The tool description merely says 'by key', which adds no additional semantic value. Baseline of 3 is appropriate given high schema coverage.

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

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

The description opens with 'Delete a previously stored memory by key' using a specific verb (delete), resource (memory), and method (by key). It clearly distinguishes from sibling tools like remember (store) and recall (retrieve), making its function 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 'Use when' scenarios are provided (stale context, task done, clearing sensitive data), which gives clear guidance on when to invoke the tool. Also mentions pairing with remember and recall to situate it in the memory workflow. It does not explicitly state when not to use it or alternative tools, but the context is clear for this simple memory operation.

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 operational detail: it performs a live page fetch, extracts title/description/key links, and outputs a text blob. It doesn't cover edge cases like unresponsive sites, but the annotation coverage is strong.

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

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

The description is two sentences plus a bullet-like 'Useful for' list. It front-loads the core function and then adds practical use cases. The use-case list could be more compact, but the overall structure is efficient and scannable.

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 only two parameters, strong annotations, and no output schema, the description covers the purpose, the output format, and usage scenarios. The only gap is a brief note about potential network errors, but that is acceptable for a tool with such a simple contract.

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

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

The input schema provides full descriptions for both 'url' and 'max_links' (100% coverage), including default and maximum values. The description reinforces the URL's purpose by calling it 'a specific landing page' and explains the overall workflow, but doesn't add new parameter-specific information, 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 a specific verb ('Generate a production-ready llms.txt file for any URL'), names the resource (llms.txt), and explains the underlying mechanics (fetches page, extracts data, emits markdown). It also lists concrete use cases that distinguish it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The 'Useful for' section provides three clear scenarios: client indexing, personal projects, and competitor auditing. While it doesn't explicitly name when not to use the tool or compare against alternative tools, the context is sufficient to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral detail by listing the exact response fields (comment ID, name, email, body). No contradictions.

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

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

The description is a single sentence with no waste, front-loading the core action and resource, followed by a useful example and return field list.

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

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

For a simple one-parameter tool with an output schema and clear annotations, the description provides everything needed: scope, example, and return contents. No gap in completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new information about the post_id parameter beyond what the schema already provides, though it reinforces the meaning with an example.

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 the verb 'Fetch' and resource 'comments for a specific post by post ID', clearly distinguishing it from sibling tools like get_post and get_posts. The example and scope are specific and 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 clearly implies the tool is for retrieving comments on a particular post, providing context for when to use it. However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behaviors. The description adds valuable context by specifying the exact return fields (post ID, user ID, title, body) and noting that the data is fake, which goes beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and includes all necessary information without any filler or redundant content.

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

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

For a simple 1-parameter, read-only tool with full annotations and an output schema, the description is complete. It clearly states what the tool does, what it returns, and that it operates on fake data, leaving no significant 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 input schema fully describes the 'id' parameter, including its type, range (1–100), and purpose. The description merely repeats 'by ID' and provides an example, adding no semantic value beyond what the schema already documents.

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?

Explicitly states 'Fetch a single fake blog post by ID,' which clearly differentiates it from sibling tools like get_posts that likely fetch multiple posts. The verb 'fetch' and resource 'single post' are specific and 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 clearly implies this tool is for retrieving exactly one post by ID, which is a clear usage context. However, it does not explicitly mention when to use alternatives like get_posts or any exclusions, so it falls 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/idempotentHint, so description needn't repeat safety. It adds the return structure (post ID, user ID, title, body) and clarifies the data is fake, which is useful contextual behavior.

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

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

Two concise sentences that front-load the action and provide essential return info. 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?

For a simple read-only list tool with one optional parameter, annotations, and an output schema, the description covers purpose, return fields, and context. The only gap is the minor tension between 'all' and the limit parameter, which prevents a perfect score.

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

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

Input schema covers the single 'limit' parameter with full description (default/max), so the description does not need to elaborate. However, it adds no extra semantics beyond the schema, and the word 'all' could be slightly ambiguous given the limit parameter.

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

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

The description clearly states the action ('Fetch'), the resource ('all fake blog posts'), and the intended use case ('testing and prototyping'). It also distinguishes from sibling 'get_post' by emphasizing 'all'.

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 testing/prototyping but does not explicitly address when to choose this tool over alternatives like get_post or get_comments. No exclusions or alternative guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing the returned fields (name, username, email, etc.), providing useful context beyond the annotations.

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

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

The description is a single, front-loaded sentence that states the action, purpose, and returned data. Every word earns its place with no redundancy.

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

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

With zero parameters, an output schema, and annotations, the description provides sufficient context: it explains the purpose, scope, and return payload. No critical gaps are apparent for a simple test utility.

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?

There are no parameters, so the baseline is 4. The description adds meaning by specifying 'all fake users', implying that no filtering is applied and the tool returns the full set.

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 ('Fetch all fake users') and the purpose ('for testing'). It distinguishes from sibling tools like get_posts and get_comments by specifying the resource as users.

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 phrase 'for testing' provides clear context on when to use this tool, but it does not explicitly mention alternatives or exclusions. It is clear enough for an agent to infer its intended use in test 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, idempotentHint, and destructiveHint, so the description is not required to restate safety. It adds value by specifying the default behavior (only active subscriptions) and the exact response structure (id, type, params, created_at, last_fired_at, fire_count). This clarifies what 'list' returns 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?

Two sentences, front-loaded with the action, followed by output fields and a usage tip. 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?

The tool is simple (one optional parameter, no output schema). The description covers purpose, output fields, default filter, and when to use it, making it self-sufficient for an agent.

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

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

The sole parameter include_inactive is fully documented in the schema with 'Include cancelled subscriptions in the response (default false).' The description's 'active subscriptions' phrasing reinforces the default but doesn't expand on the schema.

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

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

The description opens with 'List the caller's active subscriptions,' a specific verb+resource pairing that clearly distinguishes this from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, leaving no ambiguity about 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 final sentence provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call this tool—before subscribing or unsubscribing—and implies the alternative tools for those actions.

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 rate limiting (5 per identifier per day), that it is free and doesn't count against quota, the claim_token return/read flow, and that the team reads digests daily. These behavioral details go far beyond the sparse annotations and set clear 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?

Though longer than many tool descriptions, every sentence earns its place: usage triggers, scope boundaries, content rules, token flow, and rate limits. It is front-loaded with purpose and immediately actionable guidance, with no filler or repetition.

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

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

For a feedback tool with no output schema, the description is complete: it covers when to use it, what to include, scope limitations, the claim_token return flow, rate limits, and impact. The absence of an output schema is compensated by explicitly stating what the tool returns and how to check resolution status.

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, but the description adds meaningful operational detail beyond the schema: it explains that filing without an account returns a claim_token and gives the exact re-submission syntax pipeworx_feedback({claim_token:'pwfb_…'}). It also reinforces message content guidelines. This lifts it above baseline, though the schema already documents the parameters well.

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 ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately enumerates the feedback categories (bug, feature/data_gap, praise). It also distinguishes itself from any other MCP server's feedback channel, making it clear this tool is only for Pipeworx-served 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?

Explicit when-to-use triggers are given for each feedback type ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...'). It also gives a clear exclusion: if the tool came from a different MCP server, file there instead, and advises not to paste the end-user's prompt.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond that, such as caching behavior ('Cached 5min-1h'), derivation from CF analytics-engine, and no PII. This extra information helps an agent anticipate latency and data sensitivity without contradicting the annotations.

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

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

The description is moderately sized but well-structured: a clear lead sentence, a formatted 'Useful for' numbered list, and a final line on caching/PII. Each sentence earns its place; only minor redundancy exists with the schema's window description.

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 specifying the exact return shape ('top tools, top packs, and total call volume' and 'just (pack, tool, count)'). It also covers window options, caching, and data source, making it complete for a simple read-only tool. A slight gap is the lack of explicit response structure for 'top packs', but it's sufficient.

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

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

Schema coverage is 100% for the only parameter (window), with the schema description already explaining the default and tradeoffs between windows. The tool description mentions the window in the first sentence but doesn't add meaning beyond what the schema provides, so it meets the baseline for fully covered schemas.

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, actionable statement: 'What other AI agents are calling on Pipeworx right now' and explicitly lists the returned data (top tools, top packs, total call volume). This clearly distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregated call-volume trends.

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

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

The 'Useful for' section names three concrete scenarios (discovering hot data sources, confirming canonical choices, checking alignment with agent needs). It doesn't mention exclusions or alternative tools, but the context is strong enough to guide appropriate use.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds extensive behavioral context: the 3pp partition deviation threshold, ≥0.30 Jaccard similarity, placeholder filtering with >20% threshold, and fill check behavior that warns against trading when realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is long but well-structured with caps-lock section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with a summary sentence. It is dense with necessary details, though slightly redundant in places (e.g., repeating monotonicity/partition-sum wording).

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

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

Given the tool's complexity (two modes, multiple checks, output shape) and no output schema, the description fully compensates: it describes the response fields (opportunities[], partition_check{...}), explains edge cases (skipped_low_similarity, placeholder fraction null), and references sibling tools for related needs. Very complete.

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

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

Schema coverage is 100% with decent descriptions, but the tool description goes far beyond: it explains what each mode walks through (child markets, date-axis ordering), gives concrete slug examples, mentions URL acceptance not in schema, and details the partition_check and topic cross-event scanning behavior. This adds substantial meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk, which focus on edges or fill risk rather than arbitrage 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 explicitly details when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and even names alternatives ('For custom sizing use polymarket_fill_risk'). It also explains how cross-event mode catches patterns that single-event misses, giving clear decision 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 readOnly=true and destructive=false, but the description goes far beyond by disclosing the model families (crypto_price from 90d FRED log-returns, news_momentum from GDELT), the response structure (by_segment, fed_candidates, _diagnostics), caching behavior ('Cached 1h at the KV level keyed on all knobs'), and caveats like the 24h-move warning and slippage adjustments. This rich behavioral context enables the agent to understand expected outputs and limitations without contradiction.

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

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

The description is long but well-structured with explicit labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose. Every section conveys necessary detail for a complex tool, so while not terse, it earns its length. A 5 would require even tighter wording with no redundancy.

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

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

With no output schema, the description must explain the return shape, and it does: it details the top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h-move warning), and why segments may be empty via funnel counters. It also covers caching and the rare-by-design nature of one segment. For a tool with 9 parameters and complex output, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context for key knobs: it explains that min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable' and clarifies min_partition_leg_kelly's interaction with per-leg Kelly in partitions. It also adds real-world slippage context ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'). This exceeds schema-only semantics without covering every parameter in prose.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and target use case. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, though the detailed segments (model_driven, structural_arbitrage, concentrated_longshot) imply a broader 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 provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to adjust knobs (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model') and notes that Fed bets are excluded from ranking. Yet it lacks explicit when-not-to-use or alternative tool references, so it falls 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 indicate a read-only, idempotent operation, and the description goes far beyond by detailing the exact response structure (tracked, expired, snapshot_dates), the meaning of gaps, the 60-day TTL bound, and the computation basis for decay. 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 longer than average but densely organized with clearly labeled sections (Args, RESPONSE, LIMITS). Each sentence adds necessary information, and the structured format makes the complexity manageable without waste.

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

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

With no output schema, the description fully assumes the burden of explaining return values and does so thoroughly: it defines every response subsection, interprets expired opportunities, explains snapshot gaps, and documents history limits. It also accounts for edge cases like TTL and cache-miss behavior, making the tool's behavior predictably complete.

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

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

Schema coverage is 100%: both days and window already have types, defaults, ranges, and enum values. The description restates defaults and adds the concept of a 'snapshot family', but provides no additional semantic detail beyond what the schema already offers, so the baseline of 3 applies.

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

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

The description explicitly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific analytical question. It clearly differentiates itself from the sibling 'polymarket_edges' by focusing on time-series persistence rather than current edges.

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

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

The description gives a clear use case: determining how long an edge has existed and whether it is shrinking, with a concrete example contrasting fresh vs. old wide edges. It does not explicitly name alternative tools or exclusion criteria, but the context is sufficient for an agent to select this tool when temporal persistence matters.

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 the tool's internal behavior in detail: it 'walks the ladder' to compute fill prices, returns a verdict, and in basket mode identifies thin legs and forced directional risk. It doesn't contradict the annotations (readOnlyHint, idempotentHint, etc.) and adds context about the live order-book depth and the specific outputs.

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

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

The description is lengthy but well-structured, starting with the core purpose and then breaking down the two modes with clear formatting (SINGLE-MARKET, BASKET). Every sentence carries functional information; while it could be tightened, the complexity of the tool justifies the length.

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

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

Given the absence of an output schema, the description thoroughly enumerates the return fields for both modes, including top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and basket-specific outputs like capture_ratio, thin_legs, and forced_directional_risk. It also covers prerequisites and the strategic context, making it a complete 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?

Although the input schema already covers all four parameters, the description adds significant semantic context: it explains that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains default side behavior in basket mode, going 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 states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource. It clearly distinguishes between single-market and basket modes, making it distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing clear when-to-use guidance. It also explains the failure mode (partial basket fills convert an arb into an unhedged directional position), which helps an agent decide between this and alternatives.

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

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

Even though annotations already declare readOnlyHint=true, the description goes far beyond that by explaining the compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type counters. It discloses when spreads are 'mathematically meaningless' and what failure modes to expect, giving the agent substantial behavioral context.

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

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

The description is lengthy and dense, but every section earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with the core definition, then logically flows through modes, response shape, safety fields, and caveats. Slight verbosity in repeated cautionary phrasing keeps it from a 5.

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

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

With no output schema, the description fully compensates by describing the response structure: 'each venue's leg-by-leg prices... plus matched spread[].top_spreads_pp.' It also covers edge cases like temporal misalignment and incompatible bet shapes, making the tool's behavior predictable in realistic failure scenarios.

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 covers all three parameters (100% coverage), but the description adds critical meaning: it enumerates the 10 valid topic values, explains how kalshi_event_ticker and polymarket_event_slug override the mapped sides, and clarifies the two operating modes. This transforms bare parameter names into a usable mental model.

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 precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (two prediction markets) and the operation (computing a spread), and it differentiates this from siblings like polymarket_arbitrage by focusing on cross-venue 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 explains two distinct modes of use: pre-mapped topic shortcuts and explicit custom pairings. It also warns when the tool is not appropriate: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not name alternative sibling tools explicitly, but the usage context and limitations are clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive, so the bar is lower. The description adds valuable context about scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the list-all behavior when key is omitted. It does not cover return format or error cases, but for a simple retrieval 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 three sentences with no fluff. It front-loads the core behavior, then provides usage examples, scoping details, and sibling relationships. 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?

With only one optional parameter, no output schema, and good annotations, the description is complete. It covers purpose, usage context, scoping, and relationships to remember/forget. No significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by specifying the key must have been 'previously saved via remember' and clarifies the omission behavior, which complements the schema's own 'omit to list all keys'.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys, with a specific verb ('retrieve') and resource ('value'/'keys'). It distinguishes itself from siblings by naming 'remember' and 'forget' and clarifying its complementary role.

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

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

The description explicitly says when to use it ('Use to look up context the agent stored earlier') and provides a clear alternative/exclusion by pairing with 'remember' to save and 'forget' to delete. It also implies not to use it for new information by saying 'without re-deriving it from scratch'.

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 contradicts the annotation readOnlyHint:true by revealing that setting mark_read:true flags events as read, which is a state-changing side effect. Despite adding useful details like payload structure, this annotation contradiction forces a score of 1 per the rules.

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

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

The description is concise, front-loaded with the core purpose, and every sentence provides useful information—filtering, return fields, mark_read behavior, and an alternative access method. No fluff or repetition.

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

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

Despite lacking an output schema, the description fully covers return payload details, filtering options, side effects, and polling suitability. It gives a complete picture for an agent to invoke the tool correctly, aside from the annotation contradiction which is a separate issue.

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

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

Schema coverage is 100% for all 5 parameters, giving a baseline of 3. The description adds value by giving a concrete example of type (“sec_8k”), clarifying since as an ISO timestamp, and explaining the mark_read side effect on subsequent calls, which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and specifies it returns recent alerts with source, citation_uri, and raw payload. This distinguishes it from sibling tools like get_posts or list_subscriptions by focusing on fired events from the subscription feed.

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 usage context: it mentions filtering by type and since, explains the mark_read behavior, and states that polling works fine, even offering an alternative HTTP endpoint for scripts/dashboards. It does not explicitly exclude other tools but gives enough context for typical use.

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

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

The description discloses specific runtime behaviors beyond annotations, including GDELT-to-GNews fallback on rate limit/5xx, soft-failure of USPTO due to PatentsView sunset, and the return structure with citations. This complements the readOnly/idempotent hints with actionable details.

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 information-dense and well-structured, but the opening list of six example paraphrases is somewhat redundant. However, each section (purpose, parameters, fallback, return, alternative) earns its place, and the critical details are 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 tool with no output schema, the description covers return shape (changes[], total_changes, citation URIs), source specifics, and parameter semantics. It lacks minor edge-case details (e.g., behavior for invalid tickers, coverage limits) but is sufficiently complete for an agent to select 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%, and the description largely repeats parameter details: `since` formats, `value` as ticker/CIK, and `type` as 'company'. It does not introduce additional meaning beyond what the schema already specifies, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a change feed for a company, supporting queries like 'What's new with X' and listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly differentiates from entity_profile by contrasting dynamic changes with static profiles.

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

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

Provides explicit usage context via natural-language examples ('What's new with X') and a direct alternative: 'Use entity_profile instead when you want the static profile...'. Also describes the parallel fan-out behavior, clarifying when to rely on this tool for multi-source updates.

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

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

Beyond annotations (which already say this is a write, idempotent, non-destructive), the description adds that memory is 'scoped by your identifier' and that anonymous sessions only retain data for 24 hours, which is critical behavioral context. This aligns with annotations and enriches the agent's understanding of side effects.

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: a single opening sentence stating the core function, then a usage clause, then storage details, then a pairing tip. No redundant phrasing; all sentences add 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?

For a simple 2-param tool with no output schema, this description covers the essential purpose, usage context, persistence behavior, and companion tools. It is fully sufficient for an agent to understand when and how to use it.

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

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

Schema coverage is 100% with clear descriptions and examples for both key and value, so the baseline is 3. The description adds minimal parameter-level detail beyond noting the key-value structure, though the usage examples implicitly show how parameters map to real tasks. No further elucidation is needed.

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 'Save' and identifies the resource as 'data the agent will need to reuse later,' clearly distinguishing this as a memory write operation. Examples like 'resolved ticker' and 'target address' illustrate concrete uses, and mentioning recall/forget as companions differentiates it from sibling tools.

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

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

Explicit usage guidance is given: 'Use when you discover something worth carrying forward...' This tells the agent when to invoke it, and the pairing with recall/forget indicates when to use alternatives. The mention of persistence for authenticated vs anonymous sessions also helps decide when relying on memory is safe.

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

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

Annotations indicate read-only, open-world, idempotent operations. The description adds substantial context: sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), handling of unresolved identifiers, graceful degradation, and internal cascading of multiple lookups. 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?

Although long, every sentence adds operational value. The description is front-loaded with examples and purpose, uses clear labels (SUPPORTED TYPES), and avoids redundancy with schema or annotations.

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 complex multi-source resolver with no output schema. The description covers inputs, returned identifiers, source labeling, unresolved handling, and failure modes, making it sufficiently complete 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?

Schema already documents both parameters with 100% coverage, but the description enriches semantics by specifying valid inputs (ticker, CIK, name; brand vs generic) and what each entity type returns. This goes beyond the schema's basic descriptions.

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

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

The description opens with concrete example queries and precisely defines the tool as resolving a user-spoken NAME to canonical/official identifiers required by other tools. It clearly distinguishes itself from siblings like compare_entities and entity_profile by focusing on identifier resolution.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It doesn't mention specific when-not-to-use scenarios or alternatives, but the unique role among siblings is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral details beyond annotations: it reveals the tool internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This is richer than the typical annotation baseline and helps the agent anticipate side effects like sub-tool invocations.

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

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

The description is three sentences, front-loaded with the primary action, and includes a concrete usage example in quotes. Every sentence contributes information: what it does, how it works (sub-probe and ranking), when to use it, and what it returns. No redundancy or filler.

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

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

The tool has 4 parameters, 1 required, and no output schema. The description covers the core function, return format (ranked list with score, confidence, signal density), and the sub-tool dependency (ai_visibility_check). It also provides a use-case context. Missing are details about rate limits or cost implications of the sub-probes, and it doesn't mention required entity count (2-8) but that is in the schema. Overall, it is sufficiently complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so parameter semantics are already fully documented. The description adds little beyond the schema: it mentions 'your brand + N competitors' which loosely aligns with the entities parameter, but the schema already specifies the first entry as the 'subject.' Since the schema carries the parameter documentation burden, the description adds no significant new meaning, warranting the baseline score 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 opens with 'Compare AI visibility across multiple entities side-by-side,' which clearly states the specific verb (compare), resource (AI visibility), and scope (multiple entities). It also explicitly distinguishes itself from the sibling tool ai_visibility_check by noting it probes each entity and ranks scores, 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 provides an explicit use case: 'Useful for competitive AI-marketing audits' with a concrete example ("does Claude know about us as well as our competitors?"). It implies multi-entity comparison but does not explicitly mention alternatives like compare_entities or exclude single-entity checks, so while context is clear, explicit when-not guidance is missing.

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 rich behavioral context beyond annotations: it fans out across multiple sources, handles partial failures gracefully, notes potential 5-30s latency on bundlephobia's first measurement, and mentions the sources_failed field. These details complement the readOnly/idempotent/non-destructive hints without contradicting them.

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

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

The description is dense but every sentence earns its place: purpose, use cases, return fields, ecosystem scope, and failure behavior are all covered without redundancy. It is front-loaded with the core purpose and organized logically, making it easy to parse despite its length.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: summary block fields, per-advisory details, links, alternative versions, and failure behavior (sources_failed). It also explains ecosystem scope and fallback, making the tool's behavior comprehensive for the 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%, so the baseline is 3. The description adds context around the version parameter (e.g., new versions may require a first measurement) but does not add further semantic meaning beyond what the schema already provides for both 'package' and 'version'.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project' in one call. It specifies the resource (npm package), the data sources (deps.dev, bundlephobia), and the scope (NPM ecosystem only), distinguishing it from sibling tools like scan_competitor_ai_presence and from direct deps.dev usage for other ecosystems.

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 excludes non-npm ecosystems by directing users to deps.dev:version directly, giving a clear alternative and when-not-to-use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is known. The description adds valuable behavioral details beyond annotations: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and every result includes an offset for quote verification.

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

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

The description is compact but dense, front-loading the core purpose in the first sentence. It earns its length by covering usage, behavior, and pairing in a single structured paragraph.

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 fulfills the burden by explaining the return format ('top-N passages with character offsets and similarity scores') and mentioning truncation behavior. It also covers usage context and parameter constraints, making it complete for an AI 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 some context (e.g., text being a 'SEC 10-K body' or 'long tool result') and explains the query as natural language, but the schema already covers the parameters well, and the description doesn't add significant new 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?

Description clearly states 'Semantic search INSIDE a fetched record' with a specific verb+resource. It details the output (top-N passages with character offsets and similarity scores) and distinguishes from sibling tools by focusing on searching within already-fetched text.

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 the record is too big to cram into the prompt.' Also gives an alternative/partner: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear usage context and relationship to alternatives.

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

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

The description adds valuable behavioral context beyond annotations, such as the OAuth requirement, phone verification for SMS, and the 10/day cap. It also explains delivery channels and how to access the feed. However, it omits the webhook option (which appears in the schema) and does not clarify idempotency semantics beyond the annotation, but the annotation already covers safety and idempotency.

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

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

The description is fairly long but well-structured: it starts with the main purpose, then required auth, supported types, and delivery channels. Each section is informative without being redundant. It could be slightly more concise, but the density 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?

Given the complex schema (nested objects, 3 params) and 100% schema coverage, the description covers the essentials: purpose, auth requirement, supported types with examples, and delivery options. It omits webhook from the description text, and it doesn't mention all five types (patent_grant and clinical_trial are missing), but the schema fills these gaps. The description is sufficiently complete for the 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 schema already has 100% coverage with detailed examples for each type, but the description adds extra semantic meaning, such as 'items:["5.02"] = officer change' and explaining 'polymarket_edge' as cross-venue mispricings. While not all types are repeated in the description, it enriches understanding of the ones it does mention.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream' and mentions the return of a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by emphasizing proactive monitoring. The supported types further specify the resource.

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 by stating the requirement for a Pipeworx OAuth account and explicitly notes alternatives for reading alerts (feed always on, pull via recent_alerts). While it doesn't explicitly say 'when not to use,' the prerequisites and alternative access implied are sufficient. It does not mention all use cases vs alternatives, but the guidance is helpful.

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 behavioral context beyond annotations by explaining that results are drawn from a 'live catalog of thousands of tools' and that the output includes 'the exact tool + argument shape' for each suggested question. It also clarifies the two invocation modes (no-args vs topic). Annotations already declare readOnly and idempotent, so the bar is lower; the description adds useful specifics without any contradictions.

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

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

The description is a single dense paragraph that front-loads example user questions before explaining the tool's purpose and usage. While comprehensive, it is somewhat long, and the opening question list slightly overlaps with the title. Still, every sentence adds useful information, so it is concise enough.

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

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

Despite having no output schema, the description tells the agent exactly what to expect: a spread of category-bucketed example questions with the tool and argument shape. It covers parameter behavior, when to use, and what the tool is for, making it complete for a simple, read-only tool with strong annotations.

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

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

The schema already documents the `topic` parameter with a full list of allowed values and the default behavior when omitted (100% coverage). The description repeats this and adds minor examples ('finance', 'pharma'), but does not provide significant new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shapes. It uses specific verbs ('Returns', 'Call') and names its resource. It also distinguishes itself from sibling tools by positioning it as the 'first' tool to use when unfamiliar with Pipeworx.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and even lists the meta-tools to learn about. It provides clear guidance on calling with no arguments for a full spread or passing a topic to focus, going beyond implied usage to a concrete directive.

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 critical behavioral details beyond the annotations: the row is deactivated, not deleted, and the historical events remain available via recent_alerts. This adds meaning to the destructiveHint:false annotation and explains the side effect on historical data, which is exactly the kind of value the description should add.

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 short sentences, each adding a distinct piece of information: action, ownership constraint, and post-effect. It is front-loaded with the core purpose, wastes no words, and is easy to scan for an agent.

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

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

For a tool with one parameter, no output schema, and informative annotations, the description covers all essential aspects: what happens to the row, ownership rules, and the relationship to recent_alerts. No important behavioral gaps remain, making it complete for an agent to invoke confidently.

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 the only parameter 'id' fully described as 'Subscription id (uuid) returned by subscribe.' The description doesn't add new parameter semantics beyond the schema; it simply restates that cancellation is by id. Per the rubric, the baseline is 3 when schema coverage is high, and this description doesn't elevate it further.

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

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

The description starts with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe, list_subscriptions, and recent_alerts by stating the exact action and target. It leaves no ambiguity about what the tool does.

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

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

The description provides clear context, including an ownership constraint ('you can only cancel your own subscriptions') and a pointer to recent_alerts for historical events. It doesn't explicitly name alternative tools to use instead, but it implies the correct use case and behavior, which is adequate for a simple unsubscribe action.

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 behavior beyond the annotations: the dual routing path, the full verdict vocabulary (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), and the critical caveat that could_not_verify means the check failed (includes verification_error) and must not be treated as evidence. This adds substantial context that annotations alone do not capture.

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

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

The description is long but every part serves a purpose: trigger phrases, routing examples, verdict list, and important caller warnings. It is front-loaded and structured well, with the 'IMPORTANT for callers' clause emphasizing the critical could_not_verify pitfall. Slightly dense, but no wasted words.

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

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

For a complex tool with no output schema, the description covers the return verdicts, evidence/citation format (pipeworx://), reasoning, and the distinction between could_not_verify and unsupported. It also explains the tolerance override behavior. This gives an agent enough to select and invoke correctly without missing key edge cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for tolerance_pct by explaining its default (implied by claim wording, capped at 5%) and recommending 1–2% for hallucination detection. This goes beyond the schema definitions and justifies an above-baseline score.

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

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

The description opens with concrete natural-language trigger phrases and states 'natural-language claim verification against authoritative sources.' It clearly distinguishes this tool from sibling research/search tools by targeting fact-checking of a user's claim. The specific verb+resource combination is 'verify claim' plus a clear scope of what it does.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates two internal routing paths (SEC EDGAR structured vs grounded pipeline) based on claim type. However, it does not name alternative tools for open-ended research or other contexts, so exclusions are 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.