Discogs

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

The description adds behavioral context beyond the rich annotations (readOnlyHint, etc.): it explains default model, API key requirement for Anthropic, return structure (per-model {score, confidence, signals, raw_response} + combined view), and free/default model. No contradictions with annotations.

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

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

Two sentences that efficiently convey purpose, operation, and value. Front-loaded with key information (what, how, returns, use cases). No wasted words.

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

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

Given 4 parameters, no output schema, and strong annotations, the description covers return values, use cases, and configuration options. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, and the description adds meaning: default model, free vs. BYO key for Anthropic, and purpose of context parameter for disambiguation. Enhances understanding of how parameters work together.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100. It distinguishes from siblings by focusing on AI visibility checks, not general search or entity 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?

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use it or name alternative tools for other purposes.

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

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

The annotations already establish read-only, open-world, idempotent behavior. The description adds valuable behavioral context beyond annotations: it routes to one of 5,767 tools, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It does not contradict 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 most important guidance is front-loaded and the examples are useful, but the description is longer than necessary and contains redundant filler like 'START HERE for most questions — every question, every query, every prompt, every need, every goal, every ask.' Some phrasing also reads as glitchy, which prevents top marks.

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 one-parameter, read-only router tool with no output schema, the description is complete: it covers when to use it, what kinds of questions to pass, concrete examples, alternatives, and the response shape (structured answer with citations). Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the single required question parameter is already documented. The description adds value-semantic guidance beyond the schema: acceptable query types, trigger phrases, and six concrete example questions, which helps the agent formulate the parameter correctly.

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 identifies a specific action: take a natural-language factual/data question, route it to the right source tool, and return a cited structured answer. It also distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell it apart without opening schemas.

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

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

It explicitly says to prefer this over web search for authoritative, structured, cited data and lists trigger phrases like 'what is', 'look up', 'find', and 'current'. It also names alternatives: ask_pipeworx_grounded for quick single-answer questions, deep_research for broad multi-part questions, and notes that breaking news is already covered.

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 carry readOnly/idempotent/openWorld/destructive hints, so the bar is to add context beyond that — and this description delivers richly. It discloses the experimental nature (routing improvements under test), the live-state caveat with a dated retirement, that results feed merge decisions against the stable router, and that it is a full working router with no fallback. This is exactly the behavioral nuance an agent needs to calibrate trust.

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 of roughly 130 words, and every sentence earns its place: identity, current state, usage instruction, merge rationale, and fallback clarification are all load-bearing. The front-loaded first sentence establishes identity and the core experimental trait. Slight deduction for nested parentheticals that make parsing harder than necessary.

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

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

For a tool with rich annotations, full schema coverage, and no output schema, the description covers the only genuinely complex context: what the beta status means, whether behavior currently differs from stable, and how results are used. The only real gap is that the description relies on knowledge of ask_pipeworx's domain function rather than stating it, which is acceptable since that sibling appears in the same toolset.

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 even with no parameter information in the description. The description adds only 'same arguments' referencing ask_pipeworx and gains no credit for the schema already documenting all six aliases (q, text, input, query, prompt) of the required question parameter. Nothing beyond the schema is contributed.

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

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

The description clearly identifies this as the beta/experimental variant of ask_pipeworx — an 'identical universal router' over 5,767 tools — and explicitly differentiates it from the stable ask_pipeworx sibling. It does not independently define what the router does (domain, question types), instead assuming prior knowledge of ask_pipeworx, which is a minor gap given the sibling is listed.

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?

Gives an explicit when-to-use instruction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current neutral state ('No candidate is active right now... this currently matches ask_pipeworx exactly'), which is essential for routing decisions. It implies the stable alternative but does not explicitly state when NOT to use it (e.g., when guaranteed stable behavior is required).

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

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

It discloses the full success payload structure, refusal reasons as an enum, the extra LLM call cost, and the grounding constraint of using only tool contents. This goes well beyond the readOnlyHint and idempotentHint annotations by explaining exactly what the tool returns and when it refuses.

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

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

Every sentence earns its place: purpose, routing, extraction behavior, output contract, use cases, and cost trade-off. The key differentiator is front-loaded, and the refusal contract is compactly enumerated without 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 read-only question-answering tool with no output schema, this is complete. It specifies the exact success and refusal return shapes, explains the routing mechanism, names the cheaper alternative, and covers high-stakes use cases without relying on the schema.

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

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

All six parameters are aliases for the same question field, and the schema already provides 100% coverage, including the natural-language description and alias list. The tool description adds no parameter-level detail, 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 opens with a specific purpose—'hallucination-resistant answer mode for high-stakes reads'—and explains it extracts answers using only tool results. It explicitly contrasts itself with ask_pipeworx, so an agent can distinguish it without opening the sibling.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also tells the agent when not to use it by saying 'prefer ask_pipeworx for casual lookups,' and explains the cost trade-off.

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 substantial behavioral details beyond annotations: low-confidence resolutions short-circuit, closed markets return status, wide-spread markets flag illiquidity, resolver contract with confidence/alternatives, parent_event extraction, news fallback handling, and resolution-rule risk. Annotations already declare readOnlyHint, etc., but the description enriches context significantly. No contradiction.

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

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

The description is long and packed with details, with front-loaded purpose. Every sentence adds value, but it could be more structured (e.g., bullet points for classifiers, fan-out examples). The density may be overwhelming for an AI agent, though it is informative.

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

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

Given no output schema, the description thoroughly covers return shapes (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), resolver contract, parent events, news fallbacks, and resolution-rule risk. It is complete for an AI agent to understand tool behavior without additional documentation.

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

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

Schema coverage is 100% (all 3 parameters documented). The description adds context for 'market' (accepts slug, URL, or text) which aligns with schema, and explains 'depth' and 'include_raw' consequences (quick vs thorough, summarized vs raw). This goes beyond baseline 3 by providing behavioral semantics, though schema already covers basics.

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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). This is a specific verb with resource, and while it doesn't explicitly differentiate from siblings, its unique function is unambiguous.

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

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

The description explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' This provides clear context for when to use. However, it does not mention when not to use or list alternatives, though sibling names imply other betting-related tools.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds details: for company pulls 10-K data with off-calendar handling, for drug pulls FAERS/FDA/trial counts, sorted by primary metric, returns paired data with citation URIs. No contradictions.

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

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

Description is somewhat lengthy but efficient, front-loading core purpose and usage. It packs significant detail (data sources, sorting, output format) without redundancy, though could be slightly more concise.

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

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

Given no output schema, description adequately explains return format (paired data, citation URIs). Covers both entity types, parameters, and edge cases (off-calendar fiscal years). Complete for the tool's complexity.

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

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

Schema coverage is 100% with basic descriptions. Description enriches by specifying entity types (company/drug) with concrete examples (tickers/CIKs, drug names) and constraints (min 2, max 5). This adds meaningful context beyond schema.

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

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

The description explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs, with clear examples of natural language queries. It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, providing clear usage guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds substantial behavior beyond annotations: parallel tool routing across 5,767 tools, gaps[] never invented, contradictions[] for standard/thorough, semantic excerpting, citation_uri only when fetchable, hop field, and latency expectations. It falls short of 5 only because it doesn't detail failure modes or rate limits, but the behavioral disclosure is rich.

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 front-loaded with the most critical operational caveat (ACCOUNT REQUIRED). However, it is quite long and somewhat sprawling, mixing prerequisites, tool mechanics, output format, latency, and alternatives into a single paragraph without clear structural separation. Every sentence earns its place, but structure could be improved with line breaks or bullet-like separation.

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 (5,767 tools, parallel decomposition, paid tiers, citations, gaps, contradictions, latency), the description covers the essential operational context: auth requirement, free/paid tier restrictions, fallback alternative, input type, output packet components, citation resolvability, and latency bounds. No output schema exists, so the description carries the full burden for return-value expectations and does so thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for the depth parameter by explaining what each depth tier actually does (quick=3 single-hop, standard=gap-recovery + contradictions, thorough=paid iterative hop + contradictions). It also frames question as broad/multi-part-friendly. The only small gap is that exact semantics of the depth enum values are partially repeated from the schema, but the description adds behavioral consequences 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 a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in ONE call. It clearly differentiates from open-web search and from siblings like ask_pipeworx and ask_pipeworx_grounded by emphasizing structured data, parallel decomposition, and findings packets with citations.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit when-not-to-use: 'For a single lookup use ask_pipeworx instead' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names the sign-in prerequisite and alternative for non-signed-in users.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining the return format (top-N tools with schemas and examples) and that results are ready to call directly, which annotations do not cover.

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

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

The description is a single paragraph that efficiently communicates purpose, usage, and return value. It is front-loaded with the core action and includes necessary details without redundancy.

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

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

Given the parameter count (6, all documented), no output schema, and the tool's discovery nature, the description fully explains what the tool returns and how to use it, leaving no critical gaps.

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

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

Schema description coverage is 100%. The description further clarifies that multiple alias names (task, q, search, description) map to the query parameter and provides default limit values, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many domains and explains that it returns top-N relevant tools with full input schemas, distinguishing it from sibling tools like search.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set,' providing clear when-to-use and implicitly when-not-to (if the tool is already known).

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

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

The description discloses the full source fan-out, per-source failure behavior (USPTO sunset soft-fail), the expected empty fda_products case, and the meaning of empty sections via sources_used/sources_failed. This complements the readOnly/idempotent annotations and provides failure-mode context annotations cannot express.

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

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

The description is long but front-loaded with user intents and the key routing directive before diving into source/results detail. Every sentence adds operational or failure-mode value for a multi-source tool, though the dense parenthetical style could be tightened.

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 document return values, and it does comprehensively: result sections, URIs, sorting, expected empty cases, and sources_used/sources_failed are all covered. Input handling, edge cases, and failure modes are fully specified, so an agent can 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 coverage is 100% and the schema already documents both `type` and `value`, including interchangeable behavior, accepted shapes, and EDGAR name resolution. The description mostly restates this, with minor additions like person/place coming soon and resolved_from/resolved_to notes; the schema carries the parameter-semantics burden.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme') and explicitly states the tool produces a full cross-source profile of a US public company in one parallel call. It clearly delimits scope to US public companies and distinguishes itself from chaining single-pack lookups.

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

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

It gives explicit trigger phrasing and a direct routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted input shapes and how private companies are handled, so an agent knows when the tool applies.

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 destructive behavior and idempotency. Description adds that it clears saved data but provides no further behavioral context beyond what annotations convey.

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

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

Two sentences: first states action, second gives use cases. No fluff, front-loaded.

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

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

Given one simple parameter and no output schema, description is sufficient. Slight lack of detail on return value, but overall 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 a description for the only parameter. Description adds no extra semantics beyond 'by key'.

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

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

Description clearly states the verb 'Delete' and the resource 'memory by key', distinguishing it from siblings like remember and recall.

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

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

Explicitly describes when to use (stale context, task done, clear sensitive data) and mentions pairing with remember and recall.

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

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

Annotations already indicate safe, read-only, idempotent, non-destructive behavior. Description adds value by detailing the process (fetches page, extracts title/description/links, emits markdown format) and output format (single text blob for site-root/llms.txt), which goes beyond annotations.

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

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

Description is concise (3-4 sentences), front-loads the main purpose, then explains process and use cases without unnecessary words 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 no output schema, description adequately covers return value (single text blob). All parameters and use cases are addressed, providing sufficient context for correct tool selection and invocation.

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

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

Schema covers 100% of parameters with descriptions. Description adds the default value (25) and maximum (50) for max_links, plus clarifying that url should be a full URL, providing extra meaning beyond schema.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with specific use cases. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on the llms.txt file generation.

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

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

Description lists explicit use cases (client indexing, self-drafting, competitor auditing), providing clear context. However, it lacks explicit exclusions or comparisons to alternative tools among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds specific return fields and parameter context, enhancing transparency beyond annotations.

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

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

Two tight sentences with no waste. Front-loaded action verb and resource.

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 get-by-ID tool with output schema, description covers input and output adequately. No missing context.

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

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

Schema coverage is 100%, with description of artist_id matching schema's 'Discogs artist ID'. Adds minimal extra meaning beyond the schema.

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

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

Clearly states 'Fetch a Discogs artist profile by artist_id' with specific verb and resource, and lists return fields. Distinguishes from sibling tools like get_label and get_release.

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?

Implies use when needing an artist profile by ID, but lacks explicit when-to-use guidance or alternatives (e.g., when to prefer search or entity_profile).

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds detail on return fields and confirms read-only nature. 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?

One concise sentence that front-loads the purpose and lists return values. No superfluous 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?

Given the simple parameter and existence of output schema, the description adequately covers the tool's behavior and return value composition.

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

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

Schema coverage is 100% with a description for label_id. The tool description does not add additional meaning beyond the schema, meeting the baseline.

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

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

Clearly states it fetches a Discogs record label profile by label_id and lists returned fields (name, profile, contact info, URLs, etc.). Distinguishes from siblings like get_artist, get_master, get_release.

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?

Does not explicitly state when to use this tool over alternatives or provide exclusions. Usage is implied from the resource type, but no direct guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context about the master's role as a canonical work record, which is useful beyond annotations. No contradictions.

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

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

Two efficient sentences, front-loaded with the purpose. Every word adds value; no redundancy.

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

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

Given low complexity (1 parameter, output schema exists), the description adequately lists key return fields. No additional explanation of return values needed due to output schema.

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

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

Schema coverage is 100% for the only parameter master_id, with a brief description. The tool description adds no further detail about the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Fetch', the resource 'master release detail', and specifies the canonical nature of a master across pressings/editions. It lists return fields, distinguishing it from sibling tools like get_release.

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?

No guidance on when to use this tool versus alternatives (e.g., get_release). Does not mention when not to use or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds that it returns a full set of details but does not disclose further behavioral traits (e.g., authentication, rate limits). Since annotations carry the burden, a score of 3 is appropriate.

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

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

The description is a single sentence that efficiently conveys the tool's output scope. It is front-loaded with 'Full release detail' and uses a colon to list specific fields. No unnecessary words 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 simple retrieval tool with one required parameter and an output schema, the description is complete. It lists the key fields returned, and since an output schema exists, further detail on return values is unnecessary. All essential information is provided.

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 has one parameter (release_id) with a description 'Discogs release ID' and 100% schema coverage. The tool description does not enhance this parameter meaning; it simply lists the output fields. Baseline 3 is justified as the schema already documents the parameter adequately.

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 'Full release detail:' immediately conveying the tool's purpose. It lists specific fields (title, artists, labels, etc.), making it clear what information is retrieved. This distinguishes it from sibling tools like get_artist or get_label.

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 implicitly states when to use this tool: when you need comprehensive release details. It does not explicitly specify when not to use it or name alternatives, but the context from sibling tool names (e.g., get_artist, get_master) provides adequate guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds return field details and the include_inactive parameter, but no behavioral contradictions.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

Despite no output schema, the description lists return fields. Parameter is optional and described. Annotations cover safety. Complete for a simple list tool.

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

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

Schema coverage is 100% with a clear description of the only parameter. Description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Title and description clearly state the tool lists active subscriptions. It lists specific return fields and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly tells when to use and hints at alternatives.

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

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

Beyond the annotations (all false), the description discloses the claim_token return flow, the rate limit ('Rate-limited to 5 per identifier per day'), and that it's free and doesn't count against quota. It also explains the same tool can be re-invoked with the token to check status, which is a non-obvious 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?

Though the description is long, every sentence adds a necessary constraint or context: types of feedback, scope limitation, prompt-paste warning, claim_token mechanics, rate limit, and free/quota info. It is front-loaded with the core purpose and structured logically.

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

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

For a tool with no output schema and no required parameters, the description fully covers the return value (claim_token), the read-later workflow, and the practical limits. This 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 already describes all 4 parameters with 100% coverage, so baseline is 3. The description adds extra meaning by showing the claim_token invocation pattern (`pipeworx_feedback({claim_token:"pwfb_…"})`), and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts, which clarifies the `message` and `context` fields.

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 enumerates the exact feedback categories (bug, feature/data_gap, praise). It also differentiates from sibling tools by scoping it exclusively to tools served by this Pipeworx connection.

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: for bug, feature/data_gap, or praise. It also gives a clear exclusion — 'if the tool came from a different MCP server... file it with that server instead' — and warns against pasting the end-user's prompt, which gives concrete behavioral boundaries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds valuable behavioral details: self-aggregating from CF analytics-engine, no PII, caching policy (5min-1h). 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?

Very concise: one opening sentence defining the tool, followed by bulleted use cases and a note on data source and caching. Every sentence adds value, 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?

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, return values, data source, privacy, caching, and ideal use cases. No 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 covers 100% with enum and description. Description adds the semantic distinction: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides usage context beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over selectable windows, derived from CF analytics-engine with no PII. This is a specific verb+resource that distinguishes from sibling tools like search or ask_pipeworx.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case with demand). Does not specify when not to use, but context is clear enough given sibling list and description. Missing explicit alternatives, but not needed for such focused tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds detailed behavioral context: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (realizable vs theoretical edge), and response structure. 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?

Description is thorough but verbose (multiple paragraphs). However, it is well-structured with clear sections for each mode and additional details. Every sentence adds value; minor redundancy could be trimmed but overall effective.

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

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

Despite no output schema, description explains the response structure (opportunities array, partition_check, fill check) and all edge cases (placeholder filtering, similarity threshold, fill risk). Covers all modes thoroughly. Very complete for a complex tool.

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

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

Schema coverage is 100%, but description greatly expands on each parameter: 'event' expects a slug or URL, 'topic' expects a seed question for cross-event scanning. Explains how they work (walks child markets, checks monotonicity, partition check) and their output differences.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (trending scan, event, topic). This is specific, uses strong verbs, and differentiates from siblings which are unrelated or focus on edges/fill risk.

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?

Clear guidance on when to use each mode: no args for trending scan, 'event' for a specific market (recommended), 'topic' for cross-event scanning. Explains trade-offs like cross-event catching patterns single-event misses, and includes fill check to avoid non-tradeable signals.

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 the description adds beyond that by detailing internal models, caching behavior ('cached 1h at the KV level'), and response diagnostics explaining why segments may be empty. No contradictions with annotations.

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

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

The description is front-loaded with the main purpose and well-structured into segments (model families, response, knobs). It is dense but contains valuable detail, though it could be more concise for quick consumption.

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 thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and all parameter use cases. It covers edge cases like why segments might be empty and caching behavior, making the tool self-explanatory for an agent.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema, e.g., explaining slippage_pp's rationale ('Polymarket has zero trading fees... but bid/ask + thin depth typically eats 20-50bp'), and min_partition_leg_kelly's specific behavior for partition arbs.

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 with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement signals.

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"') and explains the response structure and knobs. However, it does not explicitly mention when not to use it or contrast with siblings, leaving some inference to the agent.

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

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

Annotations declare readOnlyHint and idempotentHint true. The description goes beyond by detailing data sources (daily snapshots), limits (60-day TTL, snapshot enablement start), decay calculation from daily closes not intraday, and that gaps indicate no scan. No contradiction.

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

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

The description is front-loaded with a clear summary and question. It then details args and response structure. While lengthy, every sentence adds value, especially in the RESPONSE section given no output schema. Could be slightly tighter but efficient.

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

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

The description is comprehensive: it explains inputs, output structure (tracked, expired, snapshot_dates), limits, and computation details. With no output schema, the RESPONSE section fully compensates. Annotations provide safety profile.

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 repeats the same information for 'days' and 'window' parameters without adding new semantic context beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical longevity and shrinkage, answering 'how long has this edge existed and is it shrinking?'

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 historical edge analysis but does not explicitly state when to use this tool versus alternatives. No mention of when not to use it or which sibling tool might be more appropriate for current edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so tool is safe and side-effect-free. The description adds behavioral details: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, etc.' and warns about forced directional risk. 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 long but well-structured with labeled sections (SINGLE-MARKET, BASKET) and front-loaded purpose. Every sentence provides value, though minor verbosity exists (e.g., explaining defaults). Could be slightly tighter but overall efficient.

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

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

Given the tool's complexity (dual mode, no output schema), the description comprehensively covers return fields, use cases, and risks. It explains what each mode returns, how to interpret results, and warns about dominant loss mode (unhedged directional position). Complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions. The tool description adds meaning beyond schema: explains single-market vs basket modes, default values, how size_usd is interpreted differently per mode, and auto-detection for side in basket. This adds significant context.

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

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

The description specifies 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and differentiates single-market and basket modes. It explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', distinguishing 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?

The description gives explicit usage context: 'REQUIRES one of market or event', explains when to use (before arb signals or edges above $500), and provides rationale (theoretical overround not capturable, partial fills cause unhedged positions). It lacks explicit 'when not to use', but the guidance is strong.

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

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

With annotations already marking the tool as read-only, idempotent, and non-destructive, the description goes far beyond them by explaining matching methodology, compatibility codes, unverified pairing, fee-model limitations, skipped-leg behavior, and temporal alignment semantics. It discloses that spreads are gross, not net tradeable edges, and that warnings may appear even when pairs are returned. This is exemplary transparency for a complex analytical tool.

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

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

The description is well-organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, codes) and front-loads the core purpose, but it is substantially longer than necessary. Many important details are included, but the enumeration of every compatibility code and flag is verbose and could be condensed without losing meaning. It is dense and structured, yet not concise.

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

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

There is no output schema, so the description correctly carries the burden of explaining return semantics: leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, skipped counters, and low_confidence_pairs. It also covers edge cases like temporal_alignment_unknown versus confirmed-aligned, and explicitly warns that null alignment does not mean aligned. Given the tool's complexity, this is remarkably 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 real value by explaining that topic auto-fetches the matching event on each venue and that the two explicit parameters override the topic-mapped sides. It also enumerates the full topic shortcut list and clarifies that both modes share the same matching and disclosure logic. This raises it above a neutral baseline.

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

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

The description opens with a specific, unambiguous purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by naming its exact two-venue scope and by explaining both the topic shortcuts and explicit pairing modes. The matching logic, output shape, and safety caveats make it unmistakably different from adjacent polymarket_* tools.

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

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

The description clearly defines when to use each mode: topic for pre-mapped macros, explicit ticker/slug for custom pairings, and says both run the identical matcher. It also gives strong operational guidance, such as reading compatibility fields even when pairs are returned and warning that pre-mapped topics are not automatically tradeable. It does not explicitly compare against sibling tools like polymarket_arbitrage, so it stops short of a 5.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds scoping details, the behavior of listing keys when key is omitted, and mention of pairing with siblings. 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?

Three sentences, each serving a distinct purpose: core action, usage guidance, and scoping/companion tools. No unnecessary words.

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

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

Given the simple parameter set, full annotations, and clear sibling relationships, the description provides all necessary context for an agent to use the tool correctly.

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

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

The input schema has 100% coverage for the single parameter 'key' with a description. The tool description adds context about the key's purpose and the behavior when omitted, which is valuable beyond the schema.

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

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

The description uses the specific verb 'Retrieve' and clearly identifies the resource as 'a value previously saved via remember'. It also explains the dual behavior of retrieving a specific key or listing all keys, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It implies when not to use by describing pairing with 'remember' and 'forget', and notes scoping by identifier.

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, non-destructive. Description adds valuable context: mark_read flag behavior, that setting it true makes next call return newer events only, and what each alert contains. No contradictions.

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

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

Four sentences, front-loaded with main action, no fluff. Every sentence adds information: purpose, return fields, filtering, mark_read behavior, and alternative access.

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

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

No output schema, but description covers return fields, parameter usage, polling suitability, and alternative endpoint. Complete for an alert retrieval tool with good annotation support.

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

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

Schema coverage is 100% with descriptions. Description adds meaning by showing usage examples (e.g., 'sec_8k' for type), explaining mark_read effect, and stating default limit. Adds value beyond schema.

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

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

Description clearly states it pulls fired events from subscription feed, lists specific fields returned (source, citation_uri, raw payload), and mentions filtering options. Distinguishes from siblings by focusing on recent alerts and providing an alternative REST endpoint.

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?

Mentions polling works fine and provides an alternative access URL, but does not explicitly compare to sibling tools like recent_changes or search, nor does it state when to avoid using this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds details on sources (SEC, GDELT/GNews, USPTO), the parallel call nature, date format handling, and return structure. 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 well-structured with clear sections, but slightly verbose. However, every sentence contributes meaningful information, so it earns a high score.

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 (multiple sources, fallback, relative dates, no output schema), the description covers sources, behavior, return structure, and advises on typical parameters. It is comprehensive.

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

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

Schema has 100% coverage with descriptions. The description adds value by explaining the `since` parameter's format and providing a typical recommendation ('30d' or '1m'), and clarifying the `value` parameter accepts ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company in a time window, listing example queries and distinguishing it from entity_profile. It uses specific verbs and resources.

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 guidance on when to use this tool (e.g., 'what's new with X') and when not to (use entity_profile for static profile). It also explains the fallback behavior between GDELT and GNews.

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 idempotentHint=true. Description adds scoping by identifier, persistence duration (24hrs for anonymous, permanent for authenticated), which is valuable beyond annotations.

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

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

Four sentences, front-loaded with core purpose, no redundancy. Every sentence adds value.

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

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

Covers all needed aspects: purpose, usage cues, persistence behavior, and relation to sibling tools, despite no output schema.

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

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

Schema has 100% coverage, but description provides concrete examples for key (e.g., 'subject_property') and value ('findings, addresses'), adding meaning beyond the schema's generic 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 states the tool saves data for later reuse, with clear examples like ticker, address, preference. It distinguishes from siblings 'recall' and 'forget'.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, but does not provide when-not-to-use exclusions.

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

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

Beyond the read-only/idempotent annotations, the description discloses substantial behavior: internal cascading lookups that replace 2-3 manual lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via figi_candidates, explicit unresolved identifiers, and source-labelled results. 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 dense and purpose is front-loaded with the example query patterns and the 'Use FIRST' trigger. Some redundancy with the schema exists, but the extra length is earned by the tool's complexity and edge cases.

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

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

Even without an output schema, the description explains return semantics (canonical IDs with source labels, figi_candidates on ambiguous matches, explicit unresolved list) and failure modes (degraded LEI/FIGI enrichment). It covers supported types, input constraints, fallback behavior, and the multi-lookup nature, making it sufficient for correct invocation.

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

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

Schema coverage is 100%, but the description adds meaningful parameter nuance: concrete input examples (AAPL, 0000320193, ozempic) and the critical bond-issuer caveat that the full noun phrase must not be passed. It enriches the schema rather than repeating it.

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 exact operation: resolving user-spoken names to canonical/official identifiers, illustrated with concrete verbs and resources (ticker, CIK, LEI, RxCUI). It distinguishes supported entity types (company vs drug) and clarifies that the result feeds other tools requiring these identifiers. This makes the tool's role unmistakable.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' which is actionable guidance for an agent. It does not explicitly name sibling tools or state when NOT to use it, though the tool's niche is clear enough that exclusion is mostly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific fields (score, confidence, signal density). 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 extremely concise (2 sentences plus a short example sentence) and front-loaded with the core purpose. Every sentence adds value with 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?

Despite no output schema, the description comprehensively explains the return format (ranked list with score, confidence, signal density). All parameters are covered, and the use case is clearly articulated. The description is complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and that models and context parameters are optional. It also clarifies the role of the _apiKey parameter.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes itself from sibling tools like ai_visibility_check (single probe) by emphasizing the comparative, multi-entity aspect.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implicitly guides against using for single entities (use ai_visibility_check instead), but lacks explicit when-not-to-use or alternative references.

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, not destructive. Description adds critical context on partial failure (graceful degradation, 5-30s timeout for bundlephobia first measurement, sources_failed field) and return structure.

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

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

Dense single paragraph front-loads purpose. Every sentence adds value, though slightly long. Could be broken into two sentences for readability.

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 comprehensively details return fields (summary, advisories, links, alternative versions) and handles edge cases (partial failures, timing). Complete for agent decision-making.

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

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

Schema already covers both parameters fully (100% coverage). Description adds useful context: scoped package acceptance and default version behavior, enhancing schema meaning.

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

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

The description clearly states the composite one-call check for npm package evaluation, specifying the exact resources (deps.dev, bundlephobia) and outputs. It distinguishes itself from siblings by being the only npm dependency scanner.

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 ('is X safe / popular / small') and when not ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds that it searches multiple Discogs entity types and supports many filters, providing behavioral context beyond annotations without contradiction.

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

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

Two sentences: first establishes purpose and scope, second enumerates filters. Every word earns its place; no redundancy.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers what the tool does and its primary filters, leaving no critical gaps for an agent to misunderstand.

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

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

Schema coverage is 100% with descriptions for all 12 parameters. Description lists many filters but adds no new meaning beyond what the schema already provides; examples are helpful but not essential.

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

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

Clearly states 'Full-text search across Discogs (releases, masters, artists, labels)' with specific verb and resource, distinguishing it from sibling search tools like 'search_within' which target different scopes.

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

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

Lists many filters indicating typical usage, but does not explicitly state when to use this tool versus alternatives like 'search_within' or 'deep_research'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable technical details: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), and character limit (200K chars with truncation and flagging). 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, well-structured paragraph that front-loads the purpose. All sentences add value, including examples and technical details. It could be slightly shorter but remains efficient.

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

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

Despite no output schema, the description explains the return format (passages with offsets and similarity scores), the truncation behavior, and the pairing with a sibling tool. For a tool with three parameters and moderate complexity, this is thorough and 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 parameters are already well-documented. The description adds minor context (e.g., natural-language query examples, default limit of 5) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and output details (top-N passages with offsets and scores). It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by explaining the pairing relationship.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt — search_within saves context'. It also provides integration guidance with 'ask_pipeworx_grounded'. However, it does not explicitly state when not to use the tool.

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

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

Description adds behavioral details beyond annotations: returns subscription id, requires OAuth, SMS rate limit (10/day), webhook auto-disable after 10 failures. 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?

Concise yet comprehensive; first sentence summarizes, then types and delivery options are clearly separated. Every sentence adds value.

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

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

Covers return value, prerequisites (OAuth), constraints (phone verification, rate limits), and all parameter details. No output schema needed.

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

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

Input schema has 100% coverage, but description adds rich examples and constraints for each type and delivery channel, significantly enhancing understanding.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies return value. It distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Description provides context on when to use: requires OAuth account, lists subscription types with examples. Lacks explicit when-not-to-use but alternatives are implied.

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

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

Annotations already indicate safe, idempotent, and non-destructive behavior. The description adds context about the return format (category-bucketed examples) and usage (no arguments for full spread, topic for focus). 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 somewhat lengthy but well-structured. It is front-loaded with examples, then explains the return format and usage. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers its purpose, usage, and expected output. It also mentions the underlying catalog, 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 coverage is 100%, and the description adds significant meaning: it explains the topic parameter is optional, lists possible values (finance, pharma, etc.), and describes the effect of omitting it (cross-category spread). This goes beyond the schema's minimal 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 returns category-bucketed example questions to help users know what to ask. It uses specific verbs like 'returns' and 'call with no arguments', and distinguishes itself from siblings by positioning it as an onboarding entry point, mentioning other meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It provides clear context for when to use it, though it does not explicitly state when not to use it. The mention of alternatives is implied but not exhaustive.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable context: ownership enforcement, row deactivation (not deletion), and availability of historical events. No contradictions.

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

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

Two sentences: first states the core purpose, second adds critical behavioral details. No wasted words, and key information is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers purpose, ownership constraint, side effects (deactivation), and spin-off (historical events in recent_alerts).

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 'id' parameter already well-documented as a UUID from subscribe. The description adds no further semantic detail beyond referencing 'by id', so baseline 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and resource 'subscription by id', with additional context on ownership and deactivation. It effectively distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies that ownership is enforced, implying only self-owned subscriptions can be canceled. It hints at usage context by noting historical events remain available via 'recent_alerts', but does not explicitly compare with sibling tools.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavioral depth: the structured SEC EDGAR fast path vs grounded fallback, the exact list of verdicts, the meaning of 'could_not_verify' (including the verification_error structure and the explicit instruction not to treat it as evidence), and the distinction between 'unsupported' and 'could_not_verify'. This goes well beyond the annotations.

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

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

The description is longer than typical, but every sentence earns its place: it front-loads the core purpose, then provides critical usage details and return-value semantics. The extended list of query phrasings is a bit redundant but helps ground the natural-language scope. It is well-structured and not bloated with boilerplate.

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 carries the full burden of explaining return values. It does this comprehensively: verdicts, grounded/structured actual values, pipeworx:// citations, reasoning, and the error semantics for could_not_verify. It also covers the two major claim categories, making the tool's operational envelope clear. This is complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides for 'claim' and 'tolerance_pct'. It gives rich examples of claim inputs, but those are illustrative of the concept, not additional parameter documentation. The tolerance_pct behavior is fully in the schema, and the description only implies percent-delta math without connecting it to the parameter.

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

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

The description clearly states the tool's purpose with specific verbs: 'natural-language claim verification against authoritative sources', and provides numerous example phrasings like 'fact check' and 'verify the claim that…'. It also distinguishes itself from siblings by specifying the two verification pathways (SEC EDGAR for company-financial, grounded pipeline for anything else), making it unambiguous.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further explains the alternative/replacement nature by noting it 'Replaces 4–6 sequential calls…', giving clear context for when this tool is preferred over a multi-step approach. Conditions for both financial and non-financial claims are laid out.

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