Plumb · studio start (references + brand + open session)

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

The description discloses that the tool mutates state (builds a board, opens a session) and specifies the outputs (sessionId, name, brand, references). This adds context beyond the annotations (readOnlyHint=false) by detailing what is created. It does not mention destructive behavior or idempotency, but the creation-oriented nature is clear.

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 description is efficiently structured: a bold 'STEP 1' header, a concise three-sentence body that covers the function, flow position, outputs, and prerequisite. Every sentence adds value, and the most critical information is front-loaded.

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?

Given the tool's complexity (multiple sub-actions), the description comprehensively covers the workflow, outputs, and flow integration. No output schema is provided, but the description lists return values. It also mentions the required plugin and gives follow-up steps, making it complete for an agent to use correctly.

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 each parameter is already documented. The description provides minimal additional meaning beyond the schema: it clarifies 'one-line brief' and default for count, but does not add substantial new constraints or format details. Baseline 3 is appropriate.

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 the tool's purpose as 'STEP 1 of the transparent studio flow' and details the actions: discover references, screenshot, synthesize palette, build board, open session. It distinguishes itself from sibling tools by specifying it's the first step and naming the subsequent tools (plumb_studio_kit, plumb_studio_page).

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 explicitly outlines the usage context: it's the initial step in a flow, with clear follow-up instructions ('Follow with plumb_studio_kit(sessionId), then plumb_studio_page(sessionId, …)'). It also mentions a prerequisite ('Requires the Plumb plugin to be paired'). However, it does not provide explicit when-not-to-use scenarios or alternatives beyond the flow.

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