Record Proposal Decision

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

Annotations only declare the generic profile (readOnly=false, idempotent=false, destructive=false, openWorld=false). The description goes beyond them by disclosing the post-condition state transition to pending_review, the side effect of writing fit.chosen_base, and the precise 409 failure condition when the job has no application — all behavior an agent could not derive from the annotations.

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?

Purpose is correctly front-loaded in the first sentence. The second sentence, however, is a run-on with nested clauses and parentheticals about linkage and the 409 case, which is information-dense but harder to parse than it needs to be.

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, no annotation detail, and 0% parameter description coverage, the description supplies the state machine and the application-linking/error behavior but omits any indication of what `fit` must contain. The agent still cannot construct a valid required payload from what is given.

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% and the required `fit` object is an open-ended additionalProperties object with no semantics given anywhere, so the core payload remains opaque. The description does explain application_id thoroughly (omitted → link job's application on fit.chosen_base, else the job's single application), which is real added value, but covers only one of three parameters.

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 states a specific verb and resource (record user decision / proposal) and anchors it to a named state machine position ('needs_decision state') with its resulting state ('pending_review'). It is clearly a decision-recording mutation, distinguishable from read-only siblings like get_proposal, though it never names the closest alternatives (request_decision, resume_proposal) to draw the boundary 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?

It gives a concrete precondition for use: the proposal must be in the needs_decision state. That is real when-to-use guidance, but there are no exclusions or comparisons against request_decision/resume_proposal, so the agent must infer which sibling to call when the proposal is not in that state.

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