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 mark it read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context: it routes to one of many sources, fills arguments, returns structured answers with pipeworx:// citation URIs, and works across tiers in one call. It does not detail failure behavior or result shape, but this is not a major gap for a read-only lookup tool.

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

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

The description is front-loaded with the key selection message and keeps the most important guidance first. It is dense and includes examples and route-to-alternative guidance, though a few operational details ('works on every tier', 'free account') are slightly beyond the core selection criteria.

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 broad scope and no output schema, the description covers what the tool does, when to prefer it, how it behaves, and what alternatives exist. It mentions structured output with citations but does not specify the exact response format or failure behavior; still, the guidance is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema documentation covers all six parameters, including the aliases for question, so the description does not need to add parameter-level detail. The description supplies illustrative example questions but no new semantic meaning beyond the schema's natural-language explanation.

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

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

The description states a specific purpose: ask_pipeworx answers factual questions about real-world data by routing to one of 5,724 tools and returning a structured answer with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research 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?

It explicitly tells the agent when to use it ('Use whenever the user asks ... even if web search could also answer it'), declares it the default ('START HERE'), and provides step-up rules: ask_pipeworx_grounded for grounded single answers and deep_research for broad/multi-part questions.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses live experimental behavior: candidate routing improvements may be active, none is active right now, and this is a full working router rather than a fallback. This is exactly the kind of reliability context an agent needs before relying on a beta tool.

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

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

Although it contains several sentences, every sentence carries essential information: identity, current status, usage instruction, and fallback clarification. The most important scoping facts are front-loaded before the operational details.

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

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

It covers identity, equivalence, live behavior, and response-shape parity with ask_pipeworx, which is substantial for a router with no output schema. It stops short of describing the exact response payload, but that gap is mitigated by the repeated statement that this matches ask_pipeworx exactly.

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 question and its five aliases already fully documented in the input schema. The description only reinforces that the arguments are the same as ask_pipeworx and adds no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States it is the beta version of ask_pipeworx, a universal router covering 5,724 tools with the same arguments and response shape, so the object and scope are explicit. It also distinguishes itself from the stable sibling by calling out the experimental routing edge.

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

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

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes when no candidate is active it currently matches ask_pipeworx exactly. This gives an agent a clear condition for choosing this beta over the stable variant, and even warns that there is no fallback.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: it extracts only from tool results, returns evidence and confidence, and provides an explicit refusal structure with enumerated refusal_reason values. The cost of one extra LLM call is also disclosed, which helps an agent decide when to invoke it.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, output contract, usage scenarios, and cost tradeoff are all conveyed without fluff. The key distinction and the refusal behavior are front-loaded before usage guidance.

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

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

For a grounded question-answering tool, the description is complete: it explains the routing approach, the constrained extraction, the exact success and refusal return shapes, the refusal reasons, and when to prefer the sibling. The lack of an output schema is mitigated because the return contract is fully described in prose.

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 is fully covered: the sole meaningful parameter, question, is described as accepting natural language and lists all six aliases. The description does not add extra parameter-level meaning, but with 100% schema coverage the baseline of 3 is appropriate; there is no gap for the description to fill.

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 a hallucination-resistant answer mode for high-stakes reads, with a specific extraction behavior: it answers using only what the tool result contains. It also distinguishes itself from ask_pipeworx by emphasizing grounded extraction and explicit refusals, so an agent can tell them apart without opening the schema.

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 whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. It also names the alternative, ask_pipeworx, and states the tradeoff — one extra LLM call — with a clear preference for ask_pipeworx on casual 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?

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 mark readOnly, idempotent, non-destructive, and open-world, and the description adds significant behavior beyond that: parallel decomposition, findings-packet structure, gaps[] never invented, contradictions[] for standard/thorough, semantically excerpted records, resolvable citation_uri semantics, hop field, and 15-90s latency expectations. It also clearly states the tool is NOT open-web search, aligning with openWorldHint rather than contradicting it.

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

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

The description is long but exceptionally dense and front-loaded, opening with the account requirement and the preferred alternative. Nearly every sentence carries unique operational guidance, though it does slightly overlap with the schema's depth parameter descriptions and could be tightened with paragraph breaks or bullet-like structure.

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 explains the return shape (findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), latency expectations, auth prerequisites, and behavioral caveats like gap reporting and semantic excerpting. For a complex research tool, an agent has enough to select it, invoke it, and interpret its output.

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

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

Schema coverage is 100% and the schema already documents both parameters well. The description adds value beyond the schema by explaining depth behavior ('re-angles unanswered gaps', 'chases the best leads'), the paid-plan implication of thorough, and that broad/multi-part questions are acceptable. This is more than the baseline, though not exhaustive detail beyond what the schema already conveys.

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: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search. It also names sibling ask_pipeworx and clarifies that deep_research is 'Best for broad/multi-part questions', making the differentiation from siblings clear.

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

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

Provides explicit when-to-use and when-not-to-use guidance: use for broad/multi-part structured research, use ask_pipeworx for single lookups or breaking/current-news topics, and notes the account/paid-plan requirement up front. The alternative tool is named directly, leaving no ambiguity about routing.

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?

The description goes far beyond the annotations by explaining subtle behaviors: compatibility warnings, temporal alignment semantics, the never-pairing of unknown legs, skipped comparisons, and the omission of Kalshi fees. It explicitly notes that null temporal_alignment means 'could not be computed' rather than aligned, preventing a serious misinterpretation. Annotations indicate read-only/idempotent behavior, and the description does not contradict any of 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 long and dense, but it is well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes), which helps an agent parse it efficiently. Some redundancy exists, such as re-emphasizing that both modes share the same matcher and that compatibility fields should be read even when pairs are returned, though these are low-cost safety reinforcements. Overall, the density is justified by the tool's complexity, and the most important warnings are front-loaded.

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

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

There is no output schema, so the description carries the full burden of explaining the response structure, safety fields, codes, skipped counters, fee disclosure, and failure modes. It covers leg-by-leg prices, spread entries, compatibility codes, temporal alignment nuances, and unclassified leg handling. For a tool with this level of output complexity, the description is exceptionally 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 already 100%, so the baseline is 3. The description adds meaningful semantics by explaining the relationship between the topic mode and the explicit override fields, and by elaborating on what the shortcuts resolve to. It thus enriches the bare schema definitions with mode-specific context that an agent needs to select 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 clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question, with a specific focus on matched outcomes and spread in percentage points. It distinguishes itself from sibling tools by emphasizing the cross-venue, same-question scope, and it lays out the two operational modes without ambiguity. This is a specific verb+resource description rather than a generic one.

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

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

The description provides explicit guidance on when to use each mode: pre-mapped topic shortcuts for common macro questions and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics are not necessarily tradeable and that the tool is for observing gross spreads, not net edges. This is clear, actionable guidance with appropriate caveats.

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 the operation read-only, open-world, and idempotent, but the description adds substantial behavioral context beyond that: it may return figi_candidates instead of asserting an ambiguous match, states unresolved identifiers explicitly under 'unresolved', degrades gracefully when GLEIF or OpenFIGI is unavailable, and cascades through multiple lookup endpoints. No statement contradicts 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 opening is front-loaded with purpose, examples, and a 'Use FIRST' directive, and there is little filler. However, the 'company' branch is a dense multi-clause wall of text that mixes acceptable inputs, ambiguity behavior, ownership data, and failure modes in one long parenthetical, making it less scannable than it could be.

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

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

With no output schema, the description compensates fully by naming the exact identifiers returned per type, source attribution, ambiguity output, unresolved field, and graceful degradation behavior. For a two-parameter, multi-endpoint tool, this is complete enough for an agent to call it correctly without additional lookups.

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, but the description greatly enriches the meaning of both parameters. It explains the 'type' enum thoroughly and gives exact accepted forms for 'value' (ticker, CIK, ISIN, name, brand, generic), plus a concrete formatting warning: pass the entity name only, never the full noun phrase. This goes well beyond the schema fields.

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

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

The description names a specific verb ('resolve'), a resource ('user-spoken NAME'), and an output ('canonical/official identifiers other tools require as input'), then enumerates the supported types: company and drug. It also differentiates from sibling tools by framing this as the identifier backstop ('Use FIRST whenever you have a name but need an ID').

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

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

The description gives an explicit trigger condition—'Use FIRST whenever you have a name but need an ID'—along with concrete example phrasings and type-specific input rules. It does not name sibling alternatives or state when not to use this tool, so the when-not case is left 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?

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?

The description adds substantial behavioral context beyond the annotations: it distinguishes 'could_not_verify' (check did not happen) from 'unsupported' (no source exists), warns that 'could_not_verify' must not be shown as evidence, and explains the routing logic (SEC EDGAR fast path vs. grounded pipeline) and the inclusion of verbatim evidence and citations. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it opens with natural-language trigger phrases, states the purpose, explains the dual paths, lists the output verdicts, and includes a critical caveat. No fluff or repetition of schema content.

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

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

With no output schema, the description fully enumerates the possible verdicts, explains the meaning of the ambiguous ones ('unsupported' vs 'could_not_verify'), describes the error structure (verification_error with stage/detail), and notes that it replaces 4–6 sequential calls. This is complete for a tool of moderate complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for the 'tolerance_pct' parameter, explaining it overrides the claim-wording default, is capped at 5, and offers guidance for hallucination detection (set 1–2). It also gives concrete claim examples, enhancing the schema's existing examples.

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

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

The description clearly states the tool's purpose with specific verbs like 'fact check', 'verify', and 'confirm or refute', and defines it as 'natural-language claim verification against authoritative sources.' It also distinguishes its two main paths (SEC EDGAR+ XBRL for company-financial claims vs. grounded pipeline for all others), which sets it apart from sibling tools without 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear context. However, it does not explicitly name alternative tools or state when not to use the tool, though the scope is broad enough that this is only a minor gap.

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