get_cargo_hold

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

With no annotations, the description carries the full behavioral burden. It discloses the data sources (Cargo.json + Loadout) and implies a read-only snapshot via 'Current', but says nothing about behavior when the journal directory is absent or unset, whether results are cached, or whether stale data is returned.

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?

One compact line with the most important content (manifest, capacity, free space) front-loaded and zero filler. The telegraphic '+' style is terse but readable; a leading verb would make it slightly clearer without adding length.

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?

An output schema exists, so return values need no explanation, and the tool is low-complexity with one optional parameter. Still, the undocumented parameter, absent usage guidance, and missing annotations leave gaps an agent would have to fill by trial.

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?

The single parameter journal_dir has 0% schema description coverage and the description never mentions it, so its meaning, default behavior, and expected path format are entirely undocumented. The schema does not compensate, leaving the agent without guidance on this input.

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 enumerates the payload (cargo manifest, rack capacity, free space) and names the source files, so an agent can infer this reads the commander's current cargo hold. However, it is a noun fragment with no verb and never distinguishes itself from the closely related sibling get_ship_loadout, which also draws on Loadout data.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as build_cargo_shopping_list or get_ship_loadout, which overlap in subject matter. The agent must guess whether this is the right tool for a cargo-capacity question.

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