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

Annotations declare it is a non-read, non-destructive write, and the description adds substantial context beyond that: the job transitions to 'bidding', nothing is transmitted to the client, it deliberately skips confirmation because it reaches no one, and it requires a Cotlet API key with access to the app. That is exactly the behavioral framing an agent needs for a state-mutating tool.

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?

Front-loaded with the core action, but it repeats itself: 'The job moves to bidding' appears twice and the 'nothing is sent' point is made twice in slightly different words. Two sentences do the work of four, so the redundancy costs it points.

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 two-parameter write tool with annotations covering the safety profile, the description supplies purpose, side effects, auth requirement, and the sibling alternative. The only gap is it says nothing about the outcome/return shape, though with no output schema this is a minor omission.

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 coverage is 100%, so both parameters (job_id, line_items) are already documented, including where job_id comes from and the line-item shape. The description only loosely restates the line-items concept ('contract lines') and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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 ('Save the draft proposal (bid) of a job') plus the resulting state change ('The job moves to bidding'). It also names the sibling it is not ('send_proposal_for_signature does that'), so an agent can route between them without opening either schema.

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?

Clearly frames when to use this tool (persist a draft, send nothing) and names the alternative that sends to the client. It stops short of explicit when-not conditions or prerequisites for the send path, but the context for choosing is unambiguous.

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