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

With destructiveHint=false but a write operation, the description carries rich context beyond the annotations: which facts trigger repricing, that repricing takes a minute or two, that the reply signals 'repricing', and that value_history_stale on a related list flips false once values post. It also states plainly which fields never affect value and that exit fields are inert for in-portfolio aircraft. This is exactly the operational transparency the annotations do not supply.

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 and scoping before the repricing detail. It is long (18 params justify some length), but the repricing/timing point is made twice ('a minute or two' recurs), which is mild redundancy against an otherwise dense, informative block.

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 high-complexity 18-parameter mutation tool with an output schema present, the description covers both operating modes, the repricing side effect and its latency, the reply flags, and how to verify completion via list_portfolio_archived_aircraft. Nothing an agent needs to invoke and interpret the call correctly is missing, and return-value detail is rightly left to the output schema.

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 per-field syntax is already documented and a 3 would be the floor. The description adds a semantic grouping the schema lacks: it enumerates the value-driving fields (tail, year, hours, engine times, condition, location, acquisition date, exit date shift) versus the values-neutral ones (entry price, asking price, notes, exit facts), which is decision-relevant for how a caller batches edits.

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 ('Correct the facts on a portfolio aircraft', 'Change what is on file about one aircraft') and explicitly bounds the scope: no make/model changes and no add/archive/restore/delete. It also distinguishes the two operating modes (still in portfolio vs. made its exit), so an agent can tell it apart from siblings like list_portfolio_aircraft or get_portfolio_aircraft.

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 clear prerequisites ('Send only what changes', line_id sourced from list_portfolio_aircraft or list_portfolio_archived_aircraft) and a procedural rule ('Confirm the change with the user before calling'). It notes the exit-fact fields apply only to an aircraft that has left, which prevents misuse. It does not name a competing update tool or state when not to use this one, so it stops short of a full when/when-not statement.

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