platform_versions

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

With no annotations provided, the description carries full behavioral burden and does real work: it discloses that versions are immutable, that publish operates on the 'current draft with raw-DSL hash guard' (mapping to expectedDraftSourceHash), and critically that legacy create/promote do NOT perform HTTP calls but return migration guidance — preventing an agent from assuming a write succeeded. Gaps remain (auth requirements, return format, failure behavior), but for an annotation-less tool these disclosures are genuine value-adds.

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 message 'Manage immutable agent versions' is front-loaded, but the leading '[Arch Build] Arch creates and changes...' preface is a meandering domain statement that repeats 'Arch' and adds little selection value. The structure is undermined by the action-list mismatch: it enumerates six actions while the schema has eight, and the legacy create/promote sentence arrives separately, forcing the reader to reconcile a self-inconsistent account. Moderate efficiency with a structural seam.

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?

This is a high-complexity dispatch tool: 8 enum actions, 10 parameters, 3 required, no output schema, and no annotations. The description covers the action surface, immutability, and legacy behavior, which is a solid core. But it leaves return format entirely unspecified (no output schema to compensate) and does not map which parameters apply to which action — an agent must infer param-action coupling from the schema alone. Reasonably complete on actions, lacking on call-level detail.

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 90% (high, above the 80% threshold), so the baseline is 3 even with no parameter prose in the description. The description does add context by tying expectedDraftSourceHash to the publish 'raw-DSL hash guard' and flags the promote 'status' param as legacy via the migration-guidance note. It does not restate or enrich the other parameters, but that work is already done well in the 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?

"Manage immutable agent versions" states a specific resource and operation set, distinguishing it from sibling platform_* tools like platform_agents and platform_deployments. However, the enumerated action list (list, get, publish, qualifications, audit, diff) omits 'create' and 'promote' that appear in the schema enum, and the final sentence then references 'Legacy create/version-promote' — an internal inconsistency that slightly muddies the intended action surface.

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 versus the 40+ sibling tools. The description mentions that legacy create/promote 'return migration guidance without HTTP calls,' which is a soft excluder, but it never states which tool should handle version creation or promotion now, nor when to prefer platform_versions over platform_deployments/platform_agents. Usage context is only implied from the resource name.

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