Nosdeputes Fr

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context beyond annotations: cost implications ('BYO key — you pay Anthropic directly'), the default free model, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). Minor gaps remain (e.g., no mention of rate limits or edge cases with invalid keys), but overall it adds meaningful transparency.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence earns its place. No redundancy or fluff. The format is ideal — it covers purpose, usage, parameters, return values, and use cases efficiently.

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

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

Given no output schema, the description supplies the essential return shape. It covers all parameters (via schema), use cases, and cost behavior. It could go further by defining what 'score' and 'confidence' mean or how 'signals' are derived, but for a read-only probe tool with good annotation coverage, this is sufficiently complete. Slightly more depth on the scoring algorithm would push it to a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the relationship between 'models' and '_apiKey' ('pass `_apiKey` to also probe Anthropic'), explaining the default model, and reinforcing that the key is passed straight through. This incremental semantic value warrants a 4.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's function and distinguishes it from siblings like scan_competitor_ai_presence or compare_entities, which have different scopes (scanning competitor presence vs. probing general LLM knowledge).

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 ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. opt-in model behavior. It does not explicitly state when not to use the tool or name alternatives, 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?

Annotations already establish readOnly/openWorld/idempotent-safe behavior, so the description adds context beyond them: it mentions routing to 5,430 tools, filling arguments, and returning structured answers with pipeworx:// citation URIs. This gives useful operational transparency 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 long but front-loaded with the key 'PREFER OVER WEB SEARCH' directive and contains substantive usage guidance, examples, and alternative references. Some phrasing is slightly promotional ('works on every tier', 'one fast call'), but most sentences earn their place for a catch-all entry-point tool.

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

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

Given the tool's broad scope and the absence of an output schema, the description does a good job explaining input expectations, output style (structured answer with citations), and when to use alternatives. It could be even more complete about output format details (e.g., exact fields or failure behavior), but for a single-question routing tool it is sufficiently comprehensive.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the same natural-language question, so the baseline of 3 applies. The description adds example questions and clarifies that the question can be a request, but it doesn't introduce any meaningfully new parameter detail beyond what the schema already provides.

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

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

The description clearly identifies ask_pipeworx as the default tool for factual, real-world questions with citations, and explicitly differentiates it from sibling tools like ask_pipeworx_grounded and deep_research. It uses specific verbs like 'routes', 'fills arguments', and 'returns' to explain its role, making the purpose unmistakable.

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

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

The description gives explicit preference guidance ('PREFER OVER WEB SEARCH', 'START HERE'), enumerates many concrete use cases with examples, and tells exactly when to escalate to alternatives ('Step up only when needed'). It also addresses breaking-news and multi-part questions, making when-to-use/when-not-to-use very clear.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds crucial behavioral context: beta status, live testing of candidate routing improvements, current inactive candidate, and comparison against the stable router. This significantly enriches the agent's understanding 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?

The description is three sentences, front-loaded with the core identity ('Beta version of ask_pipeworx'). Each sentence adds value, though the inclusion of the specific retirement date and detailed explanation is slightly verbose. Still well-structured and not wasteful.

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

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

Given the tool's complexity (a router with 5,430 tools) and lack of output schema, the description comprehensively covers its current behavior, relationship to the stable version, usage instructions, and even preempts a potential misconception that it might be a fallback. It provides complete context for an agent to use the tool correctly.

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

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

The schema covers 100% of parameters with detailed descriptions and aliases. The description only mentions 'same arguments' without adding semantic meaning, so the baseline of 3 is appropriate; no additional parameter insight is provided.

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

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

The description clearly states that this is a beta version of ask_pipeworx, a universal router with the same 5,430 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by mentioning experimental routing improvements, making the purpose specific and unmistakable.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes the current state (no active candidate, matches stable exactly) and clarifies that it is not a fallback but a full working router, helping the agent decide when to use it 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses internal routing across 5,430 tools, the refusal behavior with specific reasons, and the cost of an extra LLM call. This adds significant context without contradicting annotations.

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

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

The description is dense yet efficient; every sentence contributes unique value—purpose, mechanism, output format, refusal conditions, and tradeoff. It front-loads the core function and avoids fluff.

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

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

Given no output schema, the description fully documents success and refusal return structures, use cases, cost tradeoff, and relationship to sibling tool. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% with all six parameters described as aliases for 'question' and the main parameter documented. The description adds no additional parameter-level semantics, so the baseline 3 applies.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that extracts answers only from tool results, with explicit refusal when data doesn't answer. It distinguishes from sibling ask_pipeworx by highlighting the grounded extraction and provides a precise output/refusal shape.

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 to use when answers will be quoted, cited, or acted on and to prefer ask_pipeworx for casual lookups due to the extra LLM call. This is clear when-to-use and when-not-to-use guidance with an alternative named.

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 exceptionally transparent. It details fan-out behavior, response shapes, resolver confidence levels, parent-event extraction, news fallback fields, low-confidence short-circuiting, closed-market status, wide-spread illiquidity warnings, and cancellation-rule risks. Even with annotations declaring readOnlyHint=true and destructiveHint=false, the description adds far more than needed.

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

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

Though long, every section earns its place. The description is structured with clear uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), front-loads the core purpose, and packs dense but relevant behavioral and safety information. No wasted words.

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

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

For a tool with no output schema and high complexity, the description is remarkably complete. It covers input formats, classifier categories, fan-out examples, response structure, confidence gating, parent-event extraction, news fallback behavior, illiquidity, closed-market status, and cancellation-rule risk. An agent can safely invoke and interpret results from this description alone.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description does repeat market input formats and adds context about fan-out behavior, but it does not add substantial parameter-level meaning beyond the schema's property descriptions. The depth and include_raw parameters are well-documented in the schema and not further enriched in the description.

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

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

The description opens with a specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input (slug, URL, question) and the output (evidence packet + market-vs-model comparison). However, it does not explicitly distinguish this tool from sibling tools like ask_pipeworx or polymarket_edges, so it falls 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 explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples for multiple bet categories. It does not, however, mention when NOT to use it or name alternative tools, so it lacks full exclusionary 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). 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 dense but every sentence adds value: query examples, preference rule, type-specific metrics, fiscal year handling, sorting behavior, and return format. No filler words or repetition of schema details.

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

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

Despite no output schema, the description explains what is returned (paired data + citation URIs) and covers key edge cases (off-calendar fiscal years). It also addresses when to use the tool versus alternatives, making it complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters, but description goes deeper: explains how 'type' changes the data pulled (company vs drug), and how 'values' should be formatted (tickers/CIKs vs drug names). Also explains behavioral nuances like off-calendar fiscal year handling and result sorting.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific query examples. It distinguishes itself from siblings like entity_profile by emphasizing the parallel comparison versus sequential single-entity lookups.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups' when comparing entities, and notes it replaces 8–15 sequential lookups. This gives clear when-to-use guidance, though it does not name sibling tools directly, the contrast is unambiguous.

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

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

The description goes far beyond the annotations (readOnly, idempotent, etc.) by disclosing account requirements, latency expectations, the output packet structure, gaps[] that are never invented, contradictions[], semantic excerpting, and the hop/citation fields. This provides deep behavioral context without contradicting annotations.

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

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

The description is long but information-dense, with clear logical structure: account requirement, core purpose, use cases, depth behavior, output details, latency. It is front-loaded with actionable caveats (account, alternatives). It earns a 4 rather than 5 because of the sheer length and some minor redundancy in explaining 'not open-web search' and gaps[].

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers the output packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps, contradictions), edge cases (news topics, empty gaps), and performance expectations. An agent has enough information to decide when to invoke it and what to expect.

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

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

While the schema already describes both parameters at 100% coverage, the description adds significant semantic depth: depth:'standard' re-angles gaps, 'thorough' chases leads, 'quick' has 3 facets, and depth also affects contradiction scanning and paid status. It enriches the meaning of both 'question' and 'depth' 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 is explicit and specific: 'Grounded multi-source research across Pipeworx's 1408 STRUCTURED data sources' and it explains the decomposition and parallel routing. It clearly distinguishes itself from ask_pipeworx for single lookups and current news, so it is not confused with siblings.

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

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

Provides explicit guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states the account requirement and points to an alternative if not signed in, leaving no ambiguity about when to use the tool.

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

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

Annotations already declare readOnly/idempotent/destructive hints, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns full input schemas with curated examples, ready to call without a second lookup, and returns the top-N most relevant tools. This clarifies the output format and usage sequence, though it doesn't delve into pagination or relevance ranking details.

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

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

Two sentences, front-loaded with purpose, then usage guidance and output details. Every sentence earns its place—no filler, no redundancy. The structure walks from what it does, to when to use it, to what it returns, which is ideal.

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, the description is fully complete: it explains the return value (top-N tools with schemas), the usage context (call first for discovery), and the input semantics. No output schema exists, so the description's explanation of return format is sufficient. Combined with rich annotations and full schema coverage, the description leaves no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the core 'query' parameter as 'describing the data or task' and clarifying the natural language intent, which goes beyond the schema's basic description. It also implicitly sets expectations for the 'limit' parameter through 'top-N', adding value without repeating schema definitions.

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

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

The description uses a specific verb+resource ('Find tools by describing the data or task') and immediately distinguishes itself from siblings by positioning as a meta-tool for discovery. It lists concrete example domains (SEC filings, FDA drugs, etc.) and states it returns tools ready to call, making its 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 explicitly says when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and implies alternatives (direct tool calls) by contrast, satisfying the when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails on patent API sunset, and uses a GDELT→GNews fallback. It doesn't mention latency or error details, but enough is disclosed to set expectations.

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

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

The description is detailed but well-structured, leading with example queries, then stating the primary purpose, followed by a bullet-like list of return fields. It is longer than average but packs necessary details compactly without excessive fluff.

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

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

With no output schema, the description compensates by enumerating the return fields (cik, recent_filings, fundamentals, patents, news, LEI) and noting the fallback behavior. It is comprehensive enough for a read-only profile tool, though it doesn't detail the formats of every field (e.g., news or LEI).

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 repeats the value format (ticker or CIK) exactly as the schema states it. It adds no new parameter semantics beyond what the schema already provides; the schema already notes names not supported and references resolve_entity.

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

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

The description states the verb and resource clearly: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings like resolve_entity and compare_entities by emphasizing holistic multi-source profiling and listing specific return fields.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a concrete alternative: 'use resolve_entity first if you only have a name.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the main behavioral traits are covered. The description adds minimal extra behavioral context (e.g., 'previously stored memory by key' and 'clear sensitive data') but does not disclose edge cases like missing keys. No contradiction with annotations.

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

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

Three concise sentences with no redundancy. Each sentence earns its place: what the tool does, when to use it, and related tools. Front-loaded with the action.

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 single-parameter destructive tool with annotations, this description is quite complete. It covers purpose, usage timing, and sibling relationships. Missing details like error handling or return value are not critical given the simplicity and lack of output schema.

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

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

Schema description coverage is 100% since the only parameter 'key' is adequately described as 'Memory key to delete'. The description text adds no additional meaning beyond the schema, but the schema already carries the necessary information.

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

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

The description uses a specific verb ('Delete') and clearly identifies the resource ('previously stored memory by key'). It distinguishes itself from siblings like 'remember' and 'recall' by focusing on deletion.

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

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

Provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall', clarifying complementary tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context by detailing the internal steps ('Fetches the page, extracts title/description/key links') and the output form ('a single text blob ready to drop at site-root/llms.txt'), which 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 concise and well-structured: the first sentence states the primary purpose and audience, the second explains the process and output, and the third lists actionable use cases. Every sentence earns its place with no filler or repetition, making it highly effective at conveying the tool's utility.

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

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

For a tool this simple (two parameters, no output schema), the description is fully complete: it covers the input URL, the optional max_links limit (implicitly via schema but with enough context), the behavior, and the exact output format as 'a single text blob'. It also notes the target placement (site-root/llms.txt), leaving no ambiguity about what the tool returns or when to use it.

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

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

The input schema provides 100% coverage for both parameters (url and max_links), including descriptions and defaults. The description's phrase 'for any URL' is redundant with the schema and does not add meaning to max_links. Since the schema carries the full semantic burden, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate'), a specific resource ('a production-ready llms.txt file'), and the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It also distinguishes this tool from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on generating llms.txt rather than broader visibility scanning.

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

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

The description explicitly lists three concrete use cases under 'Useful for': getting a client's site indexed, drafting llms.txt for your own project, and auditing a competitor from an AI crawler's perspective. It does not name alternatives or state when not to use the tool, so it falls short of the 'explicit when/when-not' bar, but the context is clear enough for an agent to decide when to call it.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description does not need to repeat safety traits. It adds minimal behavioral context beyond the schema, such as implying a single profile fetch, but lacks details like return format or error handling. This is adequate given the annotations.

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

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

The description is extremely concise at one sentence, front-loading the essential purpose. It earns its place without fluff, though it could benefit from a brief note on usage scope without becoming 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?

For a simple read-only tool with an output schema and rich annotations, the description covers the core purpose and primary parameter. However, it omits the meaning of 'legislature' and provides no guidance on when to choose this over sibling tools, leaving a moderate gap in context completeness.

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

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

Schema description coverage is only 50% (slug_or_id is described, legislature is not). The description repeats the slug_or_id semantics ('by slug or numeric id') but adds nothing for the legislature parameter, failing to compensate for the missing schema description. It provides no extra meaning beyond the existing 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 'Deputy profile by slug or numeric id' clearly identifies the resource (deputy) and the lookup mechanism (slug or id), distinguishing it from list-type tools like list_deputies. It is concise and specific, matching the high standard of stating what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_deputies, entity_profile, or resolve_entity. There are no explicit or implicit usage contexts, leaving the agent to infer from the name alone.

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

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

Beyond the readOnly/idempotent annotations, the description reveals a critical behavioral quirk: NosDéputés never ingested the 17th legislature, making this a frozen historical record. This is essential information that could otherwise lead an agent to incorrectly assume current data. The mention of 618 deputies also sets expectations about the result set.

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 with no wasted words: the first delivers the core function and data fields, the second explains the default legislature and historical caveat. It is front-loaded and well-structured.

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 output schema exists and the input schema is fully documented, the description covers all essential context: what is listed, what fields are included, the default legislature, and the critical historical caveat. There is no significant missing information for an agent to correctly select and invoke this tool.

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

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

The input schema has 100% parameter description coverage, documenting all three parameters (group, departement, legislature) with examples and matching field names. The tool description adds no extra parameter-level semantics beyond mentioning 'party' and 'département', which are already in 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 action ('List') and resource ('French Assemblée nationale deputies') with specific data fields (party, département, profession, contact details). It also distinguishes this tool as a historical record for the 16th legislature, setting it apart from any current-chamber listing tool.

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

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

The description gives clear context, including the default legislature and an explicit warning that this is not the currently sitting chamber. However, it does not name alternative tools (e.g., get_deputy) for current data, so it falls short of providing explicit 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 the tool read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. However, the description adds no behavioral context, such as pagination, filtering behavior, or what the open-world hint means in practice. It does not contradict annotations but also provides no additional transparency beyond the structured fields.

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

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

The description is extremely short at five words, but it is a sentence fragment rather than a concise, well-structured statement. It under-specifies the tool and lacks a clear subject-verb-object structure. This is under-specification rather than effective 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 very simple tool with one optional parameter and an output schema, the description is still incomplete. It does not state the tool's core purpose explicitly, what political groups are, what the output contains, or how the legislature parameter affects the returned data. The annotations and output schema mitigate some gaps, but the description alone is not sufficient for an agent to select and invoke the tool correctly.

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

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

The 'legislature' parameter has no description in the schema (0% coverage) and the tool description does not explain what it does, what format is expected (e.g., ID vs name), or how it filters results. The parameter name is somewhat self-explanatory, but the meaning and usage remain ambiguous without explicit documentation.

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 'Political groups in the assembly' is a fragment that names a resource but lacks a verb. It does not explicitly state that the tool lists or retrieves groups, relying on the tool name for the action. It provides some context (political, assembly) but is vague and does not clearly distinguish from sibling tools like list_deputies.

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

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

No guidance is given about when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions. The description simply names the resource without explaining how it fits into a workflow or when it should be preferred over other list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about scope ('caller's') and the return fields, which is useful. However, it doesn't discuss pagination or effect of include_inactive, but annotations lower the bar.

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 with front-loaded purpose and immediate usage guidance. Every word earns its place; no filler or redundancy.

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

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

For a simple read-only list with one optional parameter, the description fully covers purpose, scope, return fields, and use cases. The output schema absence is mitigated by explicitly listing returned fields.

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

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

Schema description coverage is 100% for the single optional parameter include_inactive, which has its own description. The tool description does not mention this parameter, so it adds no additional semantic value beyond the schema.

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

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

The description uses the specific verb 'List' with a clear resource ('the caller's active subscriptions') and enumerates the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

It explicitly states when to use this tool: 'before adding more' subscriptions and 'to find an id to cancel.' This provides clear context and implies alternatives (subscribe/unsubscribe).

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

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

Annotations already indicate this is a read-only, idempotent, and safe operation. The description adds minimal behavioral context, only implying the data is a record of votes. It does not clarify what 'recent' means (e.g., time window, ordering) or any pagination behavior.

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

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

The description is extremely short (three words), but this is under-specification rather than conciseness. It lacks any structured information about filtering, ordering, or what the output represents. Every word is used, but the result is not useful.

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?

While an output schema exists, the description fails to provide essential context such as the meaning of 'recent', whether results are ordered by date, or how the limit parameter interacts with the default. The tool's overall complexity is low, but the description leaves too many gaps for an agent to use it correctly.

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

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

The description does not mention any parameters. The input schema provides descriptions for limit and deputy_slug, but the third parameter 'legislature' lacks a description. The description adds no value beyond the schema, and it fails to compensate for the missing parameter explanation.

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

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

The description 'Recent recorded votes.' is a noun phrase that conveys the tool returns recent votes, but lacks an explicit verb like 'list' or 'get'. It does not distinguish this from sibling tools like list_deputies or list_groups, though the class of resource (votes) is clear.

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

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

No guidance is provided on when to use this tool versus alternatives, such as search_interventions or search_questions. There is no mention of prerequisites, typical use cases, or when to prefer other 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?

The annotations are all false, so they convey no behavioral safety signals. The description compensates richly by disclosing: rate-limited to 5 per identifier per day, free and does not count against quota, the team reads digests daily, and the privacy instruction to not paste end-user prompts. These details exceed what annotations provide and help the agent set expectations.

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

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

The description is about four sentences, but every sentence carries essential information: purpose, trigger conditions, exclusions, content instructions, and operational policies (rate limit, quota). It is front-loaded with the main action and logically organized, so despite its length, it is concise and efficient.

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

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

For a tool with only three parameters, no output schema, and no complex behavior, this description covers all necessary context: what the tool does, when to use it, when not to use it, how to format feedback, and what constraints apply. It is fully self-contained and leaves no critical questions for the agent.

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

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

The schema already provides 100% coverage with detailed descriptions for type, context, and message, including enum values. The description adds meaningful extra guidance: 'Describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt,' which clarify how to populate the context and message fields. This goes beyond the schema, so a 4 is warranted.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This directly states the tool's function and scope, and it is distinct from sibling tools that focus on research, search, or entity resolution. The verb 'tell' plus the resource 'Pipeworx team' leaves no ambiguity about the tool's purpose.

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

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

The description explicitly defines when to use the tool: for bugs (wrong/stale data), feature requests, data gaps, or praise. It also includes a clear exclusion: if the tool came from a different MCP server, report it there instead. This provides both positive and negative usage guidance, along with an alternative action, making it superior to basic descriptions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it mentions the data source (CF analytics-engine), privacy (no PII), output granularity (pack, tool, count), and caching (5min-1h depending on window). These details go well beyond the annotations and help the agent understand performance and data provenance.

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

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

The description is front-loaded with the main purpose, followed by a compact bulleted list of use cases, then two short sentences on data characteristics and caching. Every sentence adds information without redundancy or fluff, making it easy for an agent to quickly extract key facts.

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

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

For a tool with one optional parameter and no output schema, the description is complete: it specifies what the tool returns (top tools, top packs, total call volume), how it derives data, privacy aspects, and caching behavior. The absence of an output schema is compensated by the explicit mention of '(pack, tool, count)'.

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 optional 'window' parameter, and the description reinforces its meaning by listing '24h, 7d, or 30d' in the main text. The schema description already explains the trade-off between hot/current and steady-state demand, which is actionable semantics beyond basic enum values.

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

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

The description clearly states the tool's function: it reports what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. It uses a specific verb ('Returns') and resource ('what other AI agents are calling'), and the focus on aggregated usage trends distinguishes it from siblings like discover_tools or ask_pipeworx.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool choices, and checking alignment with other agents. However, it does not explicitly name alternative tools to use instead or state when not to use this tool, though the context implies its role relative to asking questions.

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 label the tool read-only, open-world, and idempotent. The description goes far beyond this by detailing internal logic: partition_filter drops placeholder slugs, semantic anchor enforces ≥0.30 Jaccard similarity, fill check prices signals against live CLOB depth, and it explains consequences like 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' 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 exceptionally well structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. The opening sentence states the core purpose immediately, and every subsequent sentence adds essential detail. No redundancy or filler; 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?

Given the tool's complexity and absence of an output schema, the description thoroughly covers return values and operational behavior: it mentions `opportunities[]` fields, `partition_check` output, fill check results, and placeholder filtering. It also references sibling tools for related needs (custom sizing via polymarket_fill_risk), making the description self-sufficient 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 the schema covers both parameters with descriptions (100% coverage), the description adds substantial semantic depth: concrete examples ('fed-decision-may-2026'), mode-specific behavior, how each parameter triggers a different scan type, and the meaning of the internal checks. It explains the difference between `event` and `topic` far beyond what the schema provides, including trade-offs like cross-event catching date-boundary patterns.

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 states what the tool does and distinguishes it from sibling tools like polymarket_edges by focusing on arbitrage detection rather than edge monitoring. The three execution modes (no-args trending_scan, event, topic) are explicitly named and explained.

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: 'Call with NO args for a trending_scan... pass event... or topic.' It also explains when to prefer one mode over another, e.g., 'event (recommended for a specific market)' and 'Cross-event mode catches ... patterns that single-event misses.' It even directs users to a sibling tool, 'For custom sizing use polymarket_fill_risk,' and gives actionable advice on when not to trade based on fill check results.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge computations (slippage, Kelly cap at 0.25), placeholder filters, Fed bets exclusion, diagnostics with funnel counters, and 1-hour KV caching. It also discloses the 24h-move warning and 'your edge may already be in the price' caveat.

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 densely structured with clear labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL) and front-loaded purpose. Every section earns its place for a tool with 9 parameters and 3 segments. Slight verbosity prevents a 5, but the organization is excellent.

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 fully explain return values, and it does: by_segment structure, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume), fed_candidates/fed_note, and _diagnostics. It also explains why segments may be empty (top-N stale, gates failed, knobs dropped) and mentions 1h caching. Complete for a complex analytical tool.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds extra value by explaining the purpose of tradeable-edge knobs (min_liquidity/max_spread_pp drop unrealizable opportunities), clarifying min_partition_leg_kelly applies to per-leg Kelly inside partitions (not the parent level), and providing slippage rationale (Polymarket zero fees but bid/ask eats 20-50bp). This enriches parameter understanding beyond the schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', naming a specific verb, resource, and purpose. It distinguishes from siblings by emphasizing top-market scanning and Pipeworx disagreement, and explicitly frames the use case as 'what should I bet on today'.

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 ('agents discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs, but it does not explicitly name alternative tools or say when not to use this tool. The use case is clear, but exclusions/alternatives are 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 read-only/idempotent/non-destructive, and the description adds rich behavioral detail beyond that: snapshot TTL limits, cache-miss gaps meaning no scan, decay computed on absolute edge_pp_net, daily-close basis, and detailed response semantics. This gives the agent a clear model of data freshness and 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 organized into purpose, args, response, and limits, with every sentence earning its place. It is long but dense with operationally relevant detail (trend categories, expired lifespan, snapshot gaps, TTL, daily vs intraday), with no filler or repetition.

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

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

Without an output schema, the description fully documents the response fields (tracked, expired, snapshot_dates), their semantic meaning, and critical caveats. It explains how to interpret trend, decay direction, expired opportunities, and data gaps, making it complete for an AI agent to invoke and interpret correctly.

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

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

Schema coverage is 100% with both parameters already documented (days default/clamp, window enum/default). The description mostly restates these defaults and adds only minor context ('snapshot family'). Since the schema carries the parameter meaning, baseline 3 is appropriate; the description does not substantially extend parameter understanding.

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

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

The description opens with 'Edge persistence and decay telemetry' and explicitly frames the question it answers ('how long has this edge existed and is it shrinking?'), which clearly distinguishes it from the current-edge sibling tool polymarket_edges. It names the resource (daily polymarket_edges snapshots) and the analytical verb (track/measure persistence and decay).

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

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

It provides clear decision context: use this when you care whether an edge is fresh or old, because 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternatives or exclusions, but the usage intent is unmistakable and the contrast with current-edge tools is implied.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior, but the description goes far beyond. It details the mechanics: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill). It also describes failure modes (thin_legs, forced_directional_risk) and the danger of partial basket fills converting an arb into a directional position. This is rich behavioral context that annotations alone would not provide.

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

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

The description is long but well-structured. It front-loads the core purpose in the first sentence, then separates SINGLE-MARKET and BASKET sections with clear boundaries. Every sentence conveys specific information about parameters, return values, or usage context. While some might find it wordy, each clause carries meaning. The only minor deduction is that the final sentence about dominant loss mode is a bit redundant with the earlier warning, slightly padding length.

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

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

For a tool with 4 parameters, no output schema, and two distinct operating modes, this description is exceptionally complete. It explicitly lists all return fields for both modes, explains parameter interpretation and defaults, warns about edge cases (thin legs, forced directional risk), and specifies input formats (slug or URL). Given the complexity, the description fully compensates for the missing output schema and leaves no major questions about behavior.

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

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

Although the schema already describes all four parameters (100% coverage), the description adds significant semantics beyond the schema. It explains the dual interpretation of size_usd (max spend on buys, target proceeds on sells in single-market; settlement notional S meaning shares-per-leg paying $1 each in basket mode). It also details the default 'auto' side selection for baskets and the behavior of side in each context. This goes well beyond the schema's short descriptions.

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

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

The description opens with a precise verb-object pair ('Realizable-vs-theoretical edge check') and immediately specifies the resource ('live CLOB order-book depth'). It clearly distinguishes this from siblings by focusing on fill risk vs. theoretical arbitrage/edge detection, naming exact counterpart tools (polymarket_arbitrage, polymarket_edges) as triggers. The two operating modes (single-market and basket) are explicitly defined, leaving no ambiguity about what the tool does.

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

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

The description 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 also gives a clear reason why (theoretical overround is not capturable on thin books, partial fills cause unhedged directional risk). This is a direct when-to-use with alternatives implicitly covered—it positions itself as the pre-trade validation step.

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

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

Annotations declare readOnlyHint and destructiveHint=false, so safety is covered. The description substantially adds behavioral context: it explains compatibility_warning cases (a) and (b), temporal_alignment semantics, and skipped_cross_type/subtype counters, which are not visible in schema or annotations. It also discloses that most pre-mapped topics return warnings, setting expectations for real-world use.

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

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

Although long, every sentence adds value: the description front-loads purpose, then uses caps-lock structural markers (TWO MODES, RESPONSE, SAFETY FIELDS) to organize dense information. It avoids repeating schema details, instead explaining behavior and limitations.

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

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

With no output schema, the description must explain the response shape, and it does so thoroughly: it lists raw probabilities, spread[].top_spreads_pp, compatibility_warning triggers, temporal alignment fields, and skip counters. It also covers the real-world limitation that most shortcuts return warnings, making the tool's behavior predictable.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds meaningful interplay semantics: it explains that explicit ticker/slug override topic-mapped sides and gives concrete examples of topic enum values. It also clarifies that topic is a pre-mapped shortcut, which is more than the schema's 'Pre-mapped' label.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' identifying the specific verb, resource, and cross-venue scope. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Kalshi–Polymarket beta and explains the two input modes, so the purpose is unambiguous.

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

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

The description provides clear usage instructions through 'TWO MODES' and explains when to use the topic shortcut vs explicit ticker/slug. It gives decision guidance on interpreting results, warning that 'pre-mapped ≠ tradeable' and that compatibility_warning indicates non-tradeable spreads. It doesn't explicitly name alternatives, but the context is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: scoping to the agent's identifier ('anonymous IP, BYO key hash, or account ID') and the omit-key-to-list-all behavior. It also clarifies the relationship with remember and forget, all 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 concise and front-loaded: the first sentence states the action, the second gives usage context, and the third explains scoping. Every sentence earns its place, with no filler or redundancy.

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

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

For a single-parameter, read-only tool with strong annotations and no output schema, the description is complete. It covers purpose, typical use cases, key semantics, scoping, and relationship to sibling tools (remember/forget), leaving minimal ambiguity for an agent to pick and invoke it correctly.

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

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

Schema description coverage is 100% ('Memory key to retrieve (omit to list all keys)'), so the schema already documents the only parameter. The description reinforces the omit behavior and gives real-world examples of key values, but it adds no deeper syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys', and explicitly distinguishes itself from sibling memory tools by naming remember and forget. It also adds scope ('Scoped to your identifier') and examples, making the purpose unambiguous.

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

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

The description gives clear usage guidance: 'Use to look up context the agent stored earlier' and provides concrete examples (user's target ticker, address, research notes). It contrasts with re-deriving information ('without re-deriving it from scratch') and points to remember/forget for complementary operations, though it does not provide an explicit when-not-to-use list.

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

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

The description clearly discloses that setting mark_read:true will 'flag returned events read,' which is a state-changing side effect. This directly contradicts the annotation readOnlyHint=true, making the tool's annotated safety profile misleading. Per the rubric, this is an annotation contradiction and scores 1.

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

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

The description is five sentences, each earning its place: purpose, return content, filtering, mark_read behavior, and alternative access. It is front-loaded and contains zero filler or redundancy.

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

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

Given the tool has no output schema and moderate parameter complexity, the description thoroughly covers what the tool returns, how to filter, the side effect of mark_read, and polling suitability. It also points to an HTTP endpoint, making it highly complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), clarifying the since parameter as an ISO timestamp, and explaining the effect of mark_read. Limit and unread_only are not elaborated, but the schema covers them adequately.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly distinguishes this tool from siblings like list_subscriptions and ask_pipeworx. It also details the return payload (source, citation_uri, raw event payload), reinforcing the tool's core 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 gives practical usage context: filtering by type with an example ('sec_8k'), using ISO timestamps, and explaining mark_read behavior so the next call shows only newer events. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts, showing awareness of alternatives, though it doesn't explicitly compare to sibling tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral details: the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO patents with a note about PatentsView API sunset and soft-fail behavior, and the exact return shape (changes[], total_changes, pipeworx:// URIs). This is exemplary transparency for a multi-source aggregation 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 tight and efficient: it opens with example queries, then explains sources, fallback logic, parameter syntax, output format, and alternative tool in a logical flow. No redundant sentences; every clause earns its place, making it suitably sized despite covering multiple aspects.

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

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

Given the tool's complexity (multi-source fetch, fallback chain, API sunset caveat, structured output), the description covers all necessary context: the sources, the fallback conditions, the soft-fail for USPTO, the input formats, the output structure, and the differentiation from entity_profile. With no output schema, the description fully explains the return value, making it self-sufficient.

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

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

The input schema already covers all parameters with descriptions (100% coverage), including the 'since' window start and 'value' as ticker or CIK. The description repeats these examples without adding substantial new meaning beyond what the schema provides. The only minor addition is clarifying that 'since' is the window start, but the schema already says 'Window start', so the description adds marginal value.

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

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

The description states a clear purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the resource (company) and the action (fetch changes), and distinguishes itself from the sibling tool entity_profile by explicitly contrasting the use cases. The examples of natural language queries ('What's new with X') further clarify the intended use.

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 the tool vs. alternatives: 'Use entity_profile instead when you want the static profile...' It also details the fallback behavior (GDELT→GNews) and the window formats, giving the agent clear conditions for invocation. This goes beyond mere context to direct selection.

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

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

Annotations indicate idempotent and non-destructive behavior, and the description adds scoping and retention details (persistent for authenticated users, 24 hours for anonymous). This goes beyond annotations, though it doesn't mention overwrite behavior—acceptable for a key-value store.

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 total—all concise and purposeful. The main action is front-loaded, and every sentence adds distinct value: purpose, usage, and persistence details.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, persistence behavior, and complementary tools. No additional information is needed to select and invoke it correctly.

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

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

Schema already provides 100% coverage of key and value, so baseline is 3. The description adds valuable examples of what to store (ticker, address, preference, subject) and explains the pairing concept, enriching the semantics beyond schema alone.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It further clarifies the key-value pair structure and explicitly differentiates from siblings by mentioning recall and forget, making it clear this tool is for storage only.

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

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

It gives explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference, research subject). It does not explicitly state when not to use it, but the context is strong enough to infer appropriate usage, and it references complementary 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?

The description goes beyond the readOnly/idempotent annotations by detailing the exact fields returned (ticker, CIK, company_name, RxCUI, ingredient, brand), the source databases (SEC EDGAR, RxNorm), and citation URIs. It also discloses that the tool cascades through multiple endpoints for a single call, which is valuable behavioral context not present elsewhere.

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

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

The description is information-dense and efficiently structured: examples first, then a concise purpose statement, usage directive, and type-specific details. No sentence is wasted, and the formatting with 'SUPPORTED TYPES' bullet-like structure aids readability. It remains focused despite its length.

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

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

With no output schema, the description fully explains the return format for each supported entity type, including both data fields and citation URI formats. It also covers input flexibility, disambiguation behavior, and a performance note about replacing multiple lookups. This is complete for the tool's complexity and its role within the tool ecosystem.

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

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

The input schema already provides 100% coverage for the two parameters, including enum values and examples. The description adds minimal extra semantic depth, such as 'auto-disambiguated' and clarification that the output includes citation URIs, but this is a slight enhancement over the schema's descriptions. Thus a 4 is appropriate for going slightly beyond the structured field documentation.

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 immediately states the tool's purpose: resolve a user-spoken name to the canonical/official identifier required by other tools. It uses specific verbs ('resolve', 'look up') and clearly distinguishes itself from siblings by positioning it as the first step when an ID is needed. The supported types are explicitly listed with concrete examples.

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 instructs 'Use FIRST whenever you have a name but need an ID,' which is a clear directive. It also explains what types of lookups are supported and contrasts with the fact that other tools require these IDs, giving context on when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. This provides clarity beyond the structured metadata.

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 efficient and well-structured: it starts with the core action, then explains the mechanism (probes via ai_visibility_check), gives a practical use case with an example, and ends with output details. All sentences carry useful information, though slightly wordier than strictly necessary.

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

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

The description adequately covers the tool's behavior and return value (ranked list with score, confidence, signal density), which is important since there is no output schema. Combined with strong annotations and fully documented parameters, it gives the agent enough context to understand what the tool does and what to expect.

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

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

Schema coverage is 100%: each parameter (models, _apiKey, context, entities) already has detailed descriptions including conditional requirements and constraints. The description adds little new parameter-level semantics beyond reinforcing that the first entity is the subject, which the schema already states.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and surfaces which is most/least recognized. It distinguishes itself from siblings like ai_visibility_check by focusing on multi-entity comparison and ranking.

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

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

The description gives a clear use case ('competitive AI-marketing audits') with an illustrative example, and implies this tool is for comparing multiple entities rather than checking a single one. It does not explicitly state when not to use it or name alternatives, but the context is sufficient.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: composite fan-out across two services, graceful degradation of partial failures, a 5–30s latency risk on bundlephobia's first measurement, and the sources_failed field for observability. This gives the agent actionable expectations for scheduling and error handling.

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 minimal but every sentence carries essential information, from the composite nature to the summary fields to the failure mode. It is front-loaded with the core purpose and uses clear separators (em-dashes, semicolons, field lists). A slight tightening is possible but the structure is effective 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 absence of an output schema, the description compensates by enumerating the exact summary block fields, per-advisory details, links, and alternative versions. It also covers the NPM-only constraint, latency, and partial failure behavior, making the tool's full context transparent and complete.

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

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

The input schema fully covers both parameters: 'package' includes scoped package examples, and 'version' states the default-to-latest behavior. The description does not add additional parameter-level detail, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a precise verb-plus-resource framing: 'Composite should I add this npm package to my project check in ONE call', clearly identifying that it scans npm dependencies across deps.dev and bundlephobia. It explicitly distinguishes itself from sibling tools by restricting scope to NPM and naming deps.dev:version as the alternative for other ecosystems.

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

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

Provides explicit invocation guidance: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also states when NOT to use it, directing non-NPM ecosystems to deps.dev:version directly, which is a clear exclusion.

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, covering the safety profile. The description adds no further behavioral context such as pagination, result ordering, or rate limits. It is consistent with annotations but adds minimal value beyond 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 a single sentence of fewer than ten words, front-loaded with the core action and resource. Every word earns its place, with no filler or repetition.

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

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

The tool is relatively simple, has a rich output schema, and strong annotations that cover safety and side effects. The description is sufficient for understanding the tool's primary purpose, though it could benefit from noting sorting or default behavior. Overall, it is adequately complete for the tool's complexity.

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

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

Schema description coverage is 67%, with query and legislature lacking descriptions. The tool description provides no additional parameter semantics, leaving the undocumented parameters without clarification. It also does not elaborate on the meaning of 'query' or how date/deputy filters combine.

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

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

The description states a specific verb and resource: 'Full-text search across debate contributions.' This clearly distinguishes it from sibling tools like search_questions, which focus on questions, and search_within, which implies a different search scope.

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

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

The description implies the tool is used to search debate contributions, but it gives no explicit guidance on when to prefer it over alternatives such as search_questions or search_within. No exclusions or alternative suggestions are provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by listing the returned fields (title, deputy, date, type) and the available filters, which goes beyond the annotations and helps set expectations 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 a single, well-structured sentence that front-loads the core action and resource, then lists filters and return fields. Every clause earns its place with no wasted words or repetition.

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

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

Given the tool's moderate complexity (5 optional parameters) and the presence of an output schema, the description covers the essential behaviors: what it searches, what filters apply, and what it returns. It omits minor details like pagination (related to 'limit') and the meaning of 'legislature', but these are secondary and partially recoverable from the schema.

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

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

Schema description coverage is only 20% (only 'type' has a description). The description compensates for three key parameters—query, deputy_slug, and type—by explicitly mentioning them as filters. However, 'limit' and 'legislature' are not explained, and the description does not cover them, leaving a gap for an agent unfamiliar with these terms.

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

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

The description clearly states the verb 'Search' and the resource 'written or oral questions submitted by French Assemblée nationale deputies'. It also specifies the key filters (free-text query, deputy slug, question type), which distinguishes it from sibling tools like search_interventions or suggest_questions.

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

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

The description gives clear context for when the tool is appropriate: searching parliamentary questions by specific filters. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough that an agent can select it over siblings without confusion.

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

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

The description adds substantial behavioral context beyond the annotations: it specifies the use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and truncation at 200K chars with a flag. It also explains the output includes character offsets enabling verbatim quote verification. These details are not present in the annotations and significantly enhance transparency.

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

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

The description is concise and front-loaded: the first sentence immediately states the core action, the second provides usage context and benefits, and the third delivers technical details. Every sentence adds value, 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?

Despite lacking an output schema, the description adequately covers the tool's behavior, usage, and integration. It explains the work flow, the truncation edge case, and how it complements ask_pipeworx_grounded. Combined with the detailed input schema and annotations, the context is complete for an agent to use the tool correctly.

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

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

The input schema already provides thorough descriptions for all three parameters, and the schema coverage is 100%. The description does not add much new param-specific meaning beyond what the schema includes; it merely reiterates the 200K cap and natural-language query examples found in the schema. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's function: semantic search inside a fetched record, returning top-N passages with offsets and scores. It distinguishes itself from siblings by emphasizing 'INSIDE' and pairing with ask_pipeworx_grounded, making it clear this is for post-fetch search, not a general-purpose search tool.

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

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

The description explicitly says when to use it ('when the record is too big to cram into the prompt') and provides a pairing workflow with ask_pipeworx_grounded. However, it lacks an explicit when-not-to-use condition or a named alternative for small texts, which would make it 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 says 'Create... Returns the new subscription id,' implying each call creates a new subscription and is not idempotent. This directly contradicts the annotation idempotentHint=true. No other behavioral traits (like rate limits or account requirements) are disclosed beyond what annotations provide.

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

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

The description is a dense but information-packed paragraph that front-loads the purpose. It avoids fluff but lacks formatting (e.g., bullets) and runs several concepts together in a single flow. Still, every sentence contributes meaningful 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?

For a 3-param tool with nested objects and no output schema, the description covers return value, account requirements, delivery channels, and feed retrieval, and includes useful limits for sms. However, it lists only 3 of 5 subscription types and omits webhook details, though those are present in the schema.

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

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

The input schema has 100% description coverage, including all 5 types and nested delivery objects, so the baseline is 3. The description adds some extra context for sec_8k, polymarket_edge, and fred_series (e.g., 'items:["5.02"] = officer change'), but omits patent_grant and clinical_trial. It also adds sms verification and 10/day cap, but these are behavioral rather than parameter semantics.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, distinguishing it from siblings like list_subscriptions and unsubscribe. However, it lists only 3 of the 5 subscription types present in the schema, which could mislead an agent into thinking patent_grant and clinical_trial are unsupported.

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 important contextual prerequisites (OAuth account required, anonymous/BYO cannot persist) and delivery channel options, but it does not explicitly mention when to use this tool versus alternatives such as list_subscriptions or unsubscribe. No when-not-to-use guidance is given.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds context beyond these annotations: it states the output is drawn from a 'live catalog of thousands of tools' and that it returns tool+argument shapes, which helps the agent understand what to expect. It does not contradict 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, information-dense paragraph with dash-separated sections. It front-loads the user intent phrases and then explains behavior, usage, and output. While slightly long, every sentence adds value and the structure is scannable.

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

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

The description is complete for an onboarding tool: it explains the purpose, return format (category-bucketed example questions with tool+argument shapes), optional topic parameter, and when to use it first. Without an output schema, the description sufficiently discloses what the tool returns. The relationship to meta-tools is also covered.

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

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

The input schema already provides 100% description coverage for the single 'topic' parameter, including an enumeration of valid values and the omit behavior. The description's mention of topic examples ('finance', 'pharma', 'betting') is redundant. Since the schema fully covers parameter semantics, 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 states the tool's function: it returns category-bucketed example questions with exact tool and argument shape, serving as the onboarding entry point. It includes multiple example prompts and explicitly distinguishes itself from meta-tools like ask_pipeworx, entity_profile, and compare_entities by positioning itself as the 'first' tool to use when unfamiliar with Pipeworx.

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

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

Explicit usage 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 optional topic filtering and the no-argument full spread. However, it does not explicitly state when not to use it or name alternative tools for comparison.

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

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

The description adds significant behavioral details beyond the annotations: ownership is enforced, the row is deactivated not deleted, and historical events remain accessible. These clarifications are valuable and consistent with the annotations (readOnlyHint false, destructiveHint false, idempotentHint true).

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

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

The description is two sentences long, front-loaded with the primary action, and every clause adds value: ownership, deactivation, and historical retention. 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 cancellation tool with one parameter and no output schema, the description fully covers the operation's behavior, constraints, and downstream effects. It is sufficiently complete 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?

The input schema provides full coverage of the only parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds no extra meaning beyond saying 'by id,' so it does not improve on the schema's existing 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 clearly states the action ('Cancel'), the resource ('a subscription'), and the identification method ('by id'). It also distinguishes from siblings by noting ownership enforcement and deactivation (not deletion), which differentiates it from list_subscriptions and subscribe.

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

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

The description implies when to use it (when you want to cancel a subscription you own) and provides useful context about consequences (historical events remain via recent_alerts). However, it does not explicitly name alternatives or state when not to use it, though sibling tools like list_subscriptions are nearby.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive, lowering the burden. The description adds meaningful behavior: it routes to live sources, uses verbatim evidence, returns a specific verdict set, and explains the percent-delta math for financial claims. It does not contradict annotations and provides context beyond them, though it could mention limitations like source coverage or potential staleness.

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

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

The description is information-dense but efficiently organized. It front-loads trigger phrases and the core use case, then adds routing details and return format. Each sentence contributes value, with no redundant fluff or overly long digressions.

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

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

Despite having no output schema, the description fully specifies the return shape: a verdict enum, a cited actual value, and reasoning. It covers the two routing paths, the types of claims handled, and the efficiency benefit. For a tool of this complexity, the description is complete enough for an agent to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, and the schema already describes both parameters with examples and defaults. The description reinforces the claim format and tolerance behavior but does not add new parameter-level detail beyond the schema. This is the appropriate baseline score when structured data fully carries the parameter documentation.

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 verifies natural-language factual claims against authoritative sources, with a specific verb+resource ('claim verification'). It provides trigger phrases and distinguishes this from general research tools by highlighting the claim-checking scope and the two routing paths. The purpose is unambiguous and highly specific.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is strong when-guidance. It also explains when the financial fast path applies versus the general grounded pipeline, and notes the tool replaces multiple sequential calls. However, it does not name sibling tools as alternatives or explicitly state when not to use it, so it falls slightly short of a 5.

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