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

Annotations declare non-read-only, non-idempotent, non-destructive, but the description adds substantive behaviour beyond them: drafts create no deployment, work without a selected cluster, resume existing open drafts, and re-seed another org's profile as a suggestion draft. That is real context the annotations cannot convey.

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-loaded with the core action, then mode selection, then the follow-up toolchain, then a one-clause safety statement. Dense but every sentence carries distinct information; 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?

Although there is no output schema, the description supplies the lifecycle context an agent needs (start → compose → inspect → publish) and the draft/deploy boundary. Nothing required to invoke it correctly 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 coverage is 100% so the baseline is 3, but the description adds value the schema does not: it frames name and profile_id as mutually exclusive alternatives selecting NEW vs EXISTING mode, and notes that optional fields are 'new profiles only'. That combination semantics is genuinely useful beyond per-field descriptions.

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 (start) and resource (stack profile BUILDER draft), defines what the resource is ('organisation-level reusable template'), and contrasts it against the publish path. An agent can distinguish it from create_stack_profile and add_addon_to_stack_profile_draft without opening a schema.

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 enumerates the two calling modes (name for new, profile_id for existing), notes resume behaviour for an open draft, cross-org seeding, and states 'Nothing deploys'. It also chains the full workflow with add_addon_to_stack_profile_draft / add_manifest_to_stack_profile_draft, get_stack_profile_draft, and publish_stack_profile_draft.

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