Datagouv Fr

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

Annotations already declare readOnly/idempotent, and the description adds valuable post-annotation context: it reveals the default Workers AI model, the requirement of _apiKey for Anthropic calls, and the direct cost implication. It also describes the output shape, which is 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?

Three sentences, front-loaded with the core purpose, followed by configuration and use cases. Every sentence 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?

There is no output schema, so the description compensates by stating the per-model return fields (score, confidence, signals, raw_response) and a combined view. It covers default model, optional Anthropic key, cost caveat, and use cases, making it fully 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 schema covers 100% of parameters, so baseline is 3. The description adds meaning by explaining the default model behavior, the relationship between _apiKey and probing Anthropic, and the combined output view. 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 uses a specific verb ('Probe') and clearly identifies the target (LLMs) and subject (business/brand/product/topic), plus the scoring output (0-100 per model). This distinguishes it from sibling tools like ask_pipeworx by focusing on visibility scoring rather than Q&A.

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 names use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to use the tool, though it doesn't contrast with alternatives or mention when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: routes to one of 5,521 tools, fills arguments, returns structured answers with stable citation URIs, and works on every tier with one fast call. This goes beyond the annotation basics and sets accurate expectations about behavior.

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

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

Though long, every sentence earns its place. The description is front-loaded with the key recommendation, uses bold and examples for scannability, and clearly separates usage, comparisons, and step-up guidance. 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 complex, routing-based tool with no output schema, the description adequately explains the return format (structured answer with citation URIs), performance characteristics (one fast call), and coverage. It also addresses edge cases like breaking news and multi-part queries via alternatives, making it contextually complete.

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

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

Schema coverage is 100% with the 'question' parameter and its aliases fully described. The description adds context about what kind of questions are appropriate (factual, real-world entities, numbers) and provides concrete examples, enriching the schema's bare parameter list.

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 routes factual questions to appropriate data sources and returns structured answers with citations. It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, and by positioning itself as the default entry point.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA data, etc.), trigger phrases, and examples. It also defines when to step up to ask_pipeworx_grounded or deep_research, and when ask_pipeworx already covers live news, making usage conditions 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, open-world, idempotent, non-destructive behavior. The description adds valuable context: it is a full working router with no fallback, experimental candidates are enabled live only when under test, and results feed merge decisions. This complements the annotations without contradiction.

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

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

The description is somewhat verbose but well-structured, leading with the key 'beta version' concept. Each sentence contributes to understanding the experimental status, though the points about matching ask_pipeworx could be slightly tightened.

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

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

For a router with no output schema, the description effectively covers the beta context, current state, usage, and comparison to the stable router. It answers likely questions about what this tool is and when to use it, making it reasonably 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 schema has 100% coverage, describing question and its aliases in detail. The description only mentions 'same arguments' without adding new semantic meaning, so it does not exceed the baseline provided by the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,521 tools, arguments, and response shape. It differentiates itself from sibling ask_pipeworx by emphasizing its experimental status and current exact match to the stable version.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It names the alternative (ask_pipeworx) and clarifies current behavior (no active candidate, so matches stable), providing clear when-to-use guidance.

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

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

The description goes well beyond the annotations by detailing the exact success and refusal return shapes, including specific refusal reasons such as 'not_in_source' and 'data_truncated.' It also discloses the extra LLM call cost and the grounding constraint ('using ONLY what the tool result contains'). These behavioral traits are not inferable from the readOnly/openWorld/idempotent annotations, and there is no contradiction with annotations.

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

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

The description is five sentences, front-loaded with the purpose and then flowing through mechanism, return values, usage, and cost. Each sentence is informative, but the enumeration of all refusal reasons in the output format is slightly verbose and could be condensed without losing critical behavior. Overall, it is well-structured and every sentence earns its place.

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

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

With no output schema, the description takes on the full burden of explaining return values, and it does so thoroughly: it provides the success shape with evidence and confidence, and the failure shape with all refusal reasons. It also covers routing scope, usage timing, and the cost trade-off relative to the sibling. This is a complete and self-sufficient description for a complex tool.

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

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

The schema already covers 100% of parameters with descriptions, all being aliases for 'question.' The description does not add parameter-specific insight beyond noting that the tool 'fills arguments' during routing, which is general. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds no extra semantic nuance for the parameters.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's core function as an answer mode that resists fabrication. It further specifies the mechanism ('EXTRACTS the answer using ONLY what the tool result contains') and differentiates from sibling ask_pipeworx by its groundedness and refusal behavior. This gives a specific verb+resource+scope and distinguishes it from similarly named tools.

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

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

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups,' naming the alternative sibling. This provides direct when/when-not guidance and mentions cost trade-offs, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond this: resolver contract with match confidence levels, parent_event extraction, news fallback flags, safety short-circuiting on low-confidence matches, status strings for closed markets, wide-spread tradeability warnings, and cancellation-rule risk quantification (refund_50_50). 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 densely packed with actionable info, organized in uppercase-labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and usage. While not concise in raw length, every paragraph adds value for a complex tool with no output schema; minor redundancy could be trimmed.

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 high complexity and absence of an output schema, the description is remarkably complete. It covers input flexibility, classifier list, fan-out examples per domain, response shapes with key fields, resolver behavior, parent_event extraction, news fallback mechanics, safety blocking, and resolution-rule risk. Agents can confidently invoke the tool and interpret unusual outcomes.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds genuine meaning: it explains how the 'market' param is resolved (slug/URL/question), how 'depth' maps to evidence sources (quick=2-3, thorough=full), and how 'include_raw' affects response size and when to use true. It also gives concrete examples and warning implications (e.g., cancellation rules) that the schema does not convey.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input forms (slug, URL, question text) and the outcome (evidence packet + market-vs-model comparison). It distinguishes from sibling tools by scoping to a single bet research task, with explicit use cases like 'should I bet on X'.

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

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

The description gives explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also states blocking conditions (low-confidence match, closed/inactive markets) and when to consider include_raw. However, it does not name direct alternatives (e.g., polymarket_edges) or say when not to use this tool, so it stops short of full 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and returning paired data with pipeworx:// citation URIs. This goes far beyond the annotations.

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

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

The description is dense but every sentence earns its place: trigger phrases, usage preference, type-specific behavior, and output format. It is front-loaded with natural language examples and avoids fluff, making it easy for an agent to scan and understand.

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 appropriately states that results are sorted by primary metric and returns paired data with citation URIs, covering return value expectations. It also explains the tool's scope (2–5 entities, one parallel call) and the source data for each entity type, making the tool fully understandable for an agent without needing additional context.

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

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

The input schema already covers both parameters with descriptions and enum constraints, yielding 100% schema coverage. The description adds extra semantic richness by explaining what each type pulls (e.g., revenue, net income, cash for companies; adverse-event counts for drugs) and giving concrete examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"], which helps clarify usage beyond bare schema.

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

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

The description clearly identifies the tool's function as a side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific trigger phrases like "X vs Y" and "rank these companies." It distinguishes itself from sibling tools like entity_profile by explicitly noting it should be preferred over 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?

The description provides explicit when-to-use guidance through natural language examples and states "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also implies when not to use it by contrasting with sequential lookups, giving clear context for choosing 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 as false, so the safety profile is well covered. The description adds no additional behavioral context such as authentication requirements, error behavior, or rate limits, but it does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It is concise and easy to parse, though it could arguably include more useful detail 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?

Given the simple single-parameter tool and the presence of an output schema, the description is minimally viable. However, it lacks sibling differentiation and guidance on how to obtain the id/slug, making it slightly incomplete for an agent deciding between multiple related tools.

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

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

The schema description coverage is 0%, so the description must compensate. It clarifies that the 'id_or_slug' parameter accepts either an ID or a slug, which adds some meaning beyond the bare parameter name. However, it does not provide format examples or clarify the difference between an ID and a slug.

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 'Single dataset by id or slug' clearly identifies the tool's purpose: retrieving one dataset using an identifier. The resource (dataset) and lookup method are explicit, though there is no explicit verb like 'get' or 'fetch'. It is distinguishable from search_datasets due to 'single', but this is not explicitly stated.

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?

There is no guidance on when to use this tool versus alternatives like search_datasets or entity_profile. The word 'single' implies a direct lookup, but no explicit context, exclusions, or recommended alternatives 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 indicate readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral context: account requirement, decomposition into facets, parallel routing across 5,521 tools, return packet structure (evidence + confidence + source + fetched_at + citation), gaps[] and contradictions[] semantics, citation fetchability, excerpting behavior, and latency expectations. This goes far beyond annotations and sets accurate 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 long but structured and front-loaded with critical account/auth info first, then core functionality, then alternatives, then advanced nuances. Each sentence contributes useful information, though a few points (e.g., mention of ask_pipeworx multiple times) could be trimmed. For a complex tool, this level of detail is justified, but it's slightly 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?

Given the tool's complexity and absence of an output schema, the description thoroughly explains the return packet, gap handling, contradictions, citation resolvability, and excerpting. It also covers prerequisites, alternatives, and performance trade-offs. This provides an agent with comprehensive context to invoke and interpret results correctly.

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

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

Schema coverage is 100% and the schema already provides good parameter descriptions. The description adds extra semantics by explaining depth variations ('quick', 'standard', 'thorough' include gap recovery/contradictions scan), paid plan requirement for 'thorough', and typical latency ranges. This enriches the parameter meaning beyond schema details.

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

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

The description clearly states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources... in ONE call' with explicit mention of decomposition and parallel routing. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and clarifying it is NOT open-web search. This makes the tool's unique role obvious.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for 'broad/multi-part questions over structured data', while for single lookups or breaking/colloquial current-news topics it directs to ask_pipeworx. Also mentions account prerequisites and depth alternatives, giving clear decision context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: results include full input schemas with curated examples, are directly callable, and are top-N ranked by relevance.

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 purpose, and the domain list is useful but makes it slightly longer. No wasted words, though the alias details are handled by the schema.

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

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

With no output schema, the description must explain return values, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas.' It also gives usage context and examples in the schema, making it adequate for an agent.

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

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

Schema description coverage is 100%, with clear descriptions for query, limit, and all aliases. The description adds no extra parameter-level detail beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource that clearly distinguishes this meta-tool from sibling search tools like search_datasets or search_organizations. It enumerates supported domains and explicitly frames itself as a discovery layer.

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

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

It provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies a when-not by stating 'not just one answer,' but does not name alternative tools directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral detail: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), returns specific fields, limits filings to 5, and mentions the USPTO API sunset with a soft-fail behavior. It even describes fallback chains (news via GDELT→GNews). This far exceeds the annotation baseline and gives the agent a clear model of what happens during execution.

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

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

The description is dense and information-rich, but not bloated. It front-loads with intuitive example queries and the core directive, then systematically enumerates the return fields and data sources. Each clause contributes value, though the length could be slightly trimmed without loss. Overall it is well-structured for a complex 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?

There is no output schema, so the description carries the full burden of explaining returns. It does so explicitly: cik + company_name, recent_filings (up to 5 with pipeworx URIs), fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC), patents (with API sunset note), news (with fallback), and LEI. It also explains input constraints and the resolution path for names. Given the tool's complexity, this description is remarkably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the same parameter guidance already in the schema (ticker or zero-padded CIK, names not supported). It does not add new parameter semantics beyond what the schema already specifies. Thus it neither compensates nor significantly enhances the schema, warranting a baseline score.

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

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

The description clearly states the tool's purpose: to provide a 'full cross-source profile of a US public company in ONE parallel call.' It lists the specific components (filings, fundamentals, patents, news, LEI) and explicitly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This goes beyond a generic verb+resource and establishes a unique role.

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

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

Explicit when-to-use guidance is provided: 'ALWAYS PREFER' this over chaining single-pack lookups for holistic questions. It also gives a concrete exclusion criterion: names are not supported, and directs users to 'use resolve_entity first if you only have a name.' This clearly orients the agent toward the right context and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat those. It adds context by specifying what gets deleted ('previously stored memory') and the rationale (clear sensitive data), which goes beyond the structured annotations. No contradiction exists.

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

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

The description is two sentences, front-loaded with the action verb and resource. Every word contributes value—purpose, usage guidance, and sibling tool pairing—without redundancy or fluff.

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

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

For a simple delete-by-key tool with full schema coverage and rich annotations, the description covers purpose, usage, and relationship to related tools. No additional details about return values or errors are needed given the tool's simplicity and the presence of annotations.

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

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

The schema has 100% coverage with 'key' described as 'Memory key to delete', and the description simply says 'by key', adding no additional meaning beyond the schema. As the schema fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific resource ('memory') and the method ('by key'). It distinguishes itself from sibling tools like remember and recall by explicitly indicating deletion, making its purpose unambiguous.

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references sibling tools ('Pair with remember and recall') to place the tool in context, offering clear guidance on when to deploy 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?

Beyond the read-only/idempotent annotations, the description discloses that the tool fetches the page, extracts content, and outputs a text blob. This explains the network-fetching behavior and output format, which is valuable context not captured by structured fields. It doesn't discuss rate limits or failure modes, but the annotations already cover safety.

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

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

The description is concise (three sentences plus a bullet list) and front-loaded: the first sentence states the core function, the second covers mechanics, and the third specifies output. Every sentence earns its place, and the 'Useful for' section is clearly separated.

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

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

The description explains the purpose, process, output format, and use cases, which is sufficient for a simple two-parameter tool. Since there is no output schema, it correctly describes the return value as a single text blob. It could mention edge cases like invalid URLs, but the openWorldHint and annotations mitigate that. Overall, it is functionally 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 schema already provides 100% description coverage for both parameters (url and max_links), so the tool description adds little parameter-specific meaning. The baseline is 3 because the schema does the heavy lifting, and the description doesn't introduce any additional param nuances beyond the generation context.

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

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

The description clearly states the verb ('Generate') and the resource ('a production-ready llms.txt file for any URL'), and distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on generating the specific llms.txt format. It also mentions the target output (standard markdown format), 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 'Useful for:' list provides clear contexts (getting a client's site indexed, drafting for your own project, auditing competitors), which helps an agent decide when to use this tool. It doesn't explicitly name alternative tools for when not to use it, but the examples give a strong contextual frame.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the return field list (id, type, params, created_at, last_fired_at, fire_count) and clarifies the scope to the caller's own subscriptions, which is useful beyond the annotations. 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?

Two sentences: first states the purpose and return fields, second gives usage guidance. No fluff, no repetition, and the key information is front-loaded. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description is complete. It lists return fields, states scope, and provides usage context. Annotations cover safety, and the schema covers parameters. No gaps are evident.

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 single parameter include_inactive is fully described in the schema (100% coverage), so the description does not need to add parameter semantics. The description implicitly relates to 'active subscriptions' but does not elaborate beyond the schema. Baseline 3 is appropriate when the schema handles 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 action ('List'), the resource ('subscriptions'), and the scope ('the caller's active subscriptions'). It also enumerates the returned fields, making the tool's purpose unmistakable. This distinguishes 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?

The description explicitly tells when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides concrete scenarios and implies alternatives (subscribe for adding, unsubscribe for cancelling).

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context by stating it returns a 'Single' organization, but it does not disclose not-found behavior, return format beyond the output schema, or any additional side effects.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. For a one-parameter lookup tool, this is appropriately concise.

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

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

Given the simple single-parameter nature, rich annotations, and presence of an output schema, the description is almost complete. It indicates cardinality and identification method, though it omits explicit usage boundaries or edge-case behavior, which are not critical for such a direct lookup.

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?

With 0% schema description coverage, the description must compensate, and it does by explicitly stating that the sole parameter 'id_or_slug' accepts either an id or a slug. This provides essential meaning beyond the schema's bare string type and example, though it does not detail formats or constraints.

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

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

The description clearly identifies the resource ('organization') and the access method ('by id or slug'), which distinguishes it from sibling tools like search_organizations. However, it lacks an explicit verb such as 'retrieve' or 'get', relying on an implied lookup action.

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

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

The phrase 'by id or slug' implies that the tool should be used when an exact identifier is already known, but it does not explicitly state when to use this tool versus alternatives like search_organizations. There are no exclusions or alternative tool references.

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

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

The description goes well beyond the annotations (all false) by disclosing important behavioral details: the rate limit ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for follow-up reads, and that it is 'Free; doesn't count against your tool-call quota.' It also explains the feedback process ('The team reads digests daily and signal directly affects roadmap'). This is rich contextual information not present in the annotations. No contradiction exists.

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

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

The description is long but every sentence contributes practical information: purpose, use cases, exclusions, message formatting, token handling, rate limits, and quota impact. It is front-loaded with the primary purpose and organized logically. No redundancy or fluff.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does explain the primary response: 'Filing without an account returns a `claim_token`' and that passing it back later 'Returns the status and, once resolved, what actually changed.' However, it does not specify the full response structure for the basic filing case (e.g., what happens if you file with an account), which is a minor gap for an otherwise very complete description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving guidance for the `message` parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and for `claim_token` ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This is useful beyond the schema's descriptions, though the schema itself already explains each parameter well.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (feedback submission), and distinguishes itself from sibling tools by being the only feedback channel for the Pipeworx connection. It also scopes the tool to 'tools served by this Pipeworx connection,' which disambiguates it from other MCP connectors.

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

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

Provides explicit use cases: bug, feature/data_gap, and praise, with concrete examples (e.g., 'tool returns wrong/stale data'). It includes a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' It also tells the agent how to identify Pipeworx tools, making the when-to-use guidance actionable.

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

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

Adds significant context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, return format, and caching behavior, all beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is moderately sized but well-structured. It front-loads the core purpose in the first sentence, then uses a numbered list for use cases, and ends with technical details. Every sentence adds value, though it could be slightly tightened without losing 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 tool with one optional parameter and no output schema, the description fully covers purpose, use cases, return data, privacy, and caching. It gives the agent enough context to decide when to call and what to expect in the result.

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

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

Schema coverage is 100% and the window parameter already has an enum with descriptions. The description adds extra meaning by explaining the tradeoff between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's basic definition.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window'. It names a specific verb ('Returns') and resource ('Pipeworx trending'), and distinguishes it from siblings like discover_tools by focusing on aggregate call volume rather than individual tool discovery.

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

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

Provides explicit use cases numbered 1-3, such as discovering hot data sources, confirming canonical tool choice, and aligning use cases with the majority. This gives clear guidance on when to use the tool versus alternatives like discover_tools or ai_visibility_check.

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 reveals behavioral details beyond annotations, including thresholds (>3pp, ≥0.30 Jaccard similarity, >20% placeholder fraction), the fill-check caveat that realizable_edge_pp ≤ 0 means the edge is not in the book and should not be traded, and the partition filter placeholder behavior. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with an analysis-only tool, and the description adds richness without contradiction.

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

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

Despite its length, the description is tightly packed with necessary information, uses capitalized section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to aid scanning, and includes examples. No redundant sentences.

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 two optional parameters, the description covers modes, response shapes (opportunities[], partition_check), edge cases, thresholds, and even directs users to a related tool for sizing. It is sufficiently complete to guide an agent on when to call and how to 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?

Even though schema coverage is 100%, the description deepens semantics by explaining what the tool does with each parameter: event walks child markets to check ordering and compute partition_check, while topic searches related events and flattens markets. It gives concrete examples of valid inputs like 'fed-decision-may-2026' and explains the semantic anchor constraint.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and differentiates from sibling tools by naming polymarket_fill_risk for custom sizing.

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

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

It provides explicit when-to-use guidance for each mode: no args for trending_scan, event for specific markets, topic for cross-event scanning. It explains the advantage of cross-event mode (catches date patterns), and explicitly directs users to polymarket_fill_risk for custom sizing, stating an alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: model families, per-sport α values, placeholder-slug filtering, 24h-move warnings, rare-by-design gating, and KV-level 1h caching. It also discloses why segments may be empty via filter_skips and funnel counters. This goes far 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 dense and well-structured with clear sections (model families, tradeable-edge knobs, response top-level, diagnostics), and it front-loads the core purpose. While some details are specialized (e.g., 'lognormal barrier from 90d FRED log-returns', 'Run 8 from prior 85%/5%/50:1'), they are relevant for decision-making. It is longer than necessary but every sentence adds useful context.

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

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

Given the tool's complexity, 9 parameters, and no output schema, the description is remarkably complete. It enumerates response segments, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp), diagnostics for empty segments, Fed-bet handling, and caching behavior. An agent could confidently invoke this tool and interpret results based solely on the description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning beyond individual schema entries, such as explaining that min_kelly never filters partition arbs because parent-level kelly_fraction_half is 0, and that min_partition_leg_kelly applies per-leg inside top_legs. It connects knobs to 'tradeable-edge' outcomes, giving agents a clearer mental model of parameter interactions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from sibling tools by outlining three distinct response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the use case 'what should I bet on today.' This is more than a generic scan—it explicitly describes the tool's unique edge-detection role.

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

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

The description provides clear context: it is built for agents discovering opportunities without paging hundreds of markets, and it explains when results may be empty via _diagnostics. However, it does not explicitly name sibling alternatives or state when NOT to use this tool versus tools like polymarket_arbitrage or polymarket_fill_risk, so it stops short of the explicit exclusions required for a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behavioral traits: data is built from daily snapshots, history depth is bounded by a 60-day TTL, decay numbers derive from daily closes (not intraday), and snapshot gaps occur on cache-misses. It also explains the response structure, including how expired opportunities are identified and what 'lifespan_days' means.

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 lengthy, the description is highly structured with clear sections (Args, RESPONSE, LIMITS) and front-loads the purpose. Each sentence adds substantive information, including return-field semantics and operational caveats, with no redundant filler.

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

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

With no output schema, the description fully specifies the response shape (tracked, expired, snapshot_dates) and their meanings. It also covers limitations (TTL, cache-miss gaps, daily vs intraday), making the tool's behavior and data provenance clear enough for an agent to use effectively.

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

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

The input schema already provides full coverage of both parameters (days and window) with descriptions of defaults and valid values. The description adds minimal extra meaning—repeating default/max for days and noting window as a 'snapshot family'—but does not significantly augment the schema's own 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 uses a specific, descriptive verb phrase ('Edge persistence and decay telemetry') and immediately frames the tool's core question: 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshot analysis rather than current edges.

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

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

The description provides clear situational context by explaining that a fresh wide edge and a 3-week-old wide edge are different trades, implicitly guiding when to use this tool. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to infer its purpose relative to siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, but the description adds substantial behavioral detail: it walks the order book ladder, returns top_of_book, VWAP fill price, slippage, shares_filled, and a verdict. It also warns about partial basket fills converting an arb into an unhedged directional position, which is valuable risk context beyond the annotations.

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

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

The description is long but highly structured: overview, requirement, single-market details, basket details, and usage guidance. Each sentence adds necessary information for a complex two-mode tool. The opening sentence front-loads the core purpose, and the final 'USE THIS' provides actionable context.

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

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

Despite having no output schema, the description enumerates the exact return fields for both single-market and basket modes, including per-leg fill detail, thin_legs[], and forced_directional_risk. It also covers the financial interpretation of `size_usd` in each mode, making the tool fully usable by an agent without further information.

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

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

Schema coverage is 100%, but the description enriches every parameter with mode-dependent semantics. It explains that `market` and `event` are mutually exclusive but one is required, clarifies `side` defaults for both modes, and reinterprets `size_usd` differently for single-market (max spend/target proceeds) vs basket (settlement notional, shares per leg). It also discloses clamps.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges as alternatives, and explains that this tool is the pre-trade risk check for those signals.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also details the two distinct modes (single-market vs basket) and when each applies, plus explains the failure modes the tool protects against.

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 behavior. The description adds substantial behavioral detail: it defines output structure (leg-by-leg prices, top_spreads_pp), explains compatibility_warning conditions (a and b), temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond what annotations provide, with no contradiction.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and uses bold labels to help scanning. While verbose, each section earns its place given the tool's complexity.

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

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

Given the tool's complexity and the lack of an output schema, the description thoroughly covers input modes, response fields, safety warnings, and temporal alignment. It explains return values and edge cases that would otherwise be opaque, making it effectively complete for a user 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 baseline is 3. The description adds value by explaining the two modes (topic vs explicit pairing), how explicit parameters override the topic-mapped side, and why these modes exist. That contextual information is not fully contained in the schema descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource that clearly distinguishes it from same-venue tools like polymarket_arbitrage. It further details two operation modes, leaving no ambiguity about the tool's function.

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 describes two modes (topic shortcuts vs explicit ticker/slug) and when to use each, including override semantics. It also warns that pre-mapped topics are not automatically tradeable and explains what compatibility_warning means, guiding appropriate usage and expectations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations, such as scoping to 'anonymous IP, BYO key hash, or account ID' and the dual-mode behavior (single value vs. list all keys).

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 long, front-loaded with the main action, and every sentence earns its place: definition, use case, scoping/relation to siblings. No fluff or redundancy.

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

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

For a tool with one optional parameter, strong annotations (readOnly, idempotent, non-destructive), and no output schema, the description fully covers purpose, usage context, scoping, and sibling relationships. It explains what is returned (a value or key list) by implication, and the safety profile is already annotated.

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% — the property description 'Memory key to retrieve (omit to list all keys)' already documents the parameter fully. The description adds illustrative examples (ticker, address, notes) but does not change or augment the technical semantics of the parameter.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly states the dual functionality and distinguishes the tool from its siblings (remember and forget) by explicitly naming them.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also identifies alternative tools for other operations: 'Pair with remember to save, forget to delete.'

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

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

The description states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' which implies a persistent side effect and mutation of feed state. However, annotations declare readOnlyHint: true and idempotentHint: true, contradicting the described behavior. This is an annotation contradiction, so the score is 1.

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

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

The description is four sentences and every sentence earns its place: purpose, return shape, filtering/side-effect behavior, and an alternative access method. It is front-loaded with the primary action and contains no filler.

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

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

Even without an output schema, the description adequately explains what the tool returns, how to filter, the mark_read behavior, and that polling is safe. It also points to an external fallback for automation, making the tool's role in a workflow clear. The only substantive issue is the annotation contradiction, which is captured separately.

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 describes all 5 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: it gives a concrete type example ('sec_8k'), specifies ISO timestamp format, explains the consequence of mark_read, and describes the shape of returned events (source, citation_uri, raw payload). This extra context helps an agent invoke parameters correctly.

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

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

The description opens with a specific verb+resource pairing — 'Pull fired events from your subscription feed' — and clarifies that it returns the most recent alerts written by the evaluator. This clearly distinguishes it from siblings like list_subscriptions or recent_changes, which operate on different resources.

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

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

The description gives clear usage context: filtering by type and since, using mark_read, and polling. It even notes the feed is also available at a separate HTTP endpoint for scripts and dashboards, effectively telling the agent when the MCP tool is not necessary. It does not explicitly name sibling tools for exclusion, but the context is concrete enough.

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

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

Annotations already indicate a safe read operation (readOnlyHint, idempotentHint, non-destructive). The description adds valuable behavioral details about the fan-out mechanism, fallback from GDELT to GNews on rate limits/5xx, and the soft-fail of USPTO due to PatentsView API sunset. It does not contradict annotations, and offers substantial context 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 information-dense, combining query examples, tool function, source details, and parameter guidance in one paragraph. While longer than ideal, every sentence carries useful information and is structured logically from usage examples to specifics. It is not overly verbose and remains 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?

With no output schema, the description explains the return format (changes[] grouped by source, total_changes count, and citation URIs). It also covers fallback behavior, API limitations, and parameter formats, making it a comprehensive guide for a complex multi-source tool. The annotations fill the safety profile, and the description covers the rest.

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

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

Schema coverage is 100%, but the description adds practical semantics beyond the schema: it explains `since` accepts ISO dates or relative shorthand with examples, and suggests typical values like '30d' or '1m'. It also clarifies `value` can be a ticker or zero-padded CIK, enhancing the schema's basic descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with examples like 'What's new with X'. It distinguishes itself from entity_profile by noting that entity_profile is for static profiles, making the purpose and differentiation explicit.

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

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

The description provides example queries and explicitly states the alternative tool (entity_profile) and when to use it ('Use entity_profile instead when you want the static profile... regardless of window'). This gives clear 'when to use vs. 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?

Adds context beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Doesn't contradict annotations, but doesn't specify overwrite behavior for existing keys.

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

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

Every sentence adds value — purpose, use cases, storage details, pairing with related tools. No fluff or repetition.

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

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

Fully describes behavior for a simple 2-param save tool, including persistence semantics, scoping, and relationships to recall/forget. No output schema needed for a save operation.

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

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

Schema already covers both parameters with examples. Description restates the type of content to store (ticker, address, preference) but adds no new syntax or format details 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?

States 'Save data the agent will need to reuse later' with a specific verb and resource. Clearly distinguishes from siblings recall (retrieve) and forget (delete).

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and names alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: internal cascading through lookup endpoints, auto-disambiguation of inputs, and specific return payloads (ticker/CIK/company_name, RxCUI/ingredient/brand) with citation URIs. This goes well beyond the annotation hints.

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

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

The description is well-structured with a query examples opener, a clear 'Use FIRST' directive, and a bulleted SUPPORTED TYPES section. Every sentence adds value—no fluff—and the length is justified by the need to explain two entity types and their outputs. Concise for the information density.

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 thoroughly explains return values for both types, input formats, internal behavior, and why it should be used. It fully covers the tool's purpose, usage, and behavioral traits, making it self-contained for an agent to select and invoke correctly.

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

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

Schema covers both parameters with descriptions (100% coverage), so baseline is 3. The description enriches semantics by mapping each type to its output fields and clarifying that 'value' accepts various formats (ticker, CIK, or name) with auto-disambiguation. This goes beyond the schema's basic type hints, justifying a 4.

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

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

The description clearly states the tool resolves a user-spoken name to the canonical identifier required by other tools, with a specific verb ('resolve') and resource ('NAME to official identifier'). It distinguishes itself from siblings by positioning it as the first step when an ID is needed, and enumerates supported types (company, drug) with concrete outputs.

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' It provides real-world query examples and explains that it replaces 2-3 manual lookups, making the decision to use this tool vs. alternatives clear. Though it doesn't state 'when not to use', the directive 'Use FIRST' implies prioritization over other lookups.

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

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

The description states 'List all downloadable resources', implying an exhaustive result set, while the annotations include openWorldHint: true, which explicitly tells the agent that the results may not be a closed world and should not be assumed complete. This is a direct contradiction, potentially misleading the agent about the tool's 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 a single concise sentence that front-loads the core purpose ('List all downloadable resources'), then adds essential details about resource types, input, and output. Every word earns its place with no redundancy.

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

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

The description covers the main purpose, input, and output types, and an output schema exists, so full return structure is not needed. However, the 'List all' claim directly conflicts with the openWorldHint annotation, which is a critical missing caveat about result completeness. This makes the description misleading and incomplete for correct agent 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?

The schema provides no description for the parameter dataset_id_or_slug (coverage 0%), but the description compensates fully by stating it can be an id or slug and gives an example. This clearly defines the parameter's meaning and format.

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

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

The description clearly states a specific verb ('List') and resource ('downloadable resources'), specifies the input (dataset id or slug) and output (file URLs, formats, last-update dates). This distinguishes it from sibling tools like 'dataset' which likely returns metadata.

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 unambiguously indicates when to use it: when you need the list of downloadable resources attached to a data.gouv.fr dataset. It provides the input requirement (id or slug), making the usage context clear. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the exact return content (titles, URLs, linked dataset references), giving agents a clearer picture of the operation. No contradictions with annotations.

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

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

The description is a single sentence that immediately states the action and resource. It is concise, front-loaded with the verb and target, and contains no redundant information. Every word earns its place.

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

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

For a simple search tool with an output schema and strong annotations, the description sufficiently covers purpose and return values. However, it omits pagination behavior and does not clarify optional parameters, leaving minor gaps. It is nearly complete for the tool's simplicity.

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

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

Schema description coverage is 0%, and the description does not explain the parameters. While 'query' is implied by the search context, 'page' and 'page_size' are not described, leaving agents without guidance on pagination or parameter usage. The description fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool searches data.gouv.fr reuses, defining them as third-party applications, visualisations, and analyses built on open datasets. It also specifies the return fields (titles, URLs, linked dataset references). This distinguishes it from sibling tools like search_datasets and search_organizations.

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 establishes clear scope: it is for searching reuses specifically. This implies when to use it versus searching datasets or organizations, though it does not explicitly name alternatives or provide exclusions. The context is clear enough for an agent to select this tool appropriately.

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, so the safety profile is clear. The description adds behavioral context by explaining it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core action, followed by mechanism and a concrete use case. 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?

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It explains the tool's purpose, mechanism (probes with ai_visibility_check), ranking logic, and return structure (score, confidence, signal density). It also provides an example to ground the use case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it only references entities and models implicitly. No additional parameter syntax or interpretation 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 states the specific verb 'Compare' and resource 'AI visibility across multiple entities', and immediately distinguishes the tool from single-entity checks by emphasizing side-by-side comparison and ranking. The example query reinforces its unique purpose relative to 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?

The description clearly indicates when to use the tool (competitive AI-marketing audits) and differentiates it from ai_visibility_check by explaining it probes multiple entities. However, it does not explicitly state when not to use it or name alternative tools like compare_entities, so it lacks explicit exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description adds valuable context: it is a composite call that fans out across sources, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30s and may appear in sources_failed. This goes beyond annotations to set latency and failure 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 dense but every sentence serves a purpose: core purpose, use cases, return summary, ecosystem scope, failure behavior. It is front-loaded with the main action and use-guiding phrase, though the first sentence is a slight run-on with embedded quotes. Overall, it earns a high score for structure without being excessively 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?

With no output schema, the description fully enumerates the return structure (summary block with specific fields, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, timeout behavior, and partial failure handling, making it complete for a complex composite tool.

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

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

Schema coverage is 100%, so the parameters are fully documented in the schema. The description doesn't add new semantic detail about the parameters themselves, though it implicitly references version behavior (e.g., 'latest published version' via is_latest, 'recent alternative versions'). This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('check') and resource ('should I add this npm package'), and explicitly names the data sources (deps.dev, bundlephobia). It distinguishes itself from siblings by focusing on npm package evaluation and providing a summary of what it returns.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', which directly tells when to invoke the tool. It also gives exclusion guidance for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), which serves as an alternative.

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

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

The annotations already mark this as read-only, idempotent, and non-destructive. The description goes beyond by disclosing that results include dataset titles, slugs, and resource counts, and that pagination is supported. This provides behavioral context about return shape and pagination 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?

One sentence, front-loaded with the core action, no filler. It packs essential information without redundancy.

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

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

The description, combined with rich annotations and an output schema, fully covers the tool's purpose, input semantics, and behavior. Pagination and return fields are mentioned, and the output schema handles detailed return structure. For a read-only search tool with no required params, this is complete.

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

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

With 60% schema coverage, the schema describes page, page_size, and organization, but tag and query lack descriptions. The description adds semantic context by mapping query to 'keyword' and organization to 'slug', and mentions tag. However, it does not detail the use of pagination parameters beyond 'with pagination', so partial compensation.

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

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

The description specifies a verb ('Search'), a resource ('data.gouv.fr French open-data catalogue'), and the object ('datasets'), with explicit filter dimensions (keyword, organization slug, tag) and return fields. It clearly distinguishes from sibling tools like search_organizations.

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

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

The description clearly implies usage for finding datasets in the data.gouv.fr catalogue, which differentiates it from search_organizations or reuses_search. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral specifics: keyword-based search, exact return fields, and cross-tool slug usage. It doesn't mention pagination behavior, but that is a minor gap given the strong annotations.

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

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

A single, front-loaded sentence conveys the action, target, return value, and a valuable cross-tool tip. Every word earns its place; there is 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?

Given the rich annotations, existing output schema, and simple three-parameter interface, the description is nearly complete. It covers the core query semantics and cross-tool usage, but the missing pagination context in both schema and description prevents a perfect score.

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

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

Input schema has 0% description coverage, and the description only clarifies the 'query' parameter via 'by name keyword'. The 'page' and 'page_size' parameters are entirely undocumented in both the schema and description, leaving the agent to guess at their meaning. For a low-coverage schema, the description fails to compensate.

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

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

The description clearly states the tool searches data.gouv.fr publishing organizations by name keyword and lists what it returns (names, slugs, dataset counts). It differentiates from the sibling search_datasets by explaining how slugs can be used to filter that 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 provides a clear usage context: use this to find organization slugs, then feed those slugs into search_datasets. It does not explicitly state when not to use the tool or compare it with the 'organization' sibling, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses concrete behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation and flagging. It also mentions that each passage carries an offset for verbatim quote verification, adding valuable context not available in annotations.

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

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

The description is information-dense but every sentence serves a purpose: definition, use case, pairing with sibling, and technical limitations. It is front-loaded with the main action and avoids fluff, making it efficient for an AI agent to parse.

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

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

Even without an output schema, the description explains what the tool returns (passages with character offsets and similarity scores). It also covers input size limits, truncation behavior, and recommended pairing, making it fully self-contained for a moderately complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context beyond the schema by framing 'text' as the already-fetched record and 'query' as a natural-language request, with examples. However, it does not add new syntax or type details, so a 4 is appropriate rather than 5.

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

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

The description clearly states a specific action: semantic search inside a fetched record, with the input (already-fetched text + natural-language query) and output (top-N passages with offsets and similarity scores). It distinguishes itself from siblings like ask_pipeworx_grounded by explicitly positioning search_within as the tool for searching inside a prior result rather than grounding over the whole document.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and explains the benefit: saves context and returns only relevant passages. It also names a complementary tool (ask_pipeworx_grounded) and describes the pattern of fetching with the gateway and grounding over passages, giving clear contextual 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 indicate non-read-only and non-destructive; the description adds valuable behavioral details: account prerequisites, SMS verification and cap, always-on feed with retrieval instructions. It does not contradict annotations and provides context beyond the structured hints.

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

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

The description is a single, dense paragraph with the purpose front-loaded. Some redundancy exists with the schema (e.g., delivery examples), but the extra explanations (like item code meanings) earn their place; no wasted 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?

There is no output schema, so the description should fully describe the return value; it only says 'Returns the new subscription id' without mentioning webhook secret or full response shape. It also omits guidance on managing subscriptions (listing/cancelling), though those are covered by sibling tools. Given the tool's moderate complexity, the description is serviceable but has notable 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%, providing a baseline of 3. The description adds meaningful semantics not fully in the schema, such as explaining that items:["5.02"] for sec_8k means officer change, and it gives concrete examples for delivery channels.

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 ('Create') and the resource ('proactive monitoring subscription to a live-data event stream'), differentiating it from siblings like list_subscriptions and unsubscribe by focusing on creation. It even enumerates supported subscription types, making the tool's scope unmistakable.

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

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

Provides clear context and exclusions: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), SMS requires verified phone with a 10/day cap. However, it does not explicitly refer to alternative tools (e.g., list_subscriptions, unsubscribe) for when to use them instead, so it stops short of full 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 returns category-bucketed examples from the live catalog, supports optional topic filtering, and teaches how to call meta-tools. No contradiction with annotations.

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

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

The description is long but front-loaded with example queries and tightly packed with useful information. Each sentence serves a purpose, though the run-on structure could be trimmed. It earns its length without being 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 tool with one optional parameter and no output schema, the description is quite complete. It covers when to use it, how to use it, what it returns, and even provides category examples. It doesn't describe exact return formatting, but that's a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, which already includes a description and examples. The description adds a few extra examples ('finance', 'pharma', 'betting') and explains the effect of omitting the parameter, but this largely mirrors the schema. Minimal additional semantic 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 clearly states it returns category-bucketed example questions with the exact tool and argument shape, and positions itself as the onboarding entry point. It distinguishes from siblings by referencing meta-tools like ask_pipeworx and entity_profile, making its scope unique.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without a topic. It gives clear context but doesn't explicitly name alternative tools or when not to use it, though it implies this is the starting point.

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=false, destructiveHint=false, idempotentHint=true), the description adds critical context: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. This significantly enriches the behavioral profile.

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

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

The description is three concise sentences: action, ownership constraint, and side effect. Every sentence provides unique 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?

For a single-parameter tool with no output schema, the description covers the core behavior and consequences effectively. It omits return value or error details, but given the simplicity and availabile annotations, this is a minor gap.

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

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

The schema already provides 100% coverage for the id parameter, stating it is the subscription id returned by subscribe. The description reinforces that it must be your own subscription, but adds no new syntactic or format details beyond the schema.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource, and clarifies the deactivation vs deletion behavior, making it distinct from siblings like subscribe and list_subscriptions.

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

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

It clearly implies usage for canceling subscriptions you own, with ownership enforcement stated. However, it doesn't explicitly name alternative tools for other actions, leaving the comparison to siblings implicit.

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 behavior; the description adds context about dual fast-path vs grounded pipeline and the return of verdict + citation + reasoning. Doesn't cover rate limits or failure modes, but with annotations the bar is lower and this is sufficient.

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

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

Front-loaded with trigger phrases and usage, then routing and output details. Somewhat long but every sentence carries distinguishing 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 2-param tool with no output schema, the description fully explains required input, behavioral routing, and return structure (verdict types, actual value, citation, reasoning). Enough for an agent to select and invoke correctly.

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

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

Input schema has 100% description coverage for both parameters (claim and tolerance_pct), so the baseline applies. Description reinforces claim format with examples but does not add meaning 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?

States a specific verb+resource: 'natural-language claim verification against authoritative sources.' Clearly distinguishes from general Q&A siblings by defining claim-checking behavior with trigger phrases and output verdict types.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains routing for company-financial claims vs all other factual claims. Doesn't name a direct sibling alternative, but notes it replaces 4–6 sequential calls.

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