advance_project

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

Annotations only say non-read-only, non-destructive, closed-world; the description adds substantive behavior well beyond that: the patch is committed as a new Context version first, read-write project authorization is required, and the backend dispatches the next role and blocks up to wait_seconds. It also gives turn-continuation rules for action_required and a mandatory verbatim prefix from meeting_mode_notice, which are critical behaviors no annotation conveys.

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?

Content is front-loaded with purpose, then alternative, then post-call handling in a logical order, and each sentence carries operational weight. However, the awkward line wrapping splits sentences mid-clause and the multi-clause 'If the result has...' block could be tightened into a compact bulleted set of rules.

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?

With an output schema present and annotations covering the safety profile, the description need not explain return values; instead it covers what an agent actually needs — auth requirement, version-conflict implication, alternative tool for interrupted rounds, and mandatory follow-up actions on the response. Nothing essential for a correct call 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 schema already documents project_id, patch fields, plan_content role-gating, and wait_seconds semantics. The description adds only indirect context (the patch becomes a new Context version), so the baseline 3 applies rather than a higher score for value added.

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 ('PM refines one completed Agent result; backend starts the next role') with a clear scope of one execution, and explicitly names the sibling it is not (resume_pending_dispatch) for interrupted rounds. An agent can distinguish it from commit_context_patch or propose_context_patch without opening schemas.

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 explicit conditions for use ('Continue this turn whenever workflow says so') and an explicit exclusion with the alternative to use instead ('If an earlier round was interrupted, use resume_pending_dispatch instead'). The trigger phrase 'whenever workflow says so' is somewhat circular, but the exclusion plus the post-call handling rules make the routing clear.

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