put_project

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, but the description adds two things not in annotations: the per-mode permission requirements and the partial-update contract ('others keep their values'). It stops short of saying what happens on a name collision or what the response contains, but for an annotated tool this is solid added context.

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 with no waste: the create-or-partial-update behavior comes first, the permission requirement second. Every clause earns its place.

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?

The output schema means return values need no explanation, and the auth/idempotency picture is reasonably covered. But for a 7-parameter mutation with 14% schema coverage, the description leaves the meaning of the optional fields and the null-vs-omitted distinction entirely unspecified.

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 only 14% (only `instance` is documented), so the description must carry the burden, and it does not. Six of seven parameters (`enabled`, `visible`, `homepage`, `description`, `display_name`, `project`) are never mentioned, and it is unclear whether passing null leaves a field unchanged or clears it.

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?

States a specific verb and resource and, importantly, clarifies the upsert semantics: create a new project or modify only the given fields of an existing one. An agent can tell this is a write tool on the `project` resource rather than a read like `get_project`/`list_projects`, though no sibling is named explicitly.

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?

Gives the authorization prerequisites for each mode (create-projects role to create, project ownership to edit), which is real usage context. However, it offers no guidance on when to prefer this over `put_jobset`/`get_project` or on what to do when the project already exists.

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