track_history

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

No annotations are present, so the description carries the behavioral burden. It discloses the ~24-hour sliding window, downsampled paths, and the interpretation of long straight jumps as volunteer-coverage gaps. This is meaningful behavioral context beyond the raw schema, though it does not address auth, rate limits, or exact output formatting.

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 description is front-loaded with the core purpose, then gives example user questions, then closes with the essential caveats. Each sentence earns its place and nothing feels redundant or padded.

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?

With no output schema and no annotations, the description usefully explains return fields, leg structure, time window, and coverage gaps. However, it leaves the input-selection contract unresolved: three optional identifiers with no guidance about which to use, and it does not explicitly route the agent to a sibling when an archive is needed.

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 description does not explain how hex_id, callsign, or registration select the aircraft, whether at least one is required, or whether they can be combined. The property titles are somewhat self-explanatory, but the description adds no parameter semantics and leaves the all-optional behavior unclear.

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 says the tool 'Returns each airborne leg' with when it started and ended, distance, altitude, and a path, and explicitly frames it as answering 'where has this plane been today.' This is a specific verb plus resource and is clearly distinguishable from broader siblings like track_flight or sighting_history.

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 clear usage context: use this for a single aircraft's roughly-last-day leg history and route. It also draws an exclusion boundary by saying 'Not a flight archive' and explains that long straight jumps are receiver coverage gaps rather than real flight paths. It does not name the alternative sibling to use for archives, so it is slightly less explicit than it could be.

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