update_project

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

With no annotations provided, the description carries the full behavioral disclosure burden. It usefully reveals that changes are applied immediately ('Attach/detach role writes immediately') and that the response reports members, weight, and affects_projects. It does not mention persistence, rollback, or side effects, but given the output schema exists, this is a reasonable level of disclosure.

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 brief and front-loaded with the tool's core purpose in the first sentence. The second sentence is compact but somewhat cryptic ('Attach/detach role writes immediately'), sacrificing clarity for brevity, so it is not a perfect 5.

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?

This is a high-complexity mutation tool with 16 parameters, no annotations, and no parameter descriptions, yet the description covers only role-related behavior and omits the other fields it can update. It also fails to explain how this relates to sibling tools like create_project, delete_project, or update_role, leaving an agent under-equipped to invoke it correctly across its full parameter surface.

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%, so the description must compensate for 16 undocumented parameters, but it only hints at role attachments/detachments. Terms like add_core, add_skills, include_global, and remove_on_demand are not explained, and the phrase 'Attach/detach role writes' does not map clearly to the many parameter names.

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 ('update'), resource ('project map'), and mode ('incrementally'), which distinguishes it from create_project and delete_project at a basic level. However, it does not fully advertise the breadth of writable fields (name, repo, notes, skills, etc.), so differentiation from sibling update_role/update_skill is only implicit.

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 phrase 'incrementally update' implies the intended use for partial modifications, but the description gives no explicit guidance on when to prefer this over create_project, delete_project, or update_role. It also provides no prerequisites such as requiring an existing project or a particular working_folder context.

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