pebble_build

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

With no annotations, the description carries the full transparency burden. It discloses that the tool executes an external command, what the return value includes (success, .pbw path, diagnostics), and a prerequisite. It does not mention side effects like writing build artifacts to disk, but for a build tool the main behavior 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 three sentences, front-loaded with the purpose, and each sentence adds distinct value: what it does, how it runs, and what it returns plus a prerequisite. No filler or redundancy.

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 build tool with an output schema, the description covers the essential context: command executed, path semantics, required CLI, and the nature of the returned data. The presence of an output schema means return values don't need to be spelled out in detail. This is complete for an agent to decide whether and how to invoke it.

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 0%, so the description must add meaning. It explains that project_dir can be absolute or relative to the workspace root, which is exactly the semantic detail beyond the raw schema. For a single parameter, this is sufficient and useful.

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 'Build a Pebble app project' with a specific verb and resource, and distinguishes from sibling tools like project_new, pebble_install, and flow_run by focusing on compiling and returning diagnostics. It immediately conveys the tool's core function.

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?

It specifies the action (runs pebble build), the project_dir parameter's path resolution, and the requirement for the pebble CLI on PATH, with a pointer to capabilities(). This gives clear context for when to use it, though it doesn't explicitly mention when not to use it or name alternatives.

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