we_project_apply

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

The description goes meaningfully beyond the annotations by disclosing the write pipeline: candidate validation first, then a persistent checkpoint before any mutation, plus revision-based concurrency via expectedRevision. The mention of 'deletions' sits in mild tension with destructiveHint=false, but the description itself supplies the mitigating mechanism (a persistent checkpoint, supported by the we_project_restore sibling), so this reads as author intent rather than a contradiction.

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 dense sentences with the action front-loaded and zero filler; the second sentence adds behavior rather than restating the first. Nothing could be cut without losing information.

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 batched, mutation-capable tool with no output schema and zero schema-level descriptions, the definition covers purpose and the write pipeline but omits operationally important details: atomicity of the change batch, what error surfaces on revision mismatch, and path-containment guarantees. Adequate as a minimum viable definition, but not complete.

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 0% across three required, non-trivial parameters, so the description must carry the load. It clarifies that paths are project-relative, content is UTF-8, a null/omitted content means deletion, and expectedRevision drives optimistic concurrency — useful but incomplete, since the 1-100 item limit, the 64-hex revision pattern, and validation-failure behavior remain undocumented.

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 states a specific verb and resource ('Apply project-relative UTF-8 writes/deletions') plus the governing mechanism ('using expectedRevision'), so the operation is unambiguous. It does not, however, distinguish itself from near-neighbors like we_project_validate, we_publish_prepare, or we_project_restore, which is what separates a 4 from a 5.

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 explicit when-to-use guidance, no statement of prerequisites, and no named alternative. An agent must infer from the sibling list that this is the tool that actually commits changes while we_project_validate only checks them and we_project_restore rolls back.

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