opencdr_library_read

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety bar is lower; the description still adds meaningful semantics: the governance caveat that frozen content is not validated/approved/active, the pagination cursor name, ascending numeric ordering for versions/history, and the fleet-vs-Core authority split. It stops short of describing permissions or output shape.

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 purpose, then views, then caveats, then operational notes — a sensible ordering with little filler. The view list is dense but earns its place given the missing enum; the fleet/Core line is the least essential but is short.

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 six-parameter, no-output-schema, zero-coverage tool this leaves a real gap: it never maps which view requires which identifier (e.g., whether `version` or `release` views need content_id/release_id/version), so an agent must guess or trial-and-error. There is also no hint about what a manifest or artifact view returns, and no output schema to cover that gap.

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 0%, so the description carries the burden and does partially: it enumerates the legal `view` values (the schema declares `view` as a bare string with no enum, so this is the single most useful thing it could say) and names the pagination cursor. But `content_id`, `release_id`, `version`, and `limit` are never explained, and the description says 'next_after' while the actual parameter is `after`, which can confuse an agent about which field is the cursor.

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 ('Read') with the resource categories it covers: owner-wide drafts, immutable versions/history, and frozen release snapshots. The enumeration of views (items, item, versions, version, artifact, history, releases, release, manifest) makes the scope concrete, and the note that saved/frozen content is not active runtime content implicitly separates it from opencdr_library_runtime_source.

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 statement that saved/frozen content is not validated, approved or active runtime content gives a real cue about when this tool is the wrong choice, and 'owner-wide' implies the scope of reads. However, it never names an explicit alternative or says 'use X instead when you want active runtime content' — the routing is left to inference.

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