Maintain

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say what state is mutated (the schema hints at version bumps and tag overrides), what permissions are needed, or that operations may partially fail. No contradiction, but no added behavioral value.

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?

It is short and front-loaded, but the second sentence ('Core workspace organization, configuration, and maintenance') is filler that earns no place — it just re-labels the tool. This is under-specification rather than true conciseness, though it wastes no words.

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 13-parameter tool that appears to span several actions (maintain, setup, template, save, maintain_status, fleet_evidence_check) and mutates version/tag state, the description leaves critical context unstated: the action model, prerequisites, and scope of changes. The presence of an output schema excuses return-value detail, but not the missing purpose and dispatch explanation.

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 schema itself documents all 13 parameters in detail (including cross-action notes for part, force, projects, auto_start, install). The description contributes no parameter meaning at all, so the baseline of 3 for high schema coverage applies.

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 is essentially a restatement of the name: 'Maintain (rm_workspace). Core workspace organization, configuration, and maintenance.' It names no specific verb+resource outcome and does nothing to separate this tool from siblings like rm_workspace_setup, rm_workspace_template, rm_workspace_save, or rm_workspace_maintain_status. An agent cannot tell what 'maintain' concretely does.

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?

There is no when-to-use, when-not-to-use, or alternative-selection guidance anywhere in the description. The schema repeatedly references actions ('for maintain', 'for setup', 'for template', 'for save', 'for maintain_status'), implying a multi-action dispatch that the description never explains or routes. The agent is left to infer everything.

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