Read one supplier

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 explicitly states 'Reads only.' (read-only) and specifies the returned content, which gives an agent a clear picture of side effects (none) and response scope. It also discloses the lookup method (by SUP number or name), adding transparency beyond the title.

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 tight sentences that front-load the action and return scope, with no filler. 'Reads only.' is an efficient safety signal.

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 read with no output schema, the description covers the input (SUP or name), the returned field set, and the read-only nature. Its only omission, behavior for ambiguous names, is already handled by the schema description, so nothing an agent needs 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?

The schema already describes the supplier parameter at 100% coverage, so the baseline is 3. The description's phrase 'by SUP number or name' restates the schema's id/name disambiguation without adding new constraints, formats, or detailed semantics. Therefore it adds no meaningful parameter information 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 states a clear verb and resource ('Read one supplier record in full') and enumerates the content scope (contact fields, payment terms, lead time, notes, last reviewed). This differentiates it from sibling tools like supplier_list (reads many) or supplier_update (mutates). Title reinforces the single-record read.

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 for retrieving a complete single supplier record by identifier, and the 'Reads only.' line signals it is not for updates. However, it does not explicitly name alternatives such as supplier_list or supplier_due_review or state conditions for when not to use it, leaving some inference required.

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