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

Beyond readOnlyHint=true, it discloses the auth requirement ('Requires credentials.read'), that the call is read-only, that include_repositories is slower because it walks images, and it defines the meaning of each usage_status value while warning that unknown must never be reported as empty or as having room. That is substantive behavioral context not available in the annotations.

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 core purpose is front-loaded and nearly every clause carries operational information (status semantics, the version hand-off, the include_repositories caveat). It is dense and somewhat run-on, packing many ideas into long sentences, but there is little outright filler.

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?

With no output schema, the description carries the burden of explaining return values, and it does: usage_status values are defined, the retention policy version is tied to set_registry_retention's expected_version, and the repository listing behavior is bounded. An agent has everything needed to call and interpret it.

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 coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: the top-20 cap, that the result is 'capped and said so', and that ankra-ci/** holds the pipeline's per-run build images. This is meaning the schema does not convey, though it does not cover pagination or ordering edge cases.

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 names a specific verb and resource ('Read the organisation's image registry storage on registry.ankra.cloud') and enumerates exactly what is returned: storage limit (platform default vs org-set), per-project usage/fullness, and retention policy with its version. It is clearly distinguishable from siblings such as set_registry_retention and set_registry_storage_addon.

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 gives explicit trigger conditions ('when a pipeline or build failed because the registry is full (registry_push_failed...)', 'when the user asks about registry usage or storage') and an ordering rule ('before changing retention with set_registry_retention'). The alternative tool is named, so routing is unambiguous.

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