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

With only readOnlyHint=true in the annotations, the description carries the behavioral load and does so: it explains that a single-form/single-source row reads as it always has while multi-form or multi-source rows gain version_count, source_count, first_edition_seen and last_edition_seen, and that stale records persist because the Union keeps records no current catalog prints. That is genuine beyond-annotation disclosure of response shape and edge-case behavior.

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 long and meandering, with awkward prose ("reads exactly as it always has") and the core purpose buried in a question before several sentences of edge-case detail. The routing note to the one-record get appears late, so the most decision-relevant information is not front-loaded and much of the middle could be tightened without loss.

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, so the description must explain returns, and it does cover row shape, conditional fields, and the stale-record case reasonably well. It is still unclear on the overall list contract (ordering, pagination behavior, what a row minimally contains when only one form/source exists), leaving the agent with an incomplete picture of what to expect for a 5-parameter list tool.

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 does add a small amount beyond the schema — clarifying that the learning unit may appear "as a source or substitute," where the schema only says "a course named in it" — but it says nothing about limit/offset pagination semantics beyond what the schema already documents, so the added value is marginal.

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 first sentence states the resource concretely — comparability bundles, glossed as published transfer rules — and the closing line differentiates it from the sibling one-record get ("The forms themselves ... come from the one-record get, never from a list"), establishing this as the list/find side. The verb is only implied by the question phrasing rather than stated, but an agent can still tell what it returns and how it differs from get_comparability.

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 names the three optional filters and tells the agent that an empty result is a valid answer ("Answers none held when the build holds none"), which is useful context. It also routes form-level retrieval to the one-record get. However, there is no explicit statement of when to prefer this tool over the close siblings comparability_for_learning_unit or get_comparability — the routing is inferred from one sentence rather than declared.

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