EUR-Lex

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

The description adds value beyond annotations by disclosing cost implications for Anthropic usage (BYO key, pay directly) and default model behavior. Annotations already indicate read-only, idempotent, non-destructive, which are consistent with the probe-and-report nature. The cost warning is a significant behavioral disclosure.

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, then model details and use cases. Every sentence is informative, 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 explains the tool's purpose, parameters, and return format (per-model score, confidence, signals, raw_response) without an output schema. For a tool with 4 parameters and no output schema, this is sufficiently complete for an agent to understand and invoke correctly. Could be improved by explicitly listing the return fields in a structured way.

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 descriptions cover all 4 parameters (100% coverage), so the baseline is 3. The description adds context about default model and API key purpose but does not significantly extend parameter understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for visibility of a business or topic, providing a score (0-100) per model. It distinguishes itself from sibling tools that focus on specific domains like Pipeworx or betting, as this is a general AI visibility check.

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 identifies use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model options (default Workers AI, optional Anthropic with API key). It does not explicitly state when not to use, but the context is clear and sufficient for an agent to decide.

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, and non-destructive behavior. The description adds useful operational context: routes to sub-tools, fills arguments, returns citations, works on every tier, and is a fast single call. It does not contradict annotations, and the extra details (e.g., 'one fast call', 'default entry point') provide value beyond the safety flags.

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

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

The description is long but front-loaded with the key preference over web search and a clear list of use cases. It uses structure—bolded directives, examples, explicit alternates—to pack density without fluff. Slightly verbose for a simple tool, but every sentence contributes actionable 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?

With no output schema, the description mentions the return format (structured answer with citation URIs). It provides broad domain coverage, examples, escalation paths, and even a note about breaking-news handling. This makes the tool's role and limits clear even without additional structured metadata.

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 'question' and five aliases all documented. The tool description itself does not add parameter-specific syntax or format details, but it reinforces natural-language usage through examples ('What was Apple's revenue in 2024?'). This matches the baseline of 3 when the schema fully carries parameter semantics.

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

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

The description explicitly states the tool's function: routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with pipeworx:// citation URIs. It also names specific data domains (SEC filings, FDA data, etc.) and contrasts with siblings like ask_pipeworx_grounded and deep_research, clearly distinguishing its 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?

It provides explicit when-to-use guidance: 'START HERE for most questions', 'USE WHENEVER the user asks...' with verb triggers, and gives explicit escalation paths ('Step up only when needed' to ask_pipeworx_grounded or deep_research). It even handles edge cases like breaking news, saying ask_pipeworx already routes to live news.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: it states this 'Falls back to nothing — this IS a full working router, just the experimental edge,' clarifying it is not a stub or partial implementation. It also discloses that routing may vary when candidates are under test, and explains results are compared against the stable router. This directly addresses the risk of using 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?

The description is a single dense paragraph but covers all critical information: beta status, identical behavior to ask_pipeworx, current inactive candidate status, usage guidance, and safety reassurance. Every sentence adds value, and it is front-loaded with the most important distinction (beta vs stable).

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

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

Given the tool's simplicity (one required parameter with aliases) and complete schema coverage, the description fully covers what an agent needs: what it does, how it differs from the stable version, when to use it, and what happens if a candidate is active. The lack of an output schema is not an issue because the response shape is stated to be identical to ask_pipeworx. A small gap is not naming the compared stable tool as 'ask_pipeworx' in the comparison, but the sibling list makes that clear.

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 every parameter (including aliases) is described in the schema. The description adds the context that all arguments are identical to ask_pipeworx, reinforcing that any alias is acceptable. Since the schema already covers the parameters well, the description's contribution is modest but sufficient.

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 this is a beta variant of ask_pipeworx that routes to the same 5,529 tools with identical arguments and response shape. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements may be active, though none currently are. It could be more explicit about the core purpose (answering questions via routing) but the comparison to ask_pipeworx gives context.

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 it exactly like ask_pipeworx when you want the newest routing' and notes this currently matches ask_pipeworx exactly. It implies choosing this over the stable version when testing candidate improvements is desired, though it doesn't explicitly mention ask_pipeworx_grounded 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?

Even though annotations already declare readOnlyHint=true and openWorldHint=true, the description goes far beyond them by disclosing the refusal mechanism with exact refusal_reason codes, the output shape, the 'ONLY what the tool result contains' constraint, and the extra LLM call cost. 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 well-structured. It front-loads the core value proposition, then covers mechanism, return shape, refusal reasons, usage scenarios, and cost tradeoff. Every sentence earns its place, and the length is justified for a high-stakes 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?

Despite no output schema, the description provides the complete return shape and all refusal reason values. It also explains how it differs from the sibling ask_pipeworx and covers both success and failure modes. Given the tool's complexity, this is a fully 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 description coverage is 100% since all six properties are aliases with clear descriptions. The tool description does not add any parameter-specific semantics 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?

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from its sibling ask_pipeworx by explaining the same routing but grounded extraction, and details its mechanism (picks tool, fetches data, extracts only from result). This leaves no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also gives an alternative and cost tradeoff: 'prefer ask_pipeworx for casual lookups.' This is a model of usage guidance.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: resolution contract (market_match_confidence, suggestions), parent_event extraction, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and cancellation rule parsing. No contradictions.

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

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

The description is dense but front-loaded with the core purpose. It is well-structured into sections (classifiers, fan-out examples, response shapes, safety, etc.). Slightly long but earns its length by packing critical behavioral details. Could tighten repetitive elements.

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

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

Given no output schema and moderate complexity (3 params, diverse response shapes), the description is exceptionally complete. It explains all key response fields (market, analysis, evidence, market_match_confidence, parent_event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Compensates fully for missing output schema.

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

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

Schema coverage is 100% for 3 parameters. The description adds significant extra meaning: explains how 'market' can be slug, URL, or question text; describes 'depth' enum behavior (quick vs thorough); details 'include_raw' impact on response size. This goes beyond 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 starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It includes classifiers, fan-out examples, and response shapes, distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage which serve different purposes.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides extensive examples (e.g., BTC bet, Fed bet). Lacks explicit when-not-to-use or alternative tool references, but the sibling list provides context for differentiation.

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, and non-destructive behavior. The description adds useful context about resolving user-facing case numbers into official documents, which is a behavioral trait not captured by annotations. No contradictions.

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

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

Two sentences, front-loaded with the action and object, includes examples and usage direction. Every phrase earns its place with zero filler or redundancy.

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

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

The tool is simple (one required parameter, two optional paging parameters). The description, annotations, and schema together fully explain when and how to use it. The lack of an output schema is mitigated by the clear promise of 'FULL TEXT' and the paging parameters.

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

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

Input schema has 100% coverage with clear parameter descriptions, so the schema carries the semantic load. Description slightly reinforces that case_number accepts both case-number and CELEX formats, but this is already stated in the schema, adding no extra value beyond the baseline.

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

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

Description starts with a specific verb ('Get') and a clear resource ('FULL TEXT of an EU court judgment'), provides concrete input examples (C-97/23, T-144/25), and distinguishes from the sibling tool cjeu_search by noting it 'resolves the case number people actually cite into the 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 the tool: 'Use after cjeu_search, or whenever a case number appears in a filing or article.' This provides concrete trigger conditions and implicitly names the alternative (cjeu_search).

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, destructiveHint=false. The description adds useful context beyond these: it notes the tool returns 'the case, the court, the date and the CELEX id' and clarifies the search scope ('by subject'). It does not contradict the annotations and provides meaningful behavioral context for a read-only search operation.

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

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

The description is concise and front-loaded with the key purpose ('Search EU COURT JUDGMENTS'). It uses 3-4 sentences with no filler, includes concrete example queries, and clearly states an alternative tool. Every sentence adds value, and the structure leads with the most important information.

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

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

The description is complete for a search tool: it explains what it returns (case, court, date, CELEX id), provides usage examples, and differentiates from search_legislation. However, it says 'by subject' while the schema states query matches 'Words appearing in the case title'—this slight mismatch could mislead an agent into expecting semantic subject search rather than title keyword search. Given no output schema, the description covers return fields adequately but this nuance 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it mentions the court types (CJEU and General Court) and example queries, but these are also implied by the schema. The description does not compensate further or introduce new parameter meaning.

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

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

The description clearly states a specific action: 'Search EU COURT JUDGMENTS — the case law of the Court of Justice (CJEU) and the General Court — by subject.' It identifies the resource (EU court judgments) and distinguishes itself from search_legislation, which covers Regulations and Directives. This is a precise, non-tautological statement.

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

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

The description provides explicit guidance on when to use this tool: 'Use for "what has the CJEU said about data protection"...' It also contrasts with an alternative: 'This is case law; search_legislation covers the Regulations and Directives themselves.' This satisfies both 'when' and 'when-not' criteria.

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

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

Annotations already indicate read-only and idempotent. Description adds context about pulling latest 10-K data, handling off-calendar fiscal years, returning citation URIs, and sorting results. No contradictions.

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

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

Single paragraph includes examples, instructions, and data details. Effective and front-loaded, but could be slightly more structured (e.g., bullet points) for readability.

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

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

Given no output schema, description explains return type (paired data + citation URIs) and sorting. Lacks explicit error handling or format details, but sufficient for an agent to use correctly.

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

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

Schema covers 100% of parameters. Description enriches with detailed explanations: for type 'company' it pulls revenue, net income, etc.; for 'drug' it pulls FAERS and FDA data; values are tickers/CIKs or drug names with min/max 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?

Description clearly states the tool provides side-by-side comparisons of 2-5 companies or drugs in one call, with specific examples like 'Compare X and Y' and 'which is bigger'. It distinguishes from siblings like entity_profile and sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use and alternative. Also explains data sources and sorting by primary metric.

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, and idempotentHint=true, covering the safety profile. The description adds return map details but no additional behavioral traits like error handling or authorization. With strong annotations, the description's extra context is moderate.

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

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

Two concise sentences: first states the core action, second provides usage guidance and return summary. No unnecessary words, front-loaded purpose.

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 lookup tool with one optional parameter and no output schema, the description fully informs the agent: what it returns (map of EU corpus with CELEX ids, types, dates, summaries), how to use it (with or without query), and its role in the workflow. No missing information given the tool's simplicity.

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

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

The schema covers the single optional 'query' parameter with examples. The description adds 'name/alias/keyword' clarification and omission behavior, but this is marginal given 100% schema coverage. Baseline 3 is appropriate.

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

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

The description clearly states the tool resolves a common EU regulation name to its CELEX id, a specific verb+resource pair. It also describes the returned map with details, distinguishing it from sibling tools like search_legislation or get_article which operate on different granularity.

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 to turn a name like 'GDPR' into the CELEX id the other tools need,' providing clear guidance on when to use it as a prerequisite. It also explains the optional filter behavior ('Omit to list the whole corpus').

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, but the description goes far beyond them. It discloses the full pipeline (facet decomposition, parallel routing), output structure (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), semantic excerpting behavior, timing expectations (15-60s, thorough up to ~90s), and the meaning of depth values (quick/standard/thorough). This is exactly the kind of behavioral context that helps an agent decide correctly.

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

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

The description is long but every sentence earns its place. It is front-loaded with the most critical decision factors (account requirement, alternative tool, non-open-web nature), then explains core behavior, use cases, technical guarantees, and timing. There is no redundancy or filler; the structure mirrors the decision flow an agent would take.

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 covers the return value shape: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers edge cases (unanswerable facets, broken citations, large records, timing), auth requirements, and depth-specific behavior. For a tool of this complexity, the 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?

Although schema coverage is 100%, the description adds substantial semantic depth beyond the schema. It explains that `question` accepts broad/multi-part natural language and that decomposition is the point. For `depth`, it adds behavioral detail: 'standard' re-angles unanswered gaps, 'thorough' chases leads plus gap recovery, and 'thorough' requires a paid plan — information not present in the enum descriptions. This goes well beyond the baseline of 3.

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

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

The description opens with a clear, specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call.' It immediately distinguishes itself from open-web search and from the sibling ask_pipeworx by stating it decomposes questions and routes to 5,529 tools in parallel. The prime use case ('best for broad/multi-part questions') and alternative for single lookups are both named.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx (one LLM call, not many).' It also gives a critical exclusion: 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx — it routes to live news APIs.' Account requirements and fallback instructions ('If you are not signed in, use ask_pipeworx instead') add practical usage context.

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

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

Annotations already declare readOnly and idempotent hints. Description adds that results include full input schemas with examples and are ready to call, and that it returns top-N relevant tools—valuable behavioral context beyond annotations.

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

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

Description is front-loaded with purpose and provides a comprehensive list of use cases and behavior in 3 sentences; efficient but slightly verbose in listing domains.

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

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

Given no output schema, the description fully explains return value (tool names, descriptions, full schemas, examples). It covers when to use and parameter behavior, leaving no critical gaps for an agent deciding to invoke this tool.

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

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

Schema descriptions cover all 6 parameters at 100% coverage, including aliases and limit. The description mentions natural language query and lists example values but does not add significant new meaning beyond what the schema already provides.

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

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

The description explicitly states 'Find tools by describing the data or task' and lists many specific domains, clearly differentiating it from sibling tools which are data-retrieval or analysis tools.

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

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

Directly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing explicit when-to-use context and implying not to use when the target tool is already known.

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

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

Annotations already mark readOnly and idempotent. Description adds detail on parallel fan-out across sources, return fields, and soft-fail for patents, providing rich behavioral context beyond annotations.

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

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

Single, dense paragraph front-loaded with query examples. Every sentence serves a purpose, no fluff. Includes specific URI patterns and source details without redundancy.

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

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

Despite no output schema, description enumerates return fields (CIK, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). Covers all necessary context for safe invocation.

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

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

Schema coverage is 100%, and description adds value by explaining each parameter with examples (ticker or CIK format), noting the 'company' restriction, and clarifying that names are not handled.

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

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

Description clearly states the tool produces a full cross-source profile of a US public company in one call, with query examples. It distinguishes itself from chaining multiple single-pack lookups.

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

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

Explicitly advises to prefer this tool over chaining for holistic views, and specifies when not to use (names) with alternative tool (resolve_entity).

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 destructiveHint=true and idempotentHint=true. Description adds 'previously stored memory' but no additional behavioral context beyond the schema and 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 front-loaded sentences with no wasted words; every sentence adds value.

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

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

For a simple destructive tool with one parameter and no output schema, the description fully covers what the agent needs to know.

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

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

Schema coverage is 100% and the description does not add meaning beyond what the schema provides for the single 'key' parameter.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and is distinct from siblings (remember, recall).

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

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

Explicitly says when to use ('when context is stale, the task is done, or you want to clear sensitive data') and pairs with siblings (remember, recall).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. Description adds valuable context by explaining the process (fetches page, extracts title/description/key links, emits standard format) and the output is a text blob ready to deploy.

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: first states purpose and outcome, second explains process, third gives use cases. Concise, well-structured, and front-loaded with key info.

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

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

Despite no output schema, description explains output format and deploy location. With only 2 parameters fully covered by schema, the description is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100% (both url and max_links are described in schema). Description does not add extra meaning beyond what schema provides for parameters; it only reiterates them implicitly. Baseline 3 is appropriate.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and scope. It distinguishes from siblings like scan_competitor_ai_presence by focusing on output generation rather than analysis.

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

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

Description provides explicit use cases (indexing client site, drafting own project, auditing competitor), giving good context for when to use. It does not explicitly mention when not to use, but the use cases are sufficiently clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it returns 'full text' and 'verifiable EUR-Lex citation URL', and explains input format flexibility. No contradictions.

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

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

Two concise sentences front-load the purpose, then provide usage examples and selector formats. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description adequately covers return items (full text and citation URL) and input parameters. Given low tool complexity and full schema coverage, it provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the description doesn't need to explain all parameters, but it adds value by detailing how the 'article' parameter accepts single numbers, comma-separated lists, and ranges with suffix support, which goes beyond the schema's brief description.

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

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

The description clearly states it returns full text with citation URLs, uses specific verb 'get' and resource 'article', and distinguishes from siblings like list_articles or get_document by highlighting it as 'THE article-level grounding tool' for quoting specific articles.

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 article selector formats (single number, comma list, range) and gives examples (GDPR Art. 17, AI Act Art. 6). It implies primary use for article-level grounding but lacks explicit when-not-to-use or alternative tool recommendations.

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 context that the tool returns plain-text, includes recitals/enacting terms, and supports paging via offset/max_chars. 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 dense sentence that conveys purpose, scope, alternatives, and paging behavior without any wasted words. Front-loaded with key 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?

No output schema, but the description explains return type (plain-text of whole act) and paging constraints. Annotations cover safety. Could mention error handling or encoding, but adequate for this level of complexity.

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

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

Schema coverage is 100% with detailed parameter descriptions (lang, celex, offset, max_chars). The description mentions max_chars and offset in context, but does not add new semantic information beyond what the schema provides. 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 it returns the plain-text of a whole act (recitals + enacting terms) with paging. It distinguishes itself from the sibling get_article by specifying that get_article is for a specific Article, 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?

Explicitly states when to use this tool: 'Use for short acts or to read recitals/definitions' and when to use the alternative: 'for a specific Article prefer get_article'. This provides clear guidance on tool selection.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by listing the exact metadata fields retrieved and clarifying that full text is not downloaded, providing behavioral specifics beyond annotations.

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

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

The description is a single, well-structured sentence that front-loads the action verb 'Fetch', lists the returned fields, specifies the identifier format with examples, and adds a helpful negative constraint. No wasted words.

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

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

For a simple metadata retrieval tool with no output schema, the description sufficiently lists the returned fields and input method. It could hint at the output structure (e.g., JSON object) but the listed fields provide adequate completeness.

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

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

Input schema covers both parameters (celex, lang) with full descriptions, achieving 100% coverage. The description does not add new meaning beyond the schema; it reiterates the identifier purpose marginally. Baseline 3 is appropriate.

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

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

The description clearly states the tool fetches specific metadata fields (title, date, legal type, in-force status, citation URL) for one EU act using a CELEX ID or alias. It explicitly distinguishes from full-text download, making 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 implies usage for single-act metadata retrieval by ID/alias, and the note 'does not download full text' suggests when not to use it (for full text). It provides clear context but lacks explicit references to alternative sibling tools like get_document or search_legislation.

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, indicating safe read operation. The description adds value by stating the output structure (article numbers and headings), which goes beyond the annotations' safety 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?

Two sentences, zero waste. First sentence defines purpose and output; second sentence provides usage guidance. Front-loaded and efficient.

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

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

For a simple listing tool with two parameters and no output schema, the description fully covers purpose, output, and usage context. No gaps given the tool's complexity.

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

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

Schema description coverage is 100%; both parameters (lang, celex) are well-documented in the schema. The description does not add further semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Table of contents for an act: every Article number and its heading', which specifies the verb (list) and resource (articles of an act). It also distinguishes from sibling tool 'get_article' by noting its role in discovery before retrieval.

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 tells when to use: 'Use to discover which Article to quote before calling get_article.' This provides clear context and excludes the alternative, guiding correct invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows it's safe. The description adds value by stating it returns specific fields and defaults to active subscriptions only, which is behavioral context beyond annotations.

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

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

Two sentences: first defines purpose and output, second gives usage guidance. No wasted words, front-loaded with essential information.

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

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

The description lists all returned fields, explains the one parameter's default behavior, and gives usage context. For a simple list tool with no output schema, this is complete and sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description implicitly mentions the parameter by referring to 'active subscriptions' but does not add details beyond the schema. It is adequate but not enhancing.

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 'List', the resource 'the caller's active subscriptions', and specifies the returned fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by being the read-only listing tool.

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

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

The description explicitly guides the agent on 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 clear context for usage relative to subscribe/unsubscribe.

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

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

With all annotations false, the description carries the full transparency burden. It discloses side effects (feedback submission), rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'). 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 every sentence earns its place: purpose, conditions, exclusions, workflow, expectations, and limitations. It is front-loaded with the core purpose and uses clear paragraph breaks for scannability.

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

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

The description fully covers the tool's workflow: when to file, how to phrase feedback, what to expect (daily digests, roadmap influence), rate limits, and claim_token mechanism. Even without an output schema, it explains return behavior and follow-up usage.

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 each parameter has detailed descriptions (type enum meanings, message specs, claim_token usage). The description adds extra guidance beyond schema, such as 'don't paste the end-user's prompt' and clarifies claim_token usage. This exceeds the baseline 3 for high schema coverage.

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

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

The description opens with a clear, specific verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly scopes the tool to 'tools served by this Pipeworx connection,' distinguishing it from siblings and other MCP servers.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear when-not-to-use instructions for tools from other servers and offers a check: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, output structure (pack, tool, count), and caching behavior (5min-1h). This goes beyond what annotations alone provide.

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

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

The description is concise and well-structured: a single introductory sentence defining the tool, followed by a bullet list of use cases, and concluding with technical details. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the return content (tools, packs, volume), the source, privacy, and caching. No missing information needed for correct invocation.

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

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

Schema coverage is 100% with one enum parameter. The description adds meaning by explaining that shorter windows surface current hotness and longer windows show steady-state demand, which aids in choosing the right window. This is a useful addition over the schema's basic enum 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 it returns 'top tools, top packs, and total call volume' over a window, which distinguishes it from sibling tools like discover_tools. It uses specific verbs ('returns') and identifies the resource (Pipeworx trending data) and scope (recent window).

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent needs. It also explains the meaning of different window durations. However, it does not mention when not to use this tool or provide direct comparisons to alternatives like ask_pipeworx.

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

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

Disclosures far exceed annotations: details monotonicity checks, partition sum logic, Jaccard similarity anchor, placeholder filtering, fill check with realizable edge vs theoretical edge. 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?

Well-structured with clear sections, but slightly verbose. Every sentence adds value, though could be tightened slightly for conciseness.

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

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

Despite no output schema, description comprehensively explains response structure (opportunities[] with fields, partition_check details) and fill check behavior. No missing context for effective use.

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

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

Adds significant meaning beyond schema descriptions: explains event slug format (including URL acceptance), topic seed questions, and mode-specific behaviors. Schema coverage is 100% and description enriches each 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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying unique method.

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

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

Provides explicit guidance on when to use event mode vs topic mode, including recommended use cases and limitations. Also explains fill check for realizable edge, preventing misuse.

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

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

The description discloses extensive behavioral details beyond annotations: caching (1h at KV level), three model families with their exact formulas and models, tradeable-edge knobs, output structure including diagnostics for empty segments, and a '24h-move warning' when edge may already be priced in. Annotations only indicate read-only, open-world, idempotent, and non-destructive—this description adds substantial operational context.

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

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

The description is lengthy but well-structured with numbered segments, bold terms, and clear delineation of model families and knobs. Every sentence adds unique information, though the density may be high for some agents. It is front-loaded with the primary use case and model families.

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 complexity (9 parameters, no output schema, multiple segments), the description is highly complete: it explains the response top-level structure (by_segment, fed_candidates, diagnostics) and caching behavior. It lacks an explicit JSON output example but covers the key fields. With no output schema, the burden is high, but the description handles it well.

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 significant value beyond basic schema descriptions—e.g., explaining the relationship between min_kelly and min_partition_leg_kelly, providing default values with reasoning (slippage_pp default 0.3 with context on Polymarket spreads), and offering practical tuning guidance (bump/ drop for thin partitions).

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with the explicit use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection from model families.

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

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

The description provides explicit use context ('discover opportunities without paging hundreds of markets') and explains the three segments and when each applies. It also notes that Fed bets are excluded from ranking due to unreliable signal, offering guidance on limitations. It does not explicitly state when not to use it versus alternatives, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: limits (60-day TTL, snapshot history), decay computation details, and interpretation of negative values.

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 quite verbose and includes detailed output structure. While well-organized, it could be more concise.

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

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

With no output schema, the description fully details the response format (tracked[], expired[], snapshot_dates[] with fields) and limits, making it complete for an agent to understand expected output.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds small clarifications (e.g., days max 30) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge duration and shrinkage. It distinguishes from sibling polymarket_edges by focusing on tracking over time.

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

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

The description implies the tool is used to assess whether an edge is fresh or stale, contrasting a new wide edge with an old one. However, it does not explicitly state when to use this over siblings or provide exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, etc. It details basket behavior with thin_legs and forced_directional_risk, and explains partial fill risks. 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 a dense paragraph but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, but it could be slightly more concise. Given the complexity of the tool, it's appropriately detailed.

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

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

No output schema exists, but the description thoroughly explains all return fields for both modes. It covers edge cases (thin_legs, forced_directional_risk) and provides a verdict (clean|degraded|cannot_fill). The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: explains default side auto-selection for basket, clarifies size_usd interpretation for basket vs single-market, and mentions clamp range (10–1,000,000). This adds value beyond the schema.

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

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

The description clearly states it's a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills convert arb to directional position), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: compatibility_warning conditions (bet shape mismatch, semantic mismatch), temporal_alignment, and skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is lengthy (~250 words) but well-structured with labeled sections (modes, response, safety fields). The first sentence clearly states the purpose. Every sentence adds necessary detail given the tool's complexity.

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

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

The tool has no output schema, but the description fully explains the response structure, safety fields, and edge cases. It covers compatibility warnings, temporal alignment, and skipped comparisons. No required parameters, but the guidance is complete for agent invocation.

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

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

Schema coverage is 100% with clear description of each parameter. The description adds value by explaining the two modes and providing examples for topic parameters. It goes beyond the schema by noting that topic overrides are possible.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairings) and differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue differences.

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 explains when to use each mode (topic vs explicit) and warns that pre-mapped topics often return compatibility warnings. It does not explicitly state when not to use it, but the safety fields provide strong 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 already declare readOnlyHint, idempotentHint, and destructiveHint, which cover safety. The description adds scope details (scoped to identifier) but does not disclose significant behavioral traits beyond annotations. No contradiction with annotations.

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

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

Three sentences, each adding value: main action, examples, and pairing with siblings. No wasted words. Front-loaded with the core purpose.

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 return behavior (value for a key, list for omitted key) despite no output schema. It covers scope and pairing. Minor gap: no explicit statement about error behavior if key doesn't exist.

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 description for the `key` parameter already covers the semantics (omit to list all keys). The description repeats this without adding new information about parameter behavior 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 states the tool retrieves a saved value (via `remember`) or lists all keys if omitted. It provides concrete examples (ticker, address, research notes) and distinguishes itself from siblings `remember` and `forget` by specifying its role in the memory trio.

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

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

The description explicitly states when to use it (look up previously stored context) and implies when not to use it (save via `remember`, delete via `forget`). However, it does not explicitly state 'do not use for saving or deleting', leaving room for slight ambiguity.

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?

Discloses that mark_read mutates read state, beyond annotations which only indicate readOnlyHint: true. Adds context about return fields and that the feed is persisted. No contradiction with annotations.

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

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

Four sentences efficiently cover purpose, return fields, filtering, and alternative access. No fluff, front-loaded with key 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?

Covers most aspects but does not explicitly mention unread_only parameter. With 5 parameters and no output schema, slightly incomplete for a fully self-contained 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?

Adds examples for type (e.g., 'sec_8k') and explains mark_read effect. Schema already has 100% coverage, so baseline is 3; description adds value with usage 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?

Clearly states 'Pull fired events from your subscription feed' with specific verb ('Pull') and resource. Distinguishes from sibling tools like list_subscriptions by focusing on recent alerts from the feed.

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 guidance on filtering by type and since, and using mark_read to control subsequent calls. Mentions alternative access via direct URL, which helps agents decide when to use this tool vs. other methods.

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?

Discloses multi-source fan-out, fallback logic, soft-fail for USPTO, and output structure (grouped changes, total count, URIs). Annotations (readOnlyHint, idempotentHint) are consistent and added context.

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

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

Front-loaded with query examples, each sentence adds value, covers behavior, alternatives, and output 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?

Covers main sources and output, but lacks mention of pagination or result limits. Given complexity, slight gap but overall sufficient.

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

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

Schema has 100% coverage, but description adds practical examples (e.g., '30d' for monitoring) and clarifies value can be ticker or CIK. Enhances usability beyond schema.

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

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

Description clearly states the tool provides a change feed for a company, covering SEC EDGAR, news (GDELT/GNews), and USPTO patents, with query examples and distinction from entity_profile sibling.

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

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

Explicitly provides when to use (recent changes in a time window) and when not (static profile: use entity_profile). Includes fallback behavior (GDELT→GNews) and `since` format 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 set readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds persistence details (persistent for authenticated users, 24-hour for anonymous) and pairing with recall/forget, which goes beyond annotations without contradiction.

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

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

The description is concise at three sentences, with the most critical information (purpose and usage context) front-loaded. Every sentence adds value 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 covers all necessary context for a simple key-value store: purpose, scope (cross-session), retention behavior, and companion tools. With only 2 required params and no output schema, the description is complete.

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

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

Schema coverage is 100% with clear descriptions for both key and value parameters. The description does not add additional parameter-level information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using a specific verb 'Save' and resource 'data'. It distinguishes from siblings like recall and forget by explicitly mentioning pairing 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?

The description provides clear when-to-use guidance ('when you discover something worth carrying forward') and references companion tools (recall, forget). It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context: unresolved identifiers are listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. This goes beyond annotations to clarify failure modes and output guarantees.

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 tightly packed with useful information. It is front-loaded with user prompts and a clear purpose statement, then organized into supported types. Slight redundancy exists (examples of queries repeated in the purpose and usage sections), but each sentence earns its place given the tool's complexity.

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

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

With no output schema, the description thoroughly explains return value structure (CIK, LEI, FIGI, unresolved field, source labels), fallback behavior, and supported input variations. It covers edge cases like unavailable GLEIF/OpenFIGI and different entity types, making the tool's behavior predictable without an output schema.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description further adds examples and clarifies conditional behavior (e.g., "when a ticker is implied" for FIGI) and the exact accepted inputs per type, enriching the schema's enum and string descriptions with practical semantics.

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

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

The description clearly identifies the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific verb+resource ("resolve a user-spoken NAME to the canonical/official identifiers") and distinguishes from sibling tools like compare_entities and entity_profile by focusing on lookup of IDs rather than comparison or profiling.

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

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

Explicit guidance is given: "Use FIRST whenever you have a name but need an ID." It also lists supported entity types and gives examples of user queries, making the intended context unmistakable. It contrasts with manual lookups by noting the tool replaces 2-3 lookups, effectively positioning it as the primary identifier-resolution tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also describes the output structure (ranked list with score, confidence, signal density). 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 three sentences long, front-loaded with the core purpose. Each sentence adds value: statement of action, mechanism, use case and output. No wasted words or unnecessary 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?

Despite no output schema, the description explains the return format and includes all necessary context for agent selection. Parameter usage is clarified, tool behavior (calling another tool) is transparent, and the use case is obvious. The tool is moderate complexity; description fully compensates for missing output schema.

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

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

Schema coverage is 100% with all parameters described. The description adds meaning beyond schema: it explains that the first entity is treated as the 'subject' for narrative, and the optional context parameter serves to disambiguate common names. It also clarifies the function of models and _apiKey parameters.

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

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

The description starts with a clear verb+resource combination: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action, resource, and scope, and distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different comparison type). The example use case further clarifies purpose.

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

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

The description explicitly says 'Useful for competitive AI-marketing audits' and gives an example question, guiding when to use. It also clarifies that the first entity is the 'subject' and rest as competitors. However, it does not explicitly state when not to use (e.g., for a single entity, prefer ai_visibility_check), which would improve clarity.

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

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

The description adds behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list it if it times out. Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description enriches context.

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 purpose and is well-structured. It is slightly verbose but each sentence adds value (e.g., timeouts, fallback). Could trim minor redundancy, but overall effective.

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

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

Despite no output schema, the description explains the return structure: summary block, per-advisory detail, links, and alternative versions. It covers edge cases (partial failures, ecosystem limitation, timing). For a tool with only 2 required params, this is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'Scoped packages (e.g. "@types/node") are accepted' for package param, and 'Defaults to the latest published version when omitted' for version param. This clarifies usage beyond the schema.

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

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

The description clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the verb 'scan', resource 'dependency', and the exact ecosystem. This distinguishes it from sibling tools like 'validate_claim' or 'deep_research'.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly tells when to use and when to use 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that it queries a SPARQL endpoint and returns specific fields (CELEX id, English title, document date), which provides useful behavioral context beyond annotations.

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

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

Two sentences: first explains purpose and output, second provides usage guidance. No wordiness, front-loaded with critical information.

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

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

Given the tool has 3 parameters (one required) and no output schema, the description sufficiently explains what the tool does, what it returns, and when to use it. It is complete and actionable.

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

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

Schema coverage is 100%, so the description does not add meaningful information beyond the parameter descriptions already provided in the schema. It clarifies the overall purpose but not parameter-specific details.

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

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

The description clearly states the tool performs full-text search of EU legislation titles via EUR-Lex SPARQL endpoint and returns specific fields. It distinguishes from sibling compliance_index by explicitly stating when to use this tool.

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

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

The description explicitly provides usage context: 'Use when the act is not in compliance_index, or to find related/amending acts.' This gives clear guidance on when to use this tool versus alternatives.

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

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

Discloses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and passage offsets for verification. Annotations cover readOnly, idempotent, etc., and description adds beyond them 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?

Five sentences, front-loaded with purpose, then usage, then technical details. Every sentence is informative, 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?

No output schema, but description explains return format (top-N passages with offsets and scores) and truncation behavior. With annotations covering safety and idempotence, it's fully adequate for a search 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 covers all 3 parameters (100%), description adds example queries and reinforces character limit. Adds value beyond schema with natural-language query examples and max chars detail.

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 'Semantic search INSIDE a fetched record' with specific actions: pass text and query, get back passages with offsets and scores. It also distinguishes from siblings like ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Clear context but doesn't explicitly list when not to use or alternatives beyond the sibling mention.

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 substantial behavioral context beyond annotations: account prerequisites, delivery channel constraints (SMS cap, webhook verification), and return value (new subscription id). Annotations indicate idempotentHint true, but description's phrasing 'Returns the new subscription id' could imply new creation each time, but not a clear 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?

Well-structured with bullet-like lists for types and delivery channels. Front-loaded with main purpose. Slightly long but each sentence adds necessary detail; no redundant 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?

Covers all essential aspects: creation action, return value, account requirements, supported types with parameter details, delivery channels with constraints and behaviors. No output schema exists, so description must explain returns, and it does.

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 100% schema coverage, description adds meaning by explaining type-specific params with concrete examples (e.g., sec_8k items, delivery channels). Provides constraints and clarifications beyond schema (e.g., SMS cap, webhook signing secret one-time return).

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and specifying account requirements.

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 context for when to use: setting up monitoring subscriptions. Mentions account requirements (Pipeworx OAuth) and what is not supported (anonymous/BYO). However, does not explicitly contrast with alternatives like retrieve or delete, though context from siblings implies those are different operations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail: it returns category-bucketed questions with exact tool+argument shapes drawn from the live catalog. This complements annotations without contradiction.

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

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

The description is a single paragraph that packs essential information: alternative query phrasings, purpose, output content, and usage guidance. It is front-loaded with common questions. While dense, it is clear and not overly verbose for the complexity of an onboarding tool.

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

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

Given the tool's role as an onboarding entry point, the description covers all key aspects: when to use, optional parameter, output description (categorized questions with tool+argument shapes), and relation to sibling tools. No output schema exists, but the description sufficiently explains the return type.

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

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

Schema description coverage is 100%; the schema already describes the 'topic' parameter. The description adds value by listing example topics (e.g., 'finance', 'pharma', 'betting') and explaining that omitting the parameter gives a cross-category spread. This enriches the schema's basic description.

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

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

The description clearly states that the tool is an onboarding entry point that returns category-bucketed example questions with exact tool call shapes. It distinguishes from sibling tools by being the first tool to use when unfamiliar with Pipeworx, and explicitly contrasts with meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass the optional topic parameter (to focus) or omit for full spread. It also mentions learning to call meta-tools, providing clear guidance on when and how to use this tool versus alternatives.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds key context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts,' which clarifies the non-destructive behavior beyond annotations.

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

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

Two sentences, front-loaded with main action, no wasted words. Highly efficient.

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

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

For a simple one-param tool without output schema, description covers purpose, ownership constraint, and post-effect deactivation. No gaps.

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

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

Schema coverage is 100% with parameter 'id' described. Description adds 'returned by subscribe,' which provides origin context beyond the schema.

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

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

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. Title 'Unsubscribe from Alerts' aligns with description and distinguishes 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear constraint. However, no guidance on when not to use or alternatives is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, and the description adds rich behavioral nuance. It explains the meaning of each verdict, crucially clarifying that could_not_verify means the check did not happen and must not be treated as evidence. It also discloses the two pipeline paths (structured vs. grounded) and the citation behavior, going well beyond annotation metadata. 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?

Though longer than a one-liner, the description is dense and front-loaded with trigger phrases. Every sentence contributes: usage guidance, pipeline routing, return format, verdict semantics, and the replaced-call benefit. No fluff or repetition; the structure makes a complex tool understandable quickly.

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

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

Given the tool has no output schema, the description compensates by explicitly listing all possible verdicts, explaining the error payload, and clarifying the difference between could_not_verify and unsupported. It also covers both financial and non-financial domains, making it complete for a verification tool of this scope. The complexity is high, but the description gives enough context for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how tolerance_pct interacts with the claim wording, including the concrete use case "set 1–2 for hallucination detection where any material error must be refuted." It also gives examples for the claim parameter, enhancing understanding beyond the schema's standard description.

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

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

The description opens with clear natural-language trigger phrases and states the core action: "natural-language claim verification against authoritative sources." It distinguishes itself from sibling tools by focusing on fact-checking/claim verification, with a concrete verdict-based outcome. The return format is specific (verdict + value + citation + reasoning), making the tool's purpose unmistakable.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," giving clear when-to-use context. It also describes the internal routing (SEC EDGAR fast path vs. grounded pipeline) and notes it replaces 4–6 sequential calls. However, it does not explicitly name alternative tools or state when not to use this tool, 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.