Plan server build

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

Annotations declare readOnlyHint=true, but the description adds valuable behavioral context: it checks specific constraints, reports all problems at once, reuses existing channels/roles, and never duplicates. This goes beyond the annotation by detailing what 'read-only' entails in terms of validation and planning.

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?

Two sentences with no filler. The first sentence establishes purpose and checks; the second clarifies no changes and reuse policy. Information is front-loaded and every sentence earns its place.

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?

No output schema is provided. The description says 'reports every problem at once' but does not describe the output format (e.g., a build plan object or list of issues). This is a gap for a validation tool whose output is likely consumed by execute_build_plan. Additionally, it does not mention how the plan is staged or saved, though sibling tools exist for saving.

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 baseline is 3. The description adds meaning by explaining how to compose the blueprint (from user request, optionally using a reference layout) and clarifies the reuse semantics for existing channels/roles. This helps the agent construct the blueprint object appropriately.

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 clearly states 'Validate a blueprint against the live server and stage an ordered build plan', with specific checks (limits, collisions, permissions). It distinguishes from siblings like execute_build_plan (actual build) or get_blueprint (retrieval) by emphasizing it's a validation/planning step. The reuse policy further clarifies behavior.

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?

The description implies usage before actual building: 'Changes nothing' and 'stage an ordered build plan'. It advises composing the blueprint from a user request and optionally using a reference layout. However, it does not explicitly state when not to use or list alternatives, though the sibling set makes this clear.

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