Update a proposal

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

The description adds key behavioral detail beyond the annotations: it discloses in-place mutation, partial-update semantics ('Only the fields you pass change'), and the return value ('fields that changed and the file path'). Since all annotation hints are simply false, the description carries the burden well by explaining what the write operation does and returns.

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?

Three concise sentences with no filler. The core action is front-loaded, the partial-update behavior follows immediately, and the return value closes it out. Every sentence adds relevant information.

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 9-parameter tool with no output schema and no useful annotations, the description covers the most essential gaps: what is mutated, how much of the record changes, and what is returned. Minor gaps remain, such as not-found/error behavior and format expectations for fields like valid_until, but an agent has enough to invoke the update correctly.

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 low (11%), so the description must compensate; it does add important cross-cutting semantics by making clear that only passed fields are changed, which affects every parameter. The schema also gives a helpful reference description with an example and the free-tier implication. However, most parameters like valid_until, scope, and timeline still rely on names and types, with no format or value semantics provided.

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 uses a specific verb and resource: 'Rewrite an existing proposal in place from its reference.' It clearly distinguishes this from proposal_create by emphasizing 'existing' and 'in place,' so an agent can tell the two siblings apart. The 'Only the fields you pass change' clause further pins down the update-versus-create semantics.

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 description gives clear context for when to use the tool: updating an existing proposal identified by reference, with partial-field patching. It does not explicitly name alternatives or state when not to use it, but the existing-in-place framing makes the intended use obvious against proposal_create.

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