artic

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

The description discloses important behavioral details beyond the annotations: the default model (Workers AI Llama-3.3-70b) is free, while probing Anthropic requires a BYO key and direct billing. It also outlines the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is especially valuable given the absence of an output schema. No contradiction with the annotations.

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

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

The description is three concise sentences, with each earning its place: the first states the core function and scoring; the second covers models and cost; the third reveals the output structure and use cases. There is no fluff, and the most important action 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 moderate complexity (4 parameters) and no output schema, the description covers the essential aspects: what it does, the models available, the cost implications, the return format, and use cases. It does not explain how to interpret the visibility score (e.g., what high vs. low means) or potential limitations of LLM knowledge, but these are minor in context of the strong overall coverage.

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

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

Schema description coverage is 100%, so all parameters already have descriptions. The tool description adds extra meaning by explaining that _apiKey is for Anthropic and that you pay Anthropic directly, which the schema does not mention. It also says 'Omit for just workers-ai', providing practical guidance beyond the formal parameter description.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It uses a specific verb ('Probe') and resource ('one or more LLMs'), and the use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) help distinguish it from siblings. However, it does not explicitly name or contrast an alternative sibling, so it stops short of a 5.

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

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

The description provides explicit use-case guidance: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies when the Anthropic model is used (when _apiKey is passed) and that the default Workers AI model is free. It does not list when not to use the tool or contrast with specific siblings, which would earn a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by explaining the internal routing behavior ('Routes the question to the right one of 5,501 tools'), the output format ('structured answer with stable pipeworx:// citation URIs'), and operational characteristics ('works on every tier, one fast call'). This adds valuable context not captured in annotations.

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

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

The description is longer than average but well-structured: it opens with a strong directive ('PREFER OVER WEB SEARCH'), provides triggers, examples, alternatives, and ends with a summary. While some redundancy exists (e.g., reiterating 'START HERE'), the length is justified given the tool's broad scope and the need to guide agents away from web search. It's front-loaded with the most critical usage guidance.

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 (routing to 5,501 tools), the description is remarkably complete. It covers what the tool does, when to use it, how it differs from alternatives, example queries, and what the return format looks like. Combined with strong annotations and a fully described parameter schema, the description leaves little ambiguity 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% (all parameters are aliases for 'question'), and the schema itself explains each alias. The description enriches this by providing example queries and emphasizing that the parameter accepts natural language requests, which helps the agent formulate effective input. It does not explain syntax or formatting, but the schema already handles that.

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

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

The description clearly states the tool's function: routes questions to one of 5,501 tools across 1,441 sources and returns structured answers with citations. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by naming them and outlining their different use cases.

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 guidance on when to use this tool (for factual questions about real-world data, triggered by phrases like 'what is' or 'look up') and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It even gives concrete examples of valid queries.

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

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

Annotations already mark read-only, open-world, idempotent, and non-destructive. The description adds valuable context: beta status, live candidate routing, fallback guarantee ('Falls back to nothing — this IS a full working router'), comparison against the stable router, and response-shape parity. 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?

Four sentences front-load the tool's identity and current status. Some repetition exists ('identical universal router' and 'matches ask_pipeworx exactly'), but each sentence contributes useful context about behavior and usage.

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

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

Despite no output schema, the description fully covers what the tool is, its current behavior, how to use it, and its fallback nature. The reference to the same response shape as ask_pipeworx provides sufficient output expectations, and the annotations fill safety/behavioral gaps.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for question. The description adds only a generic 'same arguments' reference and no additional parameter-specific semantics, matching the baseline for high schema coverage.

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

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

Description opens with 'Beta version of ask_pipeworx' and states it is an identical universal router with the same 5,501 tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling ask_pipeworx by highlighting candidate routing improvements and its experimental edge.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that with no active candidate it currently matches ask_pipeworx exactly. However, it does not mention when not to use it or differentiate from ask_pipeworx_grounded.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds substantial context beyond annotations: the refusal reason enum, return field list with verbatim evidence, the fact that it only uses tool result content, and the extra LLM call cost. 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 dense but every part earns its place: purpose, routing, extraction behavior, success/refusal shapes, usage contexts, and cost trade-off. It is front-loaded with the core purpose and structured with hyphens and code blocks for scannability. No filler.

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

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

Although there is no output schema, the description fully specifies the return shape on success and all refusal reasons. It also explains the internal routing pipeline, the high-stakes use cases, and the cost comparison with ask_pipeworx. For a moderately complex tool, this is complete.

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

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

Schema coverage is 100% (all six parameters are documented aliases for the natural language question). The description doesn't add parameter-level detail beyond saying 'question in natural language,' but the schema already fully covers this. Baseline 3 is appropriate since description adds no new param semantics.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but then explaining the key difference: extraction from tool result only, with explicit refusal behavior.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups,' plus a cost trade-off: 'Costs one extra LLM call vs ask_pipeworx.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description goes far beyond by disclosing the resolver contract (confidence levels, alternatives, suggestions), blocking statuses (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity, cancellation-rule parsing, news fallback behavior, and a warning about flat-50¢ void settlements being a recurring pure-rules loss. 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 lengthy but meticulously structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable. It front-loads the core purpose and then layers details. While some sections are dense and could be trimmed, the structured format justifies a 4 rather than a 3.

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 carry full responsibility for explaining what the agent receives. It covers response shapes, market_match_confidence, parent_event extraction, news fallback fields, safety suppression, and cancellation-rule risk. This is an exceptionally complete description for a complex tool, leaving minimal ambiguity about behavior and output.

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 each parameter is already well-documented. The description adds some context like input formats (slug/URL/question) and the depth behavior, but these largely mirror schema examples and descriptions. It does not fundamentally enrich parameter semantics beyond what the schema already provides, warranting the base score of 3.

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

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

The description opens with a specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by listing the input types (slug, URL, question text) and the resulting evidence packet with market-vs-model comparison. The classifiers and fan-out examples further concrete the scope.

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

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

The description explicitly states when to use this tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives fan-out examples for different categories, showing context. It does not explicitly list when not to use it, but the guidance is clear and actionable.

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

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

Despite annotations already declaring read-only/idempotent behavior, the description adds substantial non-obvious details: data source (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the inclusion of pipeworx:// citation URIs. These traits go 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?

The description is dense but well-organized, starting with trigger phrases and the core action, then diving into type-specific details and output behavior. Every sentence adds value, though it is longer than typical; the length is justified by the richness of information.

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

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

Given the tool has no output schema, the description covers return format, sorting, scope, and data sources comprehensively. It also addresses edge cases like off-calendar fiscal years, making it fully self-contained for an agent to invoke correctly.

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

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

Although schema coverage is 100%, the description adds critical meaning by explaining what each type ('company' vs 'drug') actually retrieves, including specific metrics (revenue, net income, adverse events). It also specifies list constraints and gives concrete examples, which the schema alone does not provide.

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

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

The description clearly states a specific verb ('compare') and resource ('2–5 companies or drugs') with a single parallel call. It distinguishes itself from sibling tools by giving trigger phrases and noting it replaces sequential lookups, making the purpose unmistakable.

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

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

Explicitly states when to use it ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides natural-language triggers ('Compare X and Y', 'rank these companies'). It also differentiates behavior by entity type, leaving no ambiguity about 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 readOnly/idempotent annotations, the description discloses account/paywall requirements, parallel decomposition, hop-based gap recovery, contradictions[], citation resolvability via pipeworx:// URIs, semantic excerpting, and expected latency (15-90s). It also explicitly states this is not open-web search, setting correct expectations. 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; the account requirement and tool alternatives are front-loaded, and every section adds operational detail (citations, gaps, latency, excerpting). A small amount of redundancy exists around ask_pipeworx use cases, but overall the length is justified by the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], hop field, and excerpting behavior. It also covers prerequisites (account) and limitations (structured catalog only, not live news).

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

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

The schema already documents both parameters with 100% coverage, but the description adds substantial meaning: it explains how depth values (quick/standard/thorough) affect hops, gap recovery, follow-up research, contradictions, and paid access, and clarifies that question accepts broad natural-language multi-part queries. This goes well beyond the enum strings.

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+resource ('Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources') and explains the tool decomposes a question into facets and routes them in parallel to 5,501 tools. It clearly distinguishes itself from siblings like ask_pipeworx and from open-web search, so there is no ambiguity about what it does.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data; alternative tools are named for single lookups (ask_pipeworx), breaking/current news (ask_pipeworx), and unsigned-in users (ask_pipeworx). It also explains depth-tier behavior, making selection easy.

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 and idempotentHint. The description adds valuable behavioral details: returns top-N tools with full schemas and curated examples, 'ready to call directly, no second schema lookup needed', 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?

Three sentences with a clear flow: purpose, usage context with domain list, and return value. The domain list makes it slightly long, but every part earns its place.

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

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

No output schema exists, so the description compensates by stating exactly what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also explains when to use it, making it contextually complete.

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

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

Schema description coverage is 100%, and the description does not add significant parameter-specific meaning. The 'top-N' detail is mentioned, but the schema already documents the limit parameter and aliases.

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 'Find tools by describing the data or task', which clearly states a specific verb+resource. It distinguishes itself from sibling data-searching tools by emphasizing discovery of tools themselves, not data.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and adds 'Call this FIRST when you have many tools available'. This gives clear context and a directive, though it doesn't name specific alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: the USPTO PatentsView API sunset with soft-fail behavior, GDELT→GNews fallback chain, and fan-out across multiple sources. It also specifies return structure, such as latest 10-K fundamentals sorted by period_end. This adds significant context without contradicting the annotations.

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

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

The description is longer than typical but every sentence serves a purpose: usage examples, explicit priority, return details, and constraints. It is well-structured with semicolons and a clear return list. It earns its length given the complexity of the tool.

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

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

With no output schema, the description takes full responsibility for explaining return values, and it does so comprehensively: cik, company_name, recent_filings, fundamentals, patents, news, and LEI. It also covers input constraints and fallback behaviors, making the tool fully self-contained for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the ticker/CIK examples and the 'names not supported' note already present in the schema but adds no new parameter-specific semantics. It does provide usage context and constraints, but the schema already does the heavy lifting.

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 a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chained SEC/XBRL/news lookups and aligns with examples like 'Tell me about X' and 'brief me on Tesla.' This makes it unmistakable what the tool does and how it differs from alternatives.

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

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

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

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

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

Annotations already declare destructiveHint and idempotentHint. The description adds context beyond annotations by specifying what gets destroyed ('previously stored memory') and why it might be used ('clear sensitive data'), which is meaningful behavioral context for a delete operation.

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: two sentences that deliver purpose, usage context, and relationship to siblings. Every sentence earns its place with no redundancy or filler.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, usage, and tool relationships. The annotations handle safety aspects (destructive/idempotent), so the description is complete without needing to explain return values.

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 parameter 'key' is clearly described as 'Memory key to delete' in the schema. The tool description also mentions 'by key', reinforcing the parameter's meaning without adding substantial new semantics beyond the schema.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by naming the specific operation (delete) and the resource (memory key).

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

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

Provides explicit conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and names the sibling tools to pair with ('remember and recall'), giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds process context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also states the output shape, exceeding what annotations alone provide.

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

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

The description is three sentences, front-loaded with the core action, followed by process and use cases. Every sentence delivers value with no redundancy.

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

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

The description fully covers the tool's purpose, process, output format, and use cases. Output schema is absent, but the description explicitly states the output is 'a single text blob ready to drop at site-root/llms.txt,' which is sufficient. Annotations cover safety, and schema covers parameters.

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

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

Schema coverage is 100% with clear descriptions for both url and max_links. The description only adds 'for any URL,' which is already in the schema. No additional parameter semantics are provided, so baseline 3 applies.

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

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

The description uses a specific verb+resource ('Generate a production-ready llms.txt file for any URL') and clearly states the outcome ('so AI crawlers can index the site cleanly'). It distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by naming the exact deliverable and format.

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 'Useful for:' scenarios including getting a client's site indexed, drafting llms.txt, and auditing competitors. It does not explicitly name alternative tools or state when not to use it, but the use cases give clear context.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context about what specific data is returned (name, dates, bio, artwork IDs), going 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?

A single, direct sentence that promptly states the resource, scope, and return content without any filler or redundancy.

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

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

With one well-defined parameter, an output schema, and comprehensive annotations, the description covers all necessary context. It is complete and unambiguous for an agent to invoke.

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 parameter 'id' is fully described in the schema as 'ARTIC artist ID', and the description simply repeats 'by ID' without adding new semantic information. Schema coverage is 100%, so the description does not need to compensate.

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 gets an artist's biography and artworks by ID, which is specific and distinguishes it from sibling tools like get_artwork and get_exhibitions.

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

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

The phrase 'by ID' implies when to use the tool (when you have an artist ID), but it does not explicitly mention alternatives or when not to use it, lacking the clear differentiation of a 4 or 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by enumerating the exact return fields (title, artist, date, medium, dimensions, description, credit line, and high-resolution image), which gives the agent concrete expectations about the tool's output 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 two concise sentences that are front-loaded with the core purpose, followed by a clear list of returned fields. Every word earns its place, with no fluff or repetition. It is efficient and well-structured for quick parsing.

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

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

The tool has only one parameter and an output schema exists, so the description does not need to explain return formatting. The description adequately covers what the tool does and what it returns for a simple get-by-ID operation. It lacks mention of error cases or special behavior, but given the simplicity, this is not a significant gap.

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

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

The schema fully describes the single parameter 'id' with an example and type. Schema description coverage is 100%, so the description need not elaborate on parameters. The description only mentions 'by ID,' which reinforces what the schema already states. No additional semantic meaning is provided beyond the structured 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 function: 'Get complete details for an artwork by ID.' It specifies the action (get), the resource (artwork), and the scope (by ID). It also lists the returned fields, making it unmistakably distinct from related tools like get_artist or search_artworks.

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 context by saying 'by ID,' which indicates the caller must have an artwork ID and need full details. While it doesn't explicitly mention alternatives, the specificity of the purpose provides clear context for when to use this tool. No exclusions or alternate tool references are given, but the context is unambiguous for a get-by-ID tool.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: it scopes to 'current and past exhibitions' and describes the return payload (titles, descriptions, status), which helps the agent understand the tool's scope and output.

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

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

The description is two sentences, front-loaded with the main action and resource, followed by return details. Every sentence contributes useful information without redundancy or waste.

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

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

For a simple list tool with one optional parameter, strong read-only annotations, and an output schema, the description provides sufficient context for an agent to select and invoke it correctly. The scope and return content are covered, and no additional behavioral details are necessary.

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

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

The input schema already fully describes the only parameter (limit) with range and default, so the description adds no additional parameter meaning. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Browse') and resource ('exhibitions at the Art Institute'), and further specifies what it returns (titles, descriptions, status). This distinguishes it from sibling tools like get_artist or get_artwork, which target different entity types.

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 browsing exhibitions but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or when to prefer other tools. The purpose is clear enough that an agent could infer when to use it, but explicit guidance is absent.

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 this as safe, read-only, and idempotent. The description adds useful behavioral context: it only returns the caller's own subscriptions, lists the exact fields returned, and implies that inactive subscriptions are excluded by default via the mention of 'active'. This exceeds the annotation baseline without overpromising.

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: the first states purpose and return fields, the second gives concrete use cases. No filler, front-loaded, and every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what is returned, the default scope, and the primary use cases. No critical gaps remain.

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 include_inactive parameter is well-described in the schema itself. The description adds minimal parameter context beyond calling subscriptions 'active', so it doesn't need to compensate. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also enumerates the returned fields, making the purpose concrete and distinguishable from sibling tools like subscribe/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?

The description explicitly advises using this tool to review current monitoring before adding more subscriptions or to find an id to cancel. It implies when to use it relative to subscribe/unsubscribe, though it doesn't name those alternative tools explicitly or state when not to use it.

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

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

Annotations are all false and provide no safety context, so the description carries the full burden. It discloses the claim_token flow, rate limit ('5 per identifier per day'), quota exemption, daily team review, and roadmap impact. No contradiction with annotations exists.

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

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

The description is long but every sentence earns its place—purpose, use cases, exclusions, formatting guidance, token workflow, rate limits, and ROI. It's front-loaded with the core verb and resource, then branches into necessary detail 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?

For a 4-param tool with nested objects and no output schema, the description fully covers purpose, usage, exclusions, message formatting, claim_token lifecycle, rate limiting, and team behavior. It even clarifies what to avoid ('don't paste the end-user's prompt'). Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful param context beyond the schema: it explains the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), suggests message length ('1-2 sentences typical'), and elaborates on the 'type' enum use cases. This extra context pushes it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by explaining it's a feedback channel for Pipeworx tools only, with explicit examples (bug, feature, data_gap, praise). This is unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses meaningful behavioral traits: data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'). This goes beyond what annotations convey and adds valuable context for the agent.

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: it opens with a clear one-sentence summary, then details return contents, then lists three concrete use cases, and ends with technical context. Each sentence earns its place without fluff, and the size is appropriate for the tool's complexity.

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

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

Given the tool's simplicity (one optional parameter, read-only, no output schema), the description covers everything an agent needs: what data is returned, the time windows, the use cases, the data source/privacy, and caching. No critical context is missing.

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

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

The schema already fully describes the 'window' parameter with enum values and semantics. The description adds extra meaning by linking the window to cache freshness ('Cached 5min-1h depending on window') and by reinforcing that shorter windows show recent demand vs. longer windows show steady-state. This exceeds the schema baseline, warranting a 4.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It identifies the resource (Pipeworx usage data) and the action (returns trending info), and it distinguishes itself from siblings by focusing on aggregate agent-call trends rather than individual queries or discovery.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical choices, and alignment checks. It gives clear context on when to use the tool, though it does not explicitly name alternatives or when-not-to-use cases. Since it says 'Useful for' with specific scenarios, it earns a 4 but misses the top score.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description is fully consistent with these. It adds substantial behavioral detail: top ~200 markets by volume, 3pp partition deviation threshold, 0.30 Jaccard similarity anchor, placeholder filter returning null above 20%, and fill-check pricing against live CLOB depth with a clear 'do not trade it' warning. No annotation contradiction.

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

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

The description is long but every section earns its place: mode selection, semantic anchor, partition filter, response shape, and fill check. It is front-loaded with the core purpose and then organized into clearly labeled blocks, making complex information scannable and non-redundant.

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

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

Even though there is no output schema, the description enumerates the response fields (opportunities[], partition_check, fill_check fields) and covers edge cases like low similarity and placeholder-heavy partitions. It also connects to polymarket_fill_risk for custom sizing, making the tool self-contained for an informed agent.

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

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

Schema coverage is 100% with descriptions and examples for 'event' and 'topic.' The description goes beyond this by explaining mode-selection semantics, the default no-args behavior, and providing concrete example slugs and seed questions. This substantially adds operational meaning beyond the structured schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly defines the tool's scope and distinguishes it from siblings by naming its three operational modes and explicitly pointing to polymarket_fill_risk for custom sizing.

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 invocation guidance: no args for trending_scan, 'event' for a specific market, and 'topic' for cross-event scanning. It also recommends when to use each mode. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_kalshi_spread, leaving some ambiguity about when those alternatives would be preferable.

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 is rich in behavioral detail: it explains the response structure (by_segment, fed_candidates, _diagnostics), the edge calculation (net slippage, Kelly), filtering logic (tradeable-edge knobs, placeholder filters), and even the 24h-move warning. It also mentions 'Cached 1h at the KV level keyed on all knobs.' Annotations already indicate read-only/idempotent, and the description aligns without contradiction, adding substantial context beyond the annotations.

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

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

The description is a single dense paragraph with run-on sentences and extensive parenthetical details about model families and filters. While it is front-loaded with the core purpose, the sheer volume of details and lack of structured formatting (bullets, headers) makes it less concise than ideal. It is not excessively verbose for a complex tool with no output schema, but it borders on overwhelming.

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

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

Given the tool's complexity (9 parameters, 3 response segments, no output schema), the description is remarkably complete. It outlines the top-level response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), and explains edge cases like empty segments due to stale data or knob filters. It leaves little ambiguous for an AI agent deciding whether and how to call it.

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

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

Schema coverage is 100%, providing baseline 3. The description goes further by explaining the purpose of the knobs: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also clarifies a subtle interaction (min_kelly not applying to partition arbs) and explains slippage rationale. This adds significant semantic context beyond the parameter descriptions.

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

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

The first sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the use case ('Built for "what should I bet on today"'), which distinguishes it from sibling tools like polymarket_edge_tracker (tracking) and polymarket_arbitrage (pure arbitrage). This is a specific verb+resource+scope.

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

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

The description explicitly frames when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear context for the primary use case. However, it does not explicitly name alternatives or provide when-not-to-use guidance, 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?

The description goes well beyond the annotations by explaining snapshot gaps (written on cache-miss, gaps mean no scan), the 60-day TTL limit on history depth, and that decay numbers are derived from daily closes net of default slippage. This operational context is exactly what an agent needs to interpret results correctly, and it contradicts none of the annotations (readOnlyHint, idempotentHint, destructiveHint false).

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 exceptionally well-structured, with clear sections for purpose, arguments, response format, and limitations. It front-loads the core use case and every sentence delivers actionable information; the ALL-CAPS section headers improve scannability. No filler or redundant phrasing exists.

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 present, the description compensates fully by detailing the response shape (tracked[], expired[], snapshot_dates[]) and the meaning of each field, including edge_pp_net signed convention, trend values, and lifespan/competition clock. It also covers data gaps and TTL limits, giving the agent complete expectations for behavior and results.

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

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

Both parameters are already fully described in the schema: days has default, range, and clamp; window has allowed values and default. The description only restates these defaults and the 'snapshot family' concept, adding no new semantic meaning. Given 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, and immediately addresses the user's underlying question (how long has this edge existed and is it shrinking?). It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence rather than current edge values, though it lacks a direct imperative verb like 'tracks' or 'analyzes'.

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 trading context—'a fresh wide edge and a 3-week-old wide edge are different trades'—which implies when to use this tool (when edge persistence/decay matters before acting). It does not explicitly name alternative tools or list when not to use it, but the use case is clearly differentiated from the current-edge sibling polymarket_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?

Although annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial context: it explains the tool walks the order-book ladder, returns specific metrics like slippage_pp and max_fillable_usd, and warns about forced_directional_risk and thin_legs. This goes beyond the safety profile to explain operational behavior and risk, which is valuable for an agent.

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 run-on paragraph covering both modes, outputs, and usage guidance. It is front-loaded with the core purpose, but the length and lack of paragraph breaks make it less scannable. Every sentence is informative, but structure could be improved with bullet points or mode-by-mode sections, hence one point deduction.

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

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

Given the tool's complexity (two modes, no output schema, multiple return fields), the description is remarkably complete. It lists all key outputs for single-market and basket modes, explains the verdict values, and warns about specific failure modes. It also covers parameter defaults and constraints, ensuring the agent fully understands the tool's behavior without needing additional documentation.

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

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

Schema coverage is 100%, but the description enriches parameter understanding significantly. It clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains the default side behavior and the clamp range, adding semantics beyond the schema's basic type descriptions.

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

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

The description starts with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', clearly indicating the tool's function. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and slippage, not just edge detection. It also enumerates both single-market and basket modes, leaving no ambiguity about its scope.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why, citing the risk of theoretical overround not being capturable on thin books and partial basket fills converting arbs into unhedged positions. This clearly names contexts and excludes small trades, though it does not explicitly mention 'when not to use' beyond the threshold.

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 extensively discloses behavioral traits: compatibility_warning conditions, temporal_alignment flags, skipped_cross_type/subtype counters, and response structure. Annotations already declare read-only/idempotent safety, but the description adds critical caveats about non-equivalent bet shapes and temporal mismatches, which are essential for safe interpretation.

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

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

The description is lengthy but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds substantive value, detailing limitations and edge cases. It could be slightly more compact, but the density is justified given the tool's complexity.

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

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

The description fully covers the tool's input modes, response contents, safety warnings, alignment semantics, and failure conditions. Despite lacking an output schema, it explains exactly what fields (compatibility_warning, temporal_alignment, skipped counters) to expect and how to interpret them, making the tool self-contained.

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

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

Although the schema has 100% coverage with descriptions for all three parameters, the description adds substantial meaning: it explains the interaction between topic and explicit overrides, provides concrete examples for each mode, and lists the exact valid topic values. This goes beyond the schema by clarifying the selection/override logic.

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

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

The description clearly identifies the tool as a cross-venue spread calculator for Kalshi and Polymarket, with a specific verb+resource ('Cross-venue spread'). It also distinguishes itself from sibling tools by focusing on inter-venue price differences rather than within-venue edges or arbitrage execution, and adds scope limitations ('pre-mapped ≠ tradeable').

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 modes ('TWO MODES') with clear instructions on when to use topic shortcuts vs explicit tickers/slugs, and warns about the reliability of pre-mapped topics. However, it does not name specific alternative tools like polymarket_arbitrage or polymarket_edges for comparison, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of listing vs. retrieving. This goes beyond what annotations offer, though it doesn't detail error cases or output format, which is not required for such a simple read tool.

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

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

The description is three sentences with no fluff. The first sentence states the action and modes, the second gives concrete use cases, and the third explains scoping. Information is front-loaded and every sentence contributes value. This is model conciseness.

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

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

For a simple one-parameter, read-only tool with comprehensive annotations and full schema coverage, the description is complete enough. It explains the two call modes, provides usage context, scoping, and related tools. It doesn't specify the exact return format, but 'retrieve a value' and 'list keys' are self-explanatory. With no output schema, a bit more detail on the response could be provided, but the description adequately covers the essential 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?

The input schema already describes the 'key' parameter as 'Memory key to retrieve (omit to list all keys)', providing 100% coverage. The description repeats this behavior ('omit the key argument') and adds illustrative examples of key contents, but does not add technical parameter semantics beyond what the schema states. With full schema coverage, a baseline score of 3 is appropriate.

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

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

The description opens with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly identifies the tool's resource (saved memory values) and differentiates modes. It also distinguishes itself from sibling tools by referencing 'remember' and 'forget' as complements, making its role in the memory lifecycle explicit.

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

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

The description provides strong context for when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also points to alternatives ('Pair with remember to save, forget to delete'), but stops short of explicitly stating when not to use the tool (e.g., for real-time data). This is clear guidance, though 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?

The annotations claim readOnlyHint=true, yet the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the readOnlyHint annotation, making the behavioral guidance inconsistent despite the description's otherwise useful transparency.

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

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

Four sentences, each earning its place: purpose, return characteristics, filtering/read-state behavior, and alternative access. The description is front-loaded with the core action and avoids redundant detail.

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

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

There is no output schema, but the description covers return fields, filtering options, read-state behavior, and even an external URL for scripts. It does not spell out the exact response shape or limit/unread_only semantics, but the schema covers those parameters, and the description provides enough context for practical use.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds concrete meaning beyond the schema by giving an example type ('sec_8k'), clarifying that type and since can be combined, and explaining that mark_read affects subsequent calls (only newer events). This extra context justifies a 4.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb and resource that immediately clarifies the tool's role. It further distinguishes itself from sibling tools like list_subscriptions and recent_changes by describing the returned alerts with source, citation_uri, and raw event payload.

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

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

The description gives clear usage context: filtering by type and/or since, using mark_read to control seen events, and confirming polling works. It also mentions an alternative HTTP endpoint, but it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of 5.

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

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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable operational details beyond that: it fans out to SEC EDGAR, GDELT with GNews fallback on rate limits/5xx, USPTO with a soft-fail caveat due to PatentsView sunset, and it returns changes[] with citation URIs. This is substantial context, though it doesn't cover every edge case (e.g., pagination or empty results).

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 examples and flows logically from purpose to sources to fallback logic, parameters, output, and alternative tool. Every sentence carries necessary information; no filler. Its density is appropriate for a tool with this complexity, though it could be slightly trimmed without loss.

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 multi-source aggregation tool with no output schema, the description covers the full picture: input formats, source-specific fallback behavior, known API caveat (PatentsView sunset), return structure (changes[], total_changes, citation URIs), and when to use an alternative. This is sufficient for an agent to invoke the tool correctly without further clarification.

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 enhances `since` by giving concrete examples of ISO dates and relative shorthands ('7d', '30d', '1y'), and it implies the `value` format through the source list (ticker/CIK). The `type` restriction to 'company' is also reinforced. This added context justifies an above-baseline score.

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

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

The description clearly identifies the tool as a change feed for a company over a recent time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and return format. It also distinguishes itself from entity_profile by explicitly directing users to that tool for static profiles. The verb 'returns' and the concrete examples make the purpose unmistakable.

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

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

The description provides explicit usage triggers through natural language examples (e.g., 'What's new with X') and a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This tells the agent both when to use this tool and when to route to a sibling, meeting the 5-level criteria.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false), the description discloses key behavioral details: key-value storage, scoping by identifier, persistence differences between authenticated (permanent) and anonymous sessions (24 hours). It also tells how to retrieve/delete via sibling tools. No contradiction with annotations.

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

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

Three sentences, logically ordered: purpose, when to use, storage semantics and pairing. Every sentence contributes unique value; no filler or repetition of schema or annotations.

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

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

For a simple two-parameter store with no output schema, the description is complete: it explains what to store, retention behavior, scoping, and how to use it with recall/forget. An agent can confidently invoke this tool without additional context.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds meaning by framing them as 'key-value pair' and giving domain examples (e.g., 'subject_property', 'target_ticker'), reinforcing what to store. This exceeds the baseline without being redundant.

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

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

The description begins with a specific verb+resource: 'Save data the agent will need to reuse later' and clearly distinguishes itself from siblings by naming recall and forget as complementary tools. Concrete examples of keys/values (resolved ticker, target address, user preference) further clarify the purpose.

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives by instructing to pair with recall (retrieve) and forget (delete), making the usage context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds useful behavioral context: it mentions auto-disambiguation for company names and that each call cascades through multiple lookup endpoints internally. This goes beyond the annotations without contradicting them.

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

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

The description is dense but every sentence adds value: usage examples, purpose, supported types with return details, and a note on internal cascading. It is front-loaded with the core use case and structured with clear sections, making it easy to scan without unnecessary padding.

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 moderate complexity (2 params, 100% schema coverage, no output schema), the description fully compensates by explaining return values for each type, citing citation URIs, and describing auto-disambiguation. It provides enough context 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 coverage is 100% and the description enriches both parameters significantly. For 'type', it explains what each enum value returns (ticker+CIK for company, RxCUI for drug). For 'value', it provides input formats, examples (e.g., 'AAPL', 'ozempic'), and clarifies accepted forms. This adds substantial meaning beyond the raw schema.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers. It specifies supported entity types (company, drug) and the exact outputs (ticker, CIK, RxCUI), making it distinct from sibling tools like entity_profile or compare_entities.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use context. It also notes that the tool replaces 2-3 manual lookups, but does not explicitly mention alternative tools or when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows this is a safe read operation. The description adds behavioral context: it probes each entity via ai_visibility_check, ranks results, and returns score, confidence, and signal density—details not present in annotations.

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

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

The description is three sentences with no wasted words. It front-loads the primary action, then explains the mechanism and gives a concrete use case. Every sentence earns its place.

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

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

Given full schema coverage and annotations, the description explains the tool's mechanism (probing sub-calls), output format (ranked list with score, confidence, signal density), and a clear use case. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides (e.g., it references 'your brand + competitors' but schema already explains the entities array). No additional clarification needed.

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

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

The description clearly states it 'Compares AI visibility across multiple entities side-by-side', specifies the mechanism (probes with ai_visibility_check), and differentiates from siblings by focusing on competitive multi-entity comparison. It also explicitly names the underlying tool, distinguishing it from generic comparison 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 provides a concrete use case: 'competitive AI-marketing audits' with an example question ('does Claude know about us as well as our competitors?'), implying when to use this tool over single-entity ai_visibility_check. However, it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavioral context beyond that: composite fan-out across multiple services, graceful partial failures, potential 5-30s latency on first bundlephobia measurement, and the sources_failed field. This is exactly the kind of behavior an agent needs to know.

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, return structure, ecosystem limitation, and failure behavior. It is front-loaded with the most important information and contains no redundant phrasing.

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 compensates by enumerating the exact return fields (is_latest, license, advisory_count, bundle_kb_min, etc.), per-advisory detail, links, and alternative versions. It also covers latency, partial failures, and ecosystem scope, providing a complete mental model for 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?

The input schema already covers both parameters 100% with clear descriptions (package name, scoped packages accepted, version defaults to latest). The description reinforces the npm ecosystem and mentions output fields, but adds no parameter semantics beyond the schema, so the schema-coverage baseline of 3 applies.

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

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

The description opens with a specific composite check purpose ('should I add this npm package to my project') and names its data sources (deps.dev, bundlephobia). It clearly scopes to npm and distinguishes itself from generic dependency tools by mentioning that other ecosystems use deps.dev directly.

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

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

Explicitly provides usage triggers with example queries: 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives an exclusion rule, stating PyPI/Maven/Cargo/Go fall under deps.dev:version directly, which helps the agent choose alternatives.

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

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

The description adds behavioral context beyond the annotations by listing the specific data returned (titles, artists, dates, mediums, image IDs). The annotations already declare the tool read-only, idempotent, and non-destructive, so the description doesn't need to restate those. It does not contradict the annotations, and the extra detail about return content is valuable.

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

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

The description is concise and front-loaded, with two sentences that efficiently convey purpose, return content, and an alternative. Every sentence earns its place, with no redundant or extraneous information.

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

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

The tool has an output schema, so the description isn't required to detail return structures; it already summarizes the fields. Annotations cover the safety profile (read-only, idempotent). The description is sufficiently complete for a simple search tool, though it could mention the limit parameter's default or cap, but that is covered in the schema. It also doesn't reference sibling tools like search_within, but that's not essential.

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

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

The input schema provides 100% coverage for both parameters (query and limit) with clear descriptions. The tool description adds little to parameter semantics beyond reinforcing that the search is by keyword. Since the schema already carries the burden, a baseline score of 3 is appropriate; the description does not enhance understanding of the parameters.

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

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

The description clearly states the tool's function: 'Search the Art Institute of Chicago collection by keyword.' It specifies a concrete verb ('search') and resource ('Art Institute of Chicago collection'), and lists the returned fields (titles, artists, dates, mediums, image IDs). It also differentiates from the sibling tool get_artwork by noting that search is for summary results and get_artwork provides full details.

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: use this tool for keyword searching to get summary information. It explicitly names an alternative ('Use get_artwork to fetch full details'), which indicates when not to use this tool (when full details are needed). However, it does not delve into edge cases or other sibling tools like search_within, so it falls short of a perfect 5.

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

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

Beyond the annotations (read-only, idempotent), the description discloses technical behavior: BGE embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation and flagging. It also states that passages carry offsets for verbatim verification, which is useful for downstream agent reasoning.

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 earning its place: purpose, use case, and technical constraints. No redundant filler or repetition of schema fields.

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

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

The description covers input, output, use case, pairing with another tool, and limitations. Even without an output schema, the agent knows what to expect: passages with offsets and similarity scores, plus truncation behavior for oversized inputs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the text parameter as 'the text you already pulled' with concrete examples (SEC 10-K, article, tool result) and mentions the 200K limit, which directly informs how to use the text parameter. Query examples are also given, enhancing schema semantics.

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

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

The description opens with a specific verb phrase 'Semantic search INSIDE a fetched record' and details the output ('top-N passages with character offsets and similarity scores'). It differentiates itself from siblings by explicitly pairing with ask_pipeworx_grounded and noting it searches inside an already-pulled record rather than a whole document.

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 an explicit trigger: 'Use when the record is too big to cram into the prompt' and names an alternative workflow with ask_pipeworx_grounded. It also explains the benefit (saves context) and how to combine tools, providing clear when-to-use guidance.

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

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

The description contradicts the idempotentHint=true annotation by saying 'Create a proactive monitoring subscription' and 'Returns the new subscription id', implying each call creates a new subscription. This conflicts with the idempotent hint. Because of the contradiction, score is 1.

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

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

The description packs a lot of relevant information into one paragraph, front-loading the purpose and return value. Each sentence adds detail on types or delivery. It could be improved with structured bullets, but it's still efficient and not verbose.

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

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

The tool is complex with nested params and multiple delivery options, and there is no output schema. The description explains the return value (new subscription id), prerequisites, and how to access the feed. However, it omits the webhook delivery option entirely from the main text (though the schema covers it). Given the complexity, the description is fairly complete but has minor gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with concrete examples for three of the five types (sec_8k, polymarket_edge, fred_series) and delivery details like SMS verification and cap. It does not mention patent_grant or clinical_trial in the description text, but those are covered in the schema's params description. So it adds marginal 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?

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and explicitly states it returns the new subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by using the create verb and noting the feed is always on and pulled via recent_alerts.

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

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

It clearly states the account requirement and explicit exclusions (anonymous + BYO), and gives delivery channel options. It implicitly differentiates from list_subscriptions by saying the feed is always on and pulled via recent_alerts, but doesn't explicitly state when to use this vs alternatives beyond that.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds behavioral context beyond annotations: returns category-bucketed example questions drawn from the live catalog, and that each question includes the exact tool + argument shape. This explains the output structure and source without contradicting annotations.

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

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

The description is longer than average but well-structured: it opens with example queries, states purpose, explains output, gives call patterns, and ends with usage guidance. Every sentence serves a purpose, though some example phrasings could be trimmed without losing essential information.

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

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

Given the simple schema (one optional param) and no output schema, the description explains return values thoroughly: category-bucketed example questions with exact tool + argument shape. It also covers when to use, how to call, and what the live catalog provides. No important gaps remain.

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 parameter `topic` is already fully documented with its options. The description merely repeats examples like 'finance', 'pharma', 'betting' that are already in the schema, adding no new meaning or syntax details. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: it suggests questions about Pipeworx capabilities. It clearly distinguishes from siblings like ask_pipeworx by positioning itself as the onboarding entry point that returns example questions with exact tool + argument shape. The categories and meta-tool references make the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains call patterns (no args vs. topic) and contrasts with asking actual questions via meta-tools. This is clear when-to-use advice with context.

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

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

The description adds valuable behavior beyond annotations: ownership enforcement and the soft-delete behavior (deactivated, not deleted) with a rationale (historical events stay available). This goes beyond the readOnlyHint, destructiveHint, and idempotentHint annotations, providing contextual detail that helps the agent anticipate side effects.

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

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

The description is two concise sentences. It front-loads the primary action, then adds ownership and deactivation context. Every sentence earns its place without redundancy or fluff.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and post-condition behavior. It does not describe the return value or error cases, but these are not necessary for a minimal viable description given the tool's simplicity.

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 single parameter 'id', which already documents that it is a subscription uuid returned by subscribe. The description adds no new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('a subscription'), clearly stating what the tool does. It implicitly distinguishes itself from sibling tools like 'subscribe' (creation) and 'list_subscriptions' (listing) by focusing on cancellation.

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

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

The description communicates when to use the tool (cancel a subscription by id) and adds a constraint (ownership enforced). However, it does not explicitly mention alternatives or provide when-not-to-use guidance, so usage context is implied rather than explicit.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds meaningful behavioral details: the internal routing to structured vs grounded sources, the verbatim-evidence-then-judgment mechanism, and the returned verdict types. It also highlights efficiency by replacing multiple calls. It does not discuss latency or external dependencies, but the annotations cover safety.

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

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

The description is moderately long but well-structured: it starts with user intents, moves to usage, then internal behavior, and finally outputs. Each sentence adds value, though the list of example phrasings could be trimmed. It remains efficient given the tool's complexity.

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

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

With no output schema, the description fully explains return values: the verdict categories, the actual value with citation, and reasoning. It also covers the two main execution paths and the default tolerance cap. This is a complete picture for an agent to invoke the tool 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%, so the description does not need to add parameter basics. However, it provides no additional parameter-specific meaning beyond what the schema already offers (e.g., the tolerance_pct semantics are identical in both places). The description helps frame the claim parameter with example phrasings, but that is tool-level context, not parameter depth.

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

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

The description clearly identifies the tool as a claim-verification utility with a specific verb ('validate', 'verify', 'check') and resource ('natural-language factual claims'). It distinguishes itself from siblings by focusing on fact-checking and explicitly listing example user phrasings. The two-path routing (SEC EDGAR vs grounded pipeline) further defines its unique scope.

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

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

It states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also provides specific routing guidance based on claim type (company-financial vs other) and mentions it replaces multiple sequential calls, implying usage as a single-step alternative. This is strong contextual guidance.

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