Payments Law EU

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

The description goes well beyond the readOnly/idempotent annotations: it discloses that the service never recomputes comparisons, refuses unsupported pairs by returning the published URL, and treats reversed requests as the same artefact with inverted operations. This gives the agent critical behavioral expectations not available from annotations alone.

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

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

The description is dense and contains no filler; every clause conveys a constraint or behavior. It is somewhat run-on with heavy em-dash usage, which slightly reduces scanability, but it is still compact and information-rich.

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

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

Given the output schema and annotations, the description provides everything an agent needs to decide whether to call this tool and what to expect: supported pairs, refusal behavior, no recomputation, direction symmetry, and the fact that it is a read-only idempotent operation. The unusual 'servable iff diff artefact exists' restriction is fully explained.

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 most parameter meanings, and the description adds useful semantic context: the two version ids must belong to the same instrument, and their order is reversible with the operation direction inverted. It does not describe pagination parameters, but those are adequately implied by limit/cursor and the existing output schema.

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

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

The description states a specific operation: returning a word-level comparison of an article between two versions of the same instrument. It also clearly delimits the scope to precomputed diff artefacts (PSR and PSD3 proposal↔compromise pairs), which distinguishes it from generic comparison or retrieval tools like list_version_changes or get_provision.

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 a pair is servable if and only if a diff artefact exists, names the only supported pairs, and states that every other pair is refused. It gives a clear when-to-use rule and an explicit exclusion, though it does not name alternative sibling tools for the refused cases beyond pointing to the published URL.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it only accepts service-minted ids, returns citation metadata, and contrasts its output with get_provision's richer result. 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?

Two sentences with no wasted words. The core behavior and an example are front-loaded, followed by the key input restriction and explicit alternatives. The title also adds useful context with 'citation-compatible'.

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

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

For a single-parameter, read-only, idempotent tool with an output schema, this description is complete. It tells the agent what the tool returns, what inputs are acceptable, and which sibling tools to use instead in the relevant edge cases.

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

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

Schema description coverage is 100%, and the single id parameter is already well documented with concrete examples. The description reinforces the constraint that the id must be service-minted but does not add substantial meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: retrieval of the full text of one provision by a cite anchor id, with citation metadata. The description explicitly differentiates from get_provision (which returns more) and resolve_citation (which handles free-text citations), so an agent can tell them apart without inspecting the schema.

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

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

Provides explicit routing guidance: only accept ids this service minted, send free-text citations to resolve_citation, and choose get_provision when paging, applicability, or typed warnings are needed. This is clear when-to-use and when-not-to-use guidance with named 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 mark the tool as read-only and idempotent, and the description adds substantial non-obvious behavior: definitions are resolved to the cited act even if repealed, undefined terms are refused with suggestions rather than substituted, and references_in exposes reverse edges. These disclosures go well beyond what the structured hints 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?

Every sentence earns its place: the question front-loads purpose, and the remaining sentences each add a distinct fact about resolution, refusal, or reverse-edge behavior. Although dense, there is no filler or repetition of schema content.

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

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

With a rich output schema and 100% parameter coverage, the description does not need to restate return structures. It covers critical edge cases such as repealed citations, undefined terms, and corpus-wide scope, making it largely complete. It lacks explicit routing guidance relative to sibling tools, but that gap is already reflected in usage_guidelines.

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

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

The input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds interpretive value by explaining resolution policy, the no-substitution rule for unknown terms, and the meaning of reverse-edge references, which helps an agent understand both the term and comparison parameters more deeply.

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 concrete interrogative that captures the tool's core function: what a term means, where, and since when. It then enumerates distinctive outputs — verbatim and resolved definitions, clustering, chronological/concurrent views, and word-level comparisons — which clearly separate it from siblings such as compare_versions and search_defined_terms.

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 constraints and behavioral context, such as resolution following the CITED version and refusal for undefined terms, but it never explicitly states when to choose this tool over alternatives like compare_versions, get_provision, or search_defined_terms. The usage context is implied rather than spelled out.

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 signal read-only, idempotent, and closed-world behavior, but the description adds substantial behavioral nuance: operative_cite can lack an operative_locator and operative_locator_unavailable reports this; amenders outside the corpus surface under source_external with via_article; and there is deliberately no article index. These are exactly the edge cases an agent needs to interpret results 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 dense but every sentence earns its place: purpose, relationship semantics, missing-locator sentinel, external amender handling, sibling routing, and parameter guidance. It is front-loaded with the core purpose and contains no filler.

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

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

Given an output schema exists, return-value details are already covered. The description adds the operational edge cases, names the relevant siblings, and explains the on_date behavior. For a complex legal-instrument tool, this is a complete and actionable definition; the only minor gap is instrument_id documentation, which is inferable from the tool name.

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

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

The description adds meaning to on_date by calling it the 'multi-axis appplicability record on that date,' which goes beyond the schema's 'ISO date; returns full aplpicability record.' However, the required instrument_id parameter has no description in the schema and no elaboration in the description, so parameter semantics are only partially compensated at 50% 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?

Starts with a concrete question and enumerates the returned facets: metadata, dates, lifecycle/application events, and curated relationships. It explicitly names sibling tools (get_provision, list_provisions) and explains the boundary, so an agent can distinguish it from close alternatives.

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

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

Description gives clear context: use get_provision to open related articles, and use list_provisions when looking for an article index. It also tells the caller to pass on_date when the applicability record is needed. It does not exhaustively state when not to use get_instrument, but the routing guidance is strong.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral detail: the prose is editorial and labelled as such, it has no legal weight, omitting the pathway returns the catalogue, and an unknown id is refused with nothing substituted. This goes well beyond the annotation baseline.

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 core purpose and each sentence adds distinct information: content of a pathway, editorial/legal caveat, and parameter behavior. It is compact with 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?

With one optional parameter, rich annotations, and an output schema present, the description covers purpose, usage, content shape, failure behavior, and catalogue access. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the pathway parameter. The description reinforces the omit-for-catalogue behavior and adds the failure mode for unknown ids, which provides extra semantic value beyond the schema.

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

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

The description opens with a concrete user need ('Where do I start... in what order?') and defines the resource as curated reading pathways into the corpus, with ordered waypoints, cite anchors, defined terms, and pitfalls. This clearly distinguishes get_orientation from the sibling search and fetch tools.

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

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

The description gives clear context for when to use the tool: when a user needs a starting point and reading order on a subject. It also provides an exclusion ('never legal weight') and explains catalogue versus pathway behavior, though it does not explicitly name alternative sibling tools for comparison.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it guarantees pagination by structural block with no silent truncation, reveals the version refusal behavior with a published URL, and mentions provenance and text-state disclosure. This gives the agent accurate expectations for response quality and edge cases.

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 carry all the essential information: purpose, output format, pagination guarantee, and version behavior. The most useful scoping question is front-loaded, and every sentence earns its place.

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

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

For a retrieval tool with readOnly/idempotent annotations and an output schema, the description covers the non-obvious behaviors an agent must know: pagination, refusal of pinned versions, and text-state disclosure. No critical selection or invocation behavior is missing.

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

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

Schema description coverage is 80%, and the schema already documents locator.kind, cursor, on_date, and version_id. The description adds a concise restatement of the version_id policy ('the service serves one text per instrument') and implicitly explains cursor via pagination, but it does not materially expand meaning 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 names a specific verb ('Returns'), a clear resource ('operative text of an article, annex or recital'), and the output form ('as markdown, with its cite anchor, provenance and text-state disclosure'). It distinguishes itself from siblings like get_instrument or list_provisions by focusing on a single provision's content.

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 opening question 'What does this provision say?' clearly signals the intended use, and the pagination and version_id guidance tells the agent how to handle large provisions and pinned versions. It does not explicitly mention sibling alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only and idempotent, so the safety profile is clear. The description adds value by revealing pagination and the specific filter dimensions (status, category, core/supplementary, in-force-on-date), which are beyond what annotations provide. 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?

Two sentences with no filler; the core purpose is front-loaded in a memorable question. The workflow second sentence is slightly convoluted—'emumerate each instrument with list_provisions' could be misread as listing instruments rather than provisions—but it remains compact and useful.

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

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

An output schema exists, so return structure needs no description. The description covers the main filter categories, pagitation, and connects to the relevant sibling tools in a workflow. Minor gaps: default ordering, whether filters combine additively, and the precise meaning of 'in force' are not stated, but these are not critical for calling 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 description coverage is only 33%, so the description must compensate. It does so by mapping filters to parameters: status, category, core/supplementary (is_core), in-force-on-date, and pagination (limit/cursor). It does not clarify the exact format of limit/cursor or category values, but the schema covers status and in-force-on-date formats.

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 'What is in the corpus?' which immediately frames the tool's purpose: listing instruments in the corpus. It names the specific resource (instruments), the operation (list), and key behaviors (paginated, filterable), and clearly distinguishes it from siblings by outlining a workflow with list_provisions and get_provision.

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

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

The description gives explicit usage guidance: 'For corpus-coverage questions, filter by category here' and suggests a workflow using list_provisions and get_provision. It implies this tool is for broad corpus exploration rather than targeted retrieval, though it does not explicitly state when not to use it or contrast with search tools.

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

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

Annotations already mark the tool as readOnly and idempotent, and the description goes beyond that by disclosing that items are metadata-only and that each carries a locator usable by get_provision. It also explains the default kind behavior, adding useful context that annotations do not capture.

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 with no filler: the first identifies the resource and metadata nature, the second states defaults and the recital override. Every clause earns its place and the purpose is front-loaded.

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

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

The output schema covers return values and annotations cover safety, so the description need not restate those. However, with six parameters and no schema-level descriptions, the semantics of limit, cursor, topic, and chapter are left to inference, making the definition incomplete 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?

With schema description coverage at 0%, the description must compensate, but it only explains kind and indirectly instrument_id. Parameters limit, topic, cursor, and chapter receive no semantic guidance, leaving most of the six-parameter surface underspecified.

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 question identifying the resource: provisions contained in an instrument. It specifies 'Metadata only' and connects to get_provision by noting each item carries the exact locator that tool accepts, which differentiates it from its 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?

The description gives clear selection context by stating that articles and annexes are returned by default and that kind=recital switches to recitals. It implies that full provision content belongs to get_provision, but it does not explicitly list when-not conditions or compare against search-related siblings.

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

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

Annotations already carry readOnlyHint and idempotentHint, but the description adds non-obvious behavior: editorial materiality markers are always present in every response regardless of filters, and the response states the basis of the mechanical classifications. This is valuable context beyond the structured annotations and gives the agent accurate expectations.

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

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

The description is compact and front-loads the core purpose and filter possibilities. The additional sentences about materiality markers and mechanical classifications earn their place by explaining non-obvious response behavior. The opening rhetorical question and slightly ornate wording could be trimmed, but it is not padded.

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 that an output schema exists and annotations cover safety and idempotency, the description supplies the essential behavioral context and filter semantics. The main missing piece is what happens when version ids are omitted and how pagination defaults work, but this is a minor gap for a list operation with structured information present.

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 50%; status, articles, material_only and from_version_id have some schema description. The description adds meaning by tying filters to status/materiality/article range and by interpreting the version pair as 'two published texts'. But limit, cursor, instrument_id and to_version_id remain undocumented in both schema and description, so the gap is only partly compensated.

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

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

The description states a specific action and resource: it lists aligned articles with their classifications across two published texts of an instrument, and names the filtering dimensions. It does not explicitly name or contrast sibling tools such as compare_versions, so it falls just short of full sibling differentiation.

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 intended use is implied: call this tool to see what changed across a whole instrument between its two published texts, with filters on status, materiality and article range. However, it gives no explicit when-not-to-use guidance or alternatives, so an agent may not know how to route away from compare_versions or other siblings.

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

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

The description adds significant behavioral detail beyond the readOnlyHint and idempotentHint annotations: it defines the exact confidence tiers (exact, strong, ambiguous), explains how ambiguity is flagged, and discloses the special handling for citations to instruments outside the corpus (named with CELEX and ELI rather than guessed at). This is rich, concrete behavioral information that helps the agent anticipate outputs.

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 core question, then provides dense, useful detail about output categories and out-of-corpus behavior. It contains no fluff and every sentence adds meaning, though it could be slightly better structured as a list 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 covers the tool's core behavior, confidence levels, and edge-case handling, while annotations cover side-effect safety and an output schema exists. The main gap is the absence of guidance around limit/cursor pagination and explicit routing among sibling tools, but the essential invocation context is present.

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

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

Schema description coverage is only 33%, with citeration fully documented in the schema but limit and cursor left undocumented. The tool description also does not explain limit or cursor semantics or how they affect candidate ranking or pagination. Since the description does not compensate for the low schema coverage, parameter semantics are under-specified.

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

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

The description clearly identifies the tool as a citation resolver: it explains what question the tool answers ('What does this citation refer to?') and specifies the output as ranked candidates with confidence classifications. This distinguishes it from sibling tools like get_instrument or get_provision, which imply direct retrieval rather than candidate ranking and ambiguity resolution.

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

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

The description implies usage context by emphasizing that the input is 'a citation in any form a reader would write', but it does not explicitly state when to prefer this tool over alternatives like search_legislation or get_instrument. It provides no exclusions or when-not guidance, so the agent must infer the appropriate use case from the description alone.

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

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

Annotations already cover read-only and idempotent safety, so the description adds useful behavior beyond them: exact output fields, the fact that it returns only top hits, lack of advanced options, and the fetch integration. It doesn't mention result limits, but the output schema already reduces that gap.

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

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

Two sentences with no filler: the first states purpose and output upfront, the second routes to the alternative. Every phrase earns its place, including the integration hint with fetch.

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 one-parameter read-only search with an output schema, the description is complete. It covers what the tool returns, the compatibility contract, the alternative for richer needs, and the relationship to fetch. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100% and the single query parameter already has a clear description ('A single query string'). The tool description doesn't add extra query syntax or formatting details, so the schema carries the semantic weight; a 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 names the operation ('search over the corpus'), the output shape ('top hits as {id, title, url}'), and the defining trait ('OpenAI-compatible', 'id is the cite anchor fetch accepts'). It also differentiates itself from search_legislation, so an agent can select the right tool without opening schemas.

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

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

It explicitly says when not to use this tool: 'For filters, snippets, scores and paging use search_legislation'. The mention of the citation-compatible id also implies the intended use with fetch, giving both an inclusion and exclusion 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: matching is restricted to the term itself, never the definition body, and divergence is evaluated on both resolved and verbatim text, with the nuance that same-root pointers count as agreement. It also discloses that the output excludes definition text, which is beyond what annotations provide.

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

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

The description is dense but every sentence earns its place: it states the purpose, the output shape, the matching restriction, the subtle divergence semantics, and the key parameter usage. It is front-loaded with the core purpose and avoids fluff.

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

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

Given the output schema, annotations, and generally descriptive input schema, the description covers the important behavioral subtleties well. The only clear gap is that limit and cursor are left unexplained in both schema and description, but the presence of an output schema and standard pagination parameters reduce the risk.

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

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

The schema already documents query, instrument, and only_divergent well, so the description does not need to repeat that. It does add value by explaining the resolved-vs-verbatim divergence reasoning and the same-root agreement rule, and by reinforcing that matching never considers the definition body. However, limit and cursor remain undocumented in both the schema and the description, so parameter coverage is not complete.

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

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

The description opens with a precise question—'Which instruments define this term, and do they agree?'—and defines the output as a listing of term, definers, and divergence flags with no definition text. This clearly distinguishes it from siblings like get_defined_term, which would provide definition content rather than an instrument-level listing.

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

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

The description gives clear context for when to use the tool: to find which instruments define a term and whether they agree. It also gives explicit guidance on the only_divergent parameter to filter for disagreements. It does not explicitly name alternative tools or state when not to use this one, but the usage context is unmistakable.

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 rich behavioral detail: ranking order, hit fields, 320-character snippet limit, topic narrowing, acronym ranking hints, and initialism expansion. However, it directly contradicts annotations.openWorldHint=false by stating 'Absence of a result is not evidence that no relevant law exists,' which asserts open-world semantics. Per the rubric, a direct annotation contradiction scores 1.

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

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

The description is dense but front-loaded: purpose first, then hit behavior, then caveats and alternative workflow. Most sentences earn their place, though it runs long and could be tightened by merging repeated cautions about snippets and topic coverage.

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 7-parameter tool with an output schema, this is otherwise thorough: it explains result contents, ranking, query resolution, topic behavior, snippet limits, and the correct alternative workflow for coverage questions. The only serious completeness issue is the annotation contradiction, already scored separately.

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

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

Despite schema coverage of 71%, the description adds substantial meaning beyond the input schema: citation-grammar resolution, acronyms as ranking hints, expansion of defined-term initialisms, topic-as-filter semantics, snippet length, and in_force_on_date semantics tied to list_instruments. This compensates well for undocumented params like limit and cursor.

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?

Opens with 'Where does the corpus discuss X?' and defines a precise verb/resource: full-text search across articles, annexes, and recitals with a specific ranking. It also distinguishes itself from sibling tools like get_provision and list_provisions, making its role clear.

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

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

Explicitly guides coverage questions to list_instruments by category, list_provisions by topic, and get_provision, and warns that 'a page of hits is not a sweep.' It also explains when citation-shaped queries route through the citation grammar, giving clear when-to-use vs. when-to-use-alternative guidance.

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