Read available ZCode models

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

With no annotations, the description carries the behavioral burden well: it discloses the 24-hour cache lifetime, refresh triggers (provider settings change or cache expiry), the retry behavior (re-reads provider config), and a specific response-shape quirk (current_model=null on cache responses). These are non-obvious operational details that meaningfully help correct invocation. It stops short of stating rate limits or full error semantics.

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 front-loaded with the core action and then layers in cache/refresh behavior and a response hint. Three sentences, each carrying distinct operational information with no 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?

Given a single-parameter read tool with an output schema, the description covers cache semantics, refresh triggers, retry behavior, and a response-shape edge case (current_model=null). This is substantial for a tool of this complexity; only explicit when-to-use guidance 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 0% for the single `workspace` parameter, but the description implies the catalog is workspace-scoped ("for this workspace"). The description provides contextual meaning for the parameter even though it does not document its format or constraints; baseline 3 is appropriate given the minimal parameter surface.

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 specific verb ("Read") and resource ("models and reasoning levels") for the workspace, which clearly distinguishes it from state-mutating siblings like zcode_set_default_model or zcode_clear_default_model. It could better differentiate from zcode_default_model, which likely returns the current default, but the catalog scope is reasonably clear.

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?

No explicit when-to-use or when-not-to-use guidance is provided, nor are any sibling tools named as alternatives. The agent must infer that this is called to discover available models before, e.g., selecting one via zcode_set_default_model.

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