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

Goes well beyond the single readOnlyHint=false annotation by disclosing side effects: cargo from the current ship moves to station storage, modules and crew stay with their ships, wreck tow is released without moving the wreck, and the call auto-docks at the POI's station. The carrier-swap path adds the conditions (both out of transit/battle, no aggression timer, no tow) and the bay-capacity constraint.

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?

The opening clause and the parenthetical restate the same fact ('switch to a different ship stored at this station' then 'Swap your active ship with one stored at this station'), and the whole thing is delivered as one undifferentiated block mixing the station path and the carrier path. Most sentences carry real information (error codes, prerequisites), but the duplication and lack of structure cost it.

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 mutation tool with no output schema and only a readOnlyHint annotation, the description supplies everything an agent needs: prerequisites, both execution paths, state transitions of cargo/modules/crew, and the failure codes returned. Nothing material is left to inference.

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 already 100%, so the baseline is 3, but the description adds operational meaning: ship_id may mean a ship stored at your station or your ship sitting in a faction-mate's bay, and that interpretation changes the no-shipyard/one-step behavior. It also shows ship_id being reused as the module and storage item identifier for the preparatory calls.

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 plus both operating modes: switching to a ship stored at the station, and swapping in space with a ship in a faction-mate's carrier bay. It is clearly distinguishable from siblings such as refit_ship, list_ships, and uninstall_mod, which are named as related but separate actions.

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?

Explicit preconditions and routing are given: requires shipyard service for the station path but none for the carrier swap; use uninstall_mod with ship_id first to free fitted CPU/power; use storage action=withdraw to unload a towed ship before switching. Refusal conditions (already_towing, bay_full, passengers_aboard) tell the agent exactly when the call will fail.

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