resolve_reference

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.