update_project_policy

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

Annotations only state readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds genuinely new behavioral context: the operation requires user authorization, requires reading the current revision beforehand (optimistic-concurrency semantics behind expected_revision), and enforces a validation rule that budget cannot go below already-reserved usage. These are real constraints an agent could not infer from the annotations alone.

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 clauses, front-loaded with the action and its authorization precondition, followed by the constraint. No filler; every phrase carries operational meaning.

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 mutation tool with no output schema and 0% parameter description coverage, the description covers authorization, concurrency, and one validation rule, which is a reasonable core. It still omits failure behavior on revision mismatch, whether unmentioned policy fields are preserved or reset, and the meaning of the service-level fields.

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 carries the full burden for project_id, policy, and expected_revision. It partially compensates by clarifying the budget lower-bound constraint and the meaning of expected_revision (the revision that must be read first), but it says nothing about project_id or the individual policy fields (textin, metadata, host_text, embeddings), leaving several parameters opaque.

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+resource in Chinese: 修改 (modify) 项目服务与预算 (project services and budget), which maps onto the boolean service toggles and the integer budget fields in the schema. It is clear what the tool does, though it does not name or contrast with any sibling tool (e.g. create_project or workspace_status).

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 a precondition (按用户授权 / requires user authorization) and an ordering rule (先读取当前revision / read the current revision first), which is real usage guidance. However, it names no alternative tool and gives no explicit when-not guidance, so the routing value is implied rather than stated.

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