zcode_models

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that catalog is filterable and NOT ranked, that select mutates state at three scopes, and critically that server scope "affects only newly spawned runtimes in this process and does not persist." That is exactly the kind of non-obvious side-effect an agent needs. It omits what the `current` action does and any auth/permission caveats for select.

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-loads the core purpose, then walks the actions in a logical order with zero filler sentences. The quoted action names and asides are stylistic but each clause carries information. Dense and slightly telegraphic, yet nothing is wasted.

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?

The schema defines four action branches (catalog, available, current, select) inside an anyOf, but the description only explains three — `current` is never mentioned, leaving an agent to infer it. There is no output schema, which is acceptable, but with no annotations and a complex union schema the omission of one action branch is a real completeness 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 100%, so the baseline is 3 and the schema already documents min_context, session_id, model, scope and provider. The description adds meaning at the action level (filterability, non-ranking, scope persistence) rather than adding per-parameter detail the schema lacks. Adequate, but it does not extend parameter meaning beyond the already-documented 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?

States a specific verb+resource pair ("Discover models and providers, and select one") and then decomposes it into named actions, so the agent knows this is the model/provider discovery-and-selection surface. It is distinguishable from siblings like zcode_settings or zcode_session by resource, though it never explicitly contrasts with them. A clean, concrete purpose that stops short of true sibling differentiation.

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?

Explicitly routes between the two read actions: catalog is "the decision surface" while available "reports what the runtime has wired up (a different question)." It also frames catalog as deliberately unranked because "choosing a model is the job of the caller," which tells the agent what work it must do itself. It does not state prerequisites (e.g., needing a session_id for session scope) or when not to use select.

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