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

With no annotations, the description carries the burden and does well: it explicitly declares this is a non-evaluating read/preparation operation, which prevents an agent from expecting it to compute applicability. It stops short of disclosing return shape details (e.g., structure/size of the vocabulary) but the enumerated content list compensates substantially.

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 sentence with the core purpose front-loaded, followed by the enumerated return contents and the downstream routing note. The enumeration is long but each item earns its place by describing returned vocabulary; 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 exists, so the description must explain returns—and it does by listing the vocabulary categories returned. For a 4-param, zero-annotation tool this is nearly complete; only the mutual exclusivity/precedence of dmc vs xml vs path is left unaddressed.

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 dmc, xml, path, and csdbDirs are already documented in the schema. The description adds no syntax or precedence guidance beyond the schema (e.g., which source wins when multiple are provided), so the baseline 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?

States a specific verb and resource ('Describe the applicability vocabulary of a data module') and then enumerates the concrete contents returned: ACT attributes, CCT condition types, PCT products, applic statements, and attributes lacking PCT values. This is clearly distinguishable from siblings like read_data_module, which evaluates rather than describes.

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?

Gives an explicit purpose ('so a product can be chosen'), states what it does not do ('Nothing is evaluated here'), and routes to the correct alternative ('pass the chosen values as "product" to read_data_module'). The condition that selects each tool is fully 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?

With no annotations, the description carries the full burden and does well on return shape (DMC parts, techName/infoName, issue, language, schema name, S1000D issue, applicability text) and paging defaults. It says nothing about permissions, error behavior, or what happens when csdbDirs overlaps the default S1000D_CSDB_DIR, which for a filesystem-scanning tool is a meaningful 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 dense sentences plus a short paging note, front-loaded with the resource and its default. The long parenthetical and comma-list of returned fields make it slightly heavy to parse, but nothing is 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 exists, so listing the returned fields is essential and done here; paging semantics are also covered. Remaining holes are secondary: the 'icn' include option and the relationship between csdbDirs and the environment default are left unexplained.

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 high (80%), so the baseline is 3. The description usefully states the dm default for 'include' and names the filterable fields, but 'title text' loosely paraphrases a filter the schema defines as matching techName/infoName, adding ambiguity rather than precision.

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 ('List the CSDB objects') and enumerates the object kinds covered, with data modules named as the default. This clearly separates it from read_data_module/read_publication_module siblings, though those siblings are never named explicitly.

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?

Browsing/filtering usage is implied by the filter and paging details, but there is no explicit 'use this when… instead of read_data_module' guidance. An agent must infer that this tool is for discovery and the read_* tools for retrieval of a single object.

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 and does well: it discloses that verification always runs (XSD by default), that applicability is evaluated per block as applicable/notApplicable/undetermined, that without a product only display texts come back, and that assert expressions are never returned. It omits failure modes for a missing DMC and any size/truncation behavior beyond the schema's 5 MB note.

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 purpose and the "not XML" contrast are front-loaded, and the dense enumeration of return contents is grouped logically. The long parenthetical content list is heavy but every clause carries information an agent needs to anticipate the output shape.

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 9-parameter, nested-object tool with no output schema, the description does the work of describing the return shape (status block, block tree, references, verification) and the applicability model. What it lacks is error/edge-case behavior (unknown DMC, unresolvable BREX) and any note on node capping interacting with the tree.

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 real meaning beyond it by explaining the consequence of omitting `product` (undetermined, display texts only) and the semantics of the applicability evaluation that `omitNotApplicable` and `product` control. The verify and section parameters are left entirely to the schema.

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

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

States a specific verb and resource (read one data module) plus a differentiating scope ("as structure, not XML") and enumerates exactly what is returned: identification/status, body tree, references, and a verification status. An agent can distinguish it from list_data_modules and read_publication_module without opening any 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?

Implies it is the structured-read counterpart to raw XML reading and points to describe_applicability for discovering product attribute/condition ids. It never explicitly names an alternative or a when-not-to-use condition, so routing is clear but not fully 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?

No annotations are provided, so the description carries the behavioral-disclosure burden. "Read" implies a non-mutating operation, and the return contents are briefly described, but there is no information about permissions, error behavior, missing files, or how the alternative input parameters interact.

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 definition is a single front-loaded sentence with no wasted text. The main action and return description come first, followed by supporting details about related ICN files.

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 read-only tool with no output schema and no annotations, the description provides an adequate sketch of returned metadata and related files. However, it does not cover usage selection among the optional input modes or behavioral edge cases, leaving meaningful 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 description coverage is 100%, and the parameters already include useful examples and constraints such as the 5 MB XML limit. The description adds no additional parameter semantics, so this sits at the baseline for fully documented schemas.

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 gives a specific verb and resource: "Read an ICN metadata file," and enumerates the metadata fields returned. It is clearly distinguishable from generic data-module tools, though it does not explicitly contrast itself with sibling tools such as read_data_module or read_publication_module.

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 states what the tool reads but gives no guidance on when to use it instead of sibling tools, nor when to choose the icn, path, or xml input modes. No prerequisites or exclusions are mentioned.

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 behavioral burden. It usefully discloses that the tool reads from the CSDB, resolves dmRef/pmRef targets, and reports verification status, but it does not explain source precedence among pmc/xml/path, failure modes, or permission requirements.

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 tightly constructed sentences with no filler. The core purpose and return contents are front-loaded and easy to scan.

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

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

There is no output schema, but the description sufficiently explains the return shape: pmEntry tree, resolved targets, PM identification, and verification status. It omits how the mutually alternative pmc/xml/path inputs are prioritized and what happens when none is supplied, which keeps it from a 5.

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 schema already documents the five parameters, including the verify enum and csdbDirs behavior. The description adds little parameter-level meaning beyond mentioning verification status, 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 gives a specific verb and resource: 'Read a publication module (PMC) as a table of contents.' It also details the key output shape, including the pmEntry tree and resolved dmRef/pmRef targets. It does not explicitly differentiate itself from siblings such as read_data_module or resolve_reference, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance, no exclusions, and no named alternatives. A reader can infer that this tool is for PMC table-of-contents reads, but the description does not say when to choose it over read_data_module or resolve_reference.

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 behavioral load, and it does disclose the return payload (paths, issues, title) and one conditional behavior for ICN resolution. It says nothing about what happens when a reference cannot be resolved (error vs. empty result), whether multiple matches can come back, or how far the search reaches beyond csdbDirs and S1000D_CSDB_DIR. Read-only nature is only inferable from "Resolve".

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 short sentences, front-loaded with the core action and its identifier vocabulary before the output and the ICN special case. No filler, and the conditional guidance is placed last where it belongs.

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 annotations and no output schema, so the description is the only behavioral source, and it does cover return values. However, with five parameters and zero marked required, the most consequential ambiguity — whether dmc, pmc, and icn are alternatives and what happens if zero or several are given — is never addressed, nor is unresolved-reference behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little for ICN: fromPath is tied to the DOCTYPE that declares the entity and produces the declared file and notation, which clarifies the payoff of supplying it. The dmc, pmc, and csdbDirs parameters receive no treatment in the description, and the relationship among dmc/pmc/icn (mutually exclusive? exactly one required?) is left unstated.

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?

A specific verb ("Resolve") applied to a well-scoped resource ("one reference to a CSDB object"), with the three accepted identifier kinds enumerated as DMC, PMC, and ICN. It also states the realized output (file path(s), issue(s), title), so an agent knows what it gets back. It stops short of distinguishing itself from siblings such as read_icn_metadata or read_data_module, leaving that inference to the agent.

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 is implied by the wording: resolve one identifier at a time and get paths/titles rather than document content, which contrasts implicitly with the read_* siblings. The one explicit conditional is useful — pass fromPath when resolving an ICN whose declaring DOCTYPE matters. There is no statement of when to prefer this over read_icn_metadata or read_data_module, and no exclusions.

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