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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavioral facts: values are auto-extracted and not individually reviewed, source_document may describe a whole model series rather than the single model, an empty result is signalled explicitly, and OceanSphere holds no stock. Those caveats materially change how an agent should present and trust the returned data, which annotations alone could not convey.

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

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

Front-loaded with the action and the returned fields, then the data-provenance caveats; no sentence is filler. The field enumeration overlaps slightly with the existing output schema, and the closing 'does not hold stock' line is a domain caveat rather than core invocation guidance, but both are short 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?

For a zero-required-parameter read tool with a full output schema, the description supplies exactly the parts structured data cannot: how to identify the model, the reliability of extracted values, the series-level scope of source labels, empty-result behavior, and the stock caveat. Nothing an agent needs to call it correctly or interpret the response 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 100% and every parameter already documents its role, including the model_ref/designation alternation, so the baseline is 3. The description reinforces the 'exact designation' requirement and the pairing with manufacturer, but adds no syntax, format, or precedence detail beyond what the schema states (e.g. what happens if both model_ref and designation are supplied).

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 and resource ('Get one library model') and immediately names the two accepted identity modes ('model_ref from a search, or manufacturer + exact designation'). It then enumerates the returned fields (category, ship area, page URL, datasheet link, technical characteristics), which is enough for an agent to distinguish this single-record lookup from the search/list siblings without opening a 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?

It tells the agent how to reach this tool (take a model_ref from a search, or supply manufacturer + exact designation) and adds a hard rule for the empty case: 'never guess specifications in that case.' What is missing is an explicit negative case naming when to prefer search_equipment_models or find_by_manufacturer instead, though the 'from a search' phrasing implies the sequencing.

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