Update project context

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond them: that this is a wholesale replacement of all five fields rather than a partial patch, plus the auth requirements (write scope, member role). It does not, however, note reversibility or whether omitted external state is affected.

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 short sentences, front-loaded with the replacement semantics followed by the permission constraint. Nothing is padded or redundant.

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 7-parameter mutation with no output schema and no contradictions in its annotations, the description covers the essential facts: full-replacement behavior and required authorization. Minor gaps remain (no mention that idempotency_key enables safe retries, no error/permission-failure behavior), but nothing needed to call 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 description coverage is 100%, so the baseline is 3. The description adds only one clarification beyond the schema — that all five guidance fields are replaced together — and the schema's own per-field text is generic and identical across business/audience/products/goals/agent_rules, so no field-level meaning is contributed.

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 gives a specific verb and scope ('Replace all five context fields'), which cleanly distinguishes this write tool from the read sibling get_project_context and from update_project_defaults. It is clear but does not explicitly name the sibling it pairs with, so it stops short of 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?

It states prerequisites ('requires project write scope and a member role') and implies full-replacement semantics, but never says when to prefer this over alternatives such as update_project_defaults or preview_project_defaults, nor when not to use it. Usage is implied rather than routed.

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