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

With no annotations, the description carries the full burden. It transparently states the tool parses and reports structure, clearly implying a read-only analysis. It does not disclose error handling for invalid XML or file-not-found cases, but the core non-destructive behavior is well conveyed.

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

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

The description is two sentences, front-loaded with the action and specific outputs, and includes a practical usage note. Every sentence earns its place with no redundancy.

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

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

The description enumerates the exact output fields, which is valuable given no output schema is present. It gives a clear use case and sufficient detail for an analysis tool, though it does not mention handling of invalid input or mutual exclusivity of the two 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?

Schema description coverage is 100%, so the baseline is 3. The description's 'string or file' echoes the xml/file parameters, but the schema already provides detailed descriptions for each parameter, so the description adds little extra semantic value.

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

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

The description clearly states the tool parses a CERIF XML document and lists the specific structural elements it reports (root element, namespace, attributes, entity counts, total elements, max depth). This distinguishes it from siblings like validate_xml (validation) and extract_entities (entity extraction).

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 says it is useful for understanding existing CERIF data before extending it, providing a clear usage context. However, it does not explicitly mention alternatives or when not to use it, such as preferring validate_xml for schema validation.

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 no annotations, the description carries the full burden of behavioral disclosure. It reveals key output aspects (namespace, date, sourceDatabase) and instructs validation, but does not disclose the return format (e.g., XML string vs. file), error behavior on invalid fragments, or any side effects. This is a moderate level of transparency given the tool's complexity.

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

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

The description is two sentences, front-loaded with the main action and specific details. The first sentence delivers the purpose and key attributes, while the second gives a critical usage instruction. Every word earns its place; there is no redundancy or fluff.

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

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

Given no output schema and no annotations, the description should explain the return value and edge cases. It covers the main workflow and mentions validation, but does not specify what the tool returns (presumably an XML string) or what happens on invalid input. For a moderately complex tool with five parameters, this is a noticeable gap, but the core usage is still 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 coverage is 100%, providing a solid baseline. The description adds further meaning by explicitly linking the 'blocks' parameter to fragments from build_entity/build_link and highlighting the role of 'date' and 'sourceDatabase' in the document. This goes beyond the schema descriptions, enriching parameter understanding.

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

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

The description clearly states the tool's function with a specific verb ('Wraps') and resource ('entity/link fragments from build_entity / build_link') and the final output ('a complete CERIF 1.6 XML document'). It also distinguishes itself from siblings by referencing the fragment builders and the validation step, making its role in the workflow explicit.

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

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

The description provides clear context for when to use the tool: after building entity/link fragments with build_entity/build_link. It also instructs to always validate the result with validate_xml, offering a specific follow-up step. It does not explicitly state when not to use it, but the workflow is well implied.

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

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

Since no annotations are provided, the description carries the full behavioral burden. It discloses that an id is automatically generated, that language-dependent elements receive cfLangCode/cfTrans attributes, and that the tool handles scalar child elements. It doesn't mention the return format or side effects, but for a builder this is reasonable. It adds useful behavioral context beyond the schema.

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 and efficient. The first sentence states purpose, the second explains the values parameter with examples, and the third points to the sibling tool. Every sentence earns its place 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?

Given that there is no output schema and the tool has nested object parameters, the description explains the fragment-building concept and the role of build_document. It doesn't explicitly state the return type (e.g., an XML string), which is a minor gap, but overall it provides enough context for an agent to understand when and how to use it.

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

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

The schema description coverage is 100%, so the baseline is 3. The description provides examples of value names (cfFamilyNames, cfBirthdate) and mentions language handling, but these largely mirror the schema's own examples. It doesn't add significant new parameter-level semantics beyond what the schema already documents.

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 'Builds a single top-level CERIF 1.6 entity element' which is a specific verb and resource, and it gives concrete examples (<cfPers>, <cfOrgUnit>, <cfResPubl>). It also distinguishes itself from siblings by naming build_document as the tool for wrapping fragments into a full 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?

The description explicitly states 'Use `build_document` to wrap fragments into a valid CERIF document,' which tells the agent when to choose an alternative. It also explains the intended usage pattern by indicating that build_entity creates a fragment and build_document composes the final document.

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 no annotations provided, the description carries the full transparency burden. It discloses important default behavior: omitted classId/classSchemeId default to 'unclassified'/'cerif', and sides can be omitted for placeholders. It does not mention output format or validation, but the core construction behavior is clear.

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

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

The description is two sentences, front-loaded with the primary purpose and then concise usage constraints. Every clause contributes information, with no filler or repetition of schema details.

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

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

For a 10-parameter tool with no output schema, this description covers the key decision points: side specification, classification defaults, and optional dates/fraction. It omits details about the `values` parameter and the exact return structure, but the overview is sufficient for an agent to select and invoke the tool correctly in most 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?

The input schema already describes all 10 parameters, with 100% coverage, giving a baseline of 3. The description adds meaningful semantics by explaining the `sides` vs `idA`/`idB` relationship and the classification default, which are not apparent from the schema alone.

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

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

The description opens with 'Builds a linking entity element (e.g. cfProj_Pers, cfOrgUnit_Class) connecting two CERIF entities,' which is a specific verb+resource with concrete examples. This clearly distinguishes it from sibling `build_entity` by emphasizing the linking nature.

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 explains how to provide side IDs via `sides` or `idA`/`idB`, and points to `get_scheme` for canonical classification terms. However, it does not explicitly state when not to use this tool or name an alternative like `build_entity` for non-link fragments, so it lacks explicit exclusions.

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

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

With no annotations, the description must carry the transparency burden. It reveals that the tool returns XPath, id text, and child count, and that it accepts a string or file. However, it states 'all instances' while the schema's limit parameter caps results (default 20), which is a significant undisclosed behavior. It also does not mention read-only status, error handling, or ordering.

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

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

The description is two sentences: the first states purpose and output, the second provides a concrete example. It is front-loaded, efficient, and contains no fluff.

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

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

For a tool with no output schema and no annotations, the description explains the tool's core function and output fields, which is helpful. However, it omits the limit behavior (despite the schema), and does not clarify return structure or error cases. These gaps prevent it from being fully complete.

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

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

The schema has 100% description coverage for all 4 parameters, so the baseline is 3. The description adds minimal param-specific meaning; it mentions 'string or file' which is already implied by the xml/file parameter descriptions. It does not enrich the understanding of entity, limit, or the input alternatives beyond what the schema already states.

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

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

The description clearly states the tool 'Extracts all instances of a given entity element from a CERIF document' and specifies the output fields (XPath, id text, child count). The example 'list every <cfOrgUnit> or <cfProj_Pers>' clarifies the use case. This distinguishes it from siblings like get_entity (single entity) and list_entities (entity type list).

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

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

The description provides clear context for when to use the tool: to extract all instances of a specific entity element from a CERIF document. The example reinforces this. However, it does not explicitly mention alternatives or situations where this tool should not be used, 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals the output structure (category, primary id, child elements, linking entities) and input flexibility (friendly names or exact element names). It does not mention error behavior (e.g., unknown entity name) or any side effects, but as a read-only lookup tool, the transparency is adequate.

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

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

The description is two sentences, front-loaded with the core purpose, and every phrase contributes meaningful information. No filler or redundancy; it is efficiently structured and easy to parse.

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

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

For a single-param tool with no output schema, the description is complete: it explains what the tool returns, what inputs it accepts, and gives examples. It lacks only edge-case details like not-found errors or case sensitivity, which are minor given the simple scope.

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

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

The schema description already covers the single parameter fully (100%), but the tool description adds extra examples of friendly names (person, project, publication) and exact names (cfPers, cfProj, cfResPubl), reinforcing the accepted formats. This adds value beyond the schema and clarifies naming conventions.

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 'Returns the full definition of one CERIF 1.6 entity' and enumerates what that definition includes (category, primary id element, child elements, linking entities). This specific verb+resource+scope distinguishes it from sibling tools like list_entities, which lists entities rather than returning a single entity's detail.

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?

Usage context is clear: use this tool when you need the full detail of a single entity, as opposed to listing all entities or working with schemes. It does not explicitly exclude alternatives, but the 'one CERIF entity' wording strongly implies the scope. No direct comparison to sibling tools is provided.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. The word 'Returns' strongly implies a read-only operation with no side effects, which is a positive signal. However, the description omits details about error handling for unknown schemes, response format, or any access/permission requirements. For a simple retrieval tool, this is minimally adequate but not rich in transparency.

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

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

The description is two sentences and extremely efficient. The first sentence delivers the core action and resource, while the second explains practical application. Every word earns its place, and it is front-loaded with the essential information. No fluff or repetition.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description gives sufficient context for an agent to know what to expect: it returns a full term list and explains why one would use it. It could be even stronger by outlining the structure of the returned list or handling of invalid scheme names, but the description is solid 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?

The input schema already fully documents the 'scheme' parameter with a clear description and examples. The tool description adds a small amount of context by mentioning what the pairs are used for, but this does not significantly enhance the parameter understanding beyond what the schema provides. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the primary function with a specific verb ('Returns') and a specific resource ('full term list of a CERIF classification scheme'). It distinguishes itself from sibling tools like list_schemes by focusing on retrieving the terms of a single scheme rather than listing schemes or entities. The use case for finding cfClassId/cfClassSchemeId pairs adds further clarity.

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

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

The description provides explicit guidance on when to use the tool: 'Use to find the exact cfClassId / cfClassSchemeId pairs used when classifying entities.' This gives practical context that differentiates it from potentially similar tools. However, it does not explicitly mention when not to use it or name alternatives, so it stays one step short of the top score.

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?

No annotations are provided, so the description must carry the behavioral disclosure burden. It does add context about the catalog composition (293 total) and that query searches names and descriptions, which is helpful. However, it does not explicitly state that the operation is read-only, the default limit is 100, or describe the response format. For a list tool, this is acceptable but not fully transparent.

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

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

The description is two sentences, front-loaded with the purpose and valuable counts, followed by concise parameter guidance. Every word earns its place; no fluff.

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

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

With no output schema, the description should compensate by clarifying the return structure. It mentions the catalog and that query searches names/descriptions, hinting at return fields, but it does not explicitly state the response format, default limit behavior, or whether results are paginated. For a listing tool with 3 params, this is a gap but not severe.

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

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

The input schema already provides full descriptions for all three parameters (kind, limit, query), with 100% coverage. The description essentially paraphrases the schema ('cap results' for limit, 'search names and descriptions' for query) without adding new syntactic or format details beyond what the schema provides. The baseline of 3 applies.

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

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

The description clearly states the tool lists the CERIF 1.6 entity catalog, with specific counts for each category. This distinguishes it from sibling tools like get_entity, which retrieves a specific entity. The verb 'Lists' and resource 'entity catalog' are specific and 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 explains parameter usage ('Use `kind` to filter...') but does not explicitly state when to use this tool versus alternatives like get_entity or list_schemes. The usage context is implied ('catalog'), but no explicit when-to-use or when-not-to-use guidance is given.

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

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

No annotations are provided, so the description bears the full burden. It discloses that the tool lists schemes and that query filters names and terms, but it does not describe the return format, pagination, default limit, or whether user-defined schemes are excluded. This is adequate for a simple read operation but lacks depth.

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

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

The description is two sentences, front-loaded with the primary purpose and examples. Every word contributes value; no fluff or repetition of schema details.

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

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

For a low-complexity tool with two optional params and no output schema, the description covers the core purpose and parameter behavior. It could be slightly more explicit about what the response includes (e.g., scheme metadata and terms) and when to prefer sibling tools, but it is largely sufficient.

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

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

The input schema provides 100% coverage with clear descriptions for both 'limit' and 'query'. The description adds minor reinforcement ('query filters scheme names and terms') but does not meaningfully extend the schema's semantics, 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 the tool's purpose: 'Lists the canonical CERIF classification schemes (vocabularies) curated for common use' with specific examples. It distinguishes from sibling tools like list_entities and get_scheme by specifying the resource type (classification schemes) and the curated nature.

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

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

The phrase 'curated for common use' implies this is the default for standard schemes, and the optional query filter suggests search usage. However, it does not explicitly mention when not to use it or direct users to alternatives like get_scheme for specific schemes, so guidance is only implied.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It accurately describes the search behavior, input forms (string file), and output (XPath), but does not explicitly state that the operation is read-only, nor does it mention how errors or conflicting xml/file inputs are handled.

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

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

The description is two sentences, front-loaded with the action and resource, and includes relevant input examples and output details (XPath). Every sentence contributes meaning without unnecessary repetition or fluff.

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

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

The tool has 4 parameters and no output schema; the description covers the core purpose, input types, and output type (XPath). However, it does not specify behavior when both xml and file are given, nor describe the return structure in detail beyond 'with XPath'. This leaves some edge-case ambiguity, making it adequate but not fully 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 the baseline is 3. The description adds value by providing concrete examples for the query parameter (ORCID, project ID, DOI) and clarifying that matching is against id element text. This enriches the parameter semantics beyond the schema descriptions.

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

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

The description clearly states the tool's function: searching a CERIF document for id elements matching a query and returning XPaths. It uses a specific verb ('searches') and resource ('CERIF document'), and distinguishes from sibling tools by focusing on id lookup rather than validation, extraction, or entity management.

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 mentions a use case ('useful for cross-referencing links') but does not explicitly explain when to use this tool instead of siblings like validate_xml or analyze_document. Usage is implied but not contrasted with alternatives, so the guidance is only partial.

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?

No annotations are provided, so the description carries the full burden. It discloses the exact steps (namespace replacement, schemaLocation update, release attribute removal), the return value (migrated XML plus change log), and the recommendation to validate. This is transparent for a migration tool, though it does not mention error handling or 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?

The description is well-structured with numbered steps, and the validation note is essential. While a bit longer than minimal, each sentence adds value and is front-loaded with the main 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?

Given two parameters, no output schema, and no annotations, the description covers inputs, the migration process, return content, and a validation recommendation. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters (xml and file), with descriptions already explaining their roles. The tool description adds the alternative relationship between the two but no extra syntax or behavioral details. 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 migrates a CERIF 1.5 XML document to CERIF 1.6, with explicit steps and a reference to validate_xml for validation. This distinguishes it as the migration tool among siblings (which include validation and build 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?

It provides clear usage context by instructing to always validate the result with validate_xml, which tells the agent a next step. It does not explicitly exclude alternatives, but no other migration tool exists among siblings, so this is adequate.

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 no annotations, the description carries the full burden. It discloses that the tool reads from the local filesystem and validates, implying a non-mutating operation. However, it does not explain the outcome of validation (e.g., error reporting, return format) or any side effects beyond 'reads', leaving some behavioral ambiguity.

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

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

The description is two sentences with no filler. The first sentence states the action and object, and the second sentence provides a usage scenario. Every word earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the core purpose, input source, and typical usage. It doesn't specify what the validation returns, but the mention of 'schema confirmation' implies a result. Since the tool is simple, the completeness is sufficient, but it could add a note about success/failure output for full clarity.

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's phrase 'local filesystem' reinforces the path parameter. The description adds minimal meaning beyond the schema, which already states the path is an absolute path, 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 uses specific verbs ('Reads', 'validates') and names the exact resource (XML file against CERIF 1.6 schema). It also distinguishes itself from siblings by mentioning 'local filesystem', which sets it apart from a likely generic validate_xml 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 states when to use this tool: 'Use when the agent has written a CERIF file to disk and needs schema confirmation.' It provides clear context but does not mention when not to use or name alternatives, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: validation against an official schema, in-process execution, and the specific error types and locations returned. It does not explicitly state that the operation is non-destructive or mention side effects, but for a validation tool, the read-only nature is strongly implied and the description adds meaningful 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 two sentences that are dense with actionable information: purpose, schema reference, output details, and usage guidance. Every sentence earns its place with no filler or repetition.

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

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

Given the single parameter, no annotations, and no output schema, the description is complete. It specifies what the tool does, the schema, the return format (error types and locations), and even the intended iterative usage. There are no significant gaps for an agent to select and invoke this tool correctly.

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

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

The schema already covers 100% of the parameter with a clear description. The tool description adds value by clarifying that the input is an 'XML string' (emphasizing inline content, not a file path) and by naming the exact schema version used, which helps the agent understand what format is expected.

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

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

The description clearly states a specific verb ('Validates'), a specific resource ('CERIF 1.6 XML string'), and the target schema ('euroCRIS CERIF_1.6_2.xsd'). This distinguishes it from the sibling `validate_file` (which likely operates on files, not inline strings) and other 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?

It explicitly advises using `validate_xml` iteratively during failures and suggests `build_*` tools as an alternative for constructing valid fragments. This provides clear usage context, but it does not explicitly contrast with `validate_file`, so it stops short of full exclusions or alternative discrimination.

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