vehicle_status

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-redundant behavior: it requests single messages without altering stream rates, it reports `unavailable` for anything not received, and it flags STATUSTEXT as untrusted vehicle data. The trust warning in particular is safety-relevant context the structured fields cannot convey.

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 long field enumeration leads, followed by the read-only/non-disruptive guarantee and the `unavailable` and trust caveats, so no sentence is buried. The list is dense but every item corresponds to real returned data; a slightly tighter grouping would make it easier to scan.

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 an output schema present, the description need not restate return structure, and it still explains the one ambiguous output field (`unavailable`) plus the semantics of the pre-arm check boolean. For a zero-parameter read tool, an agent has everything needed to call it and interpret the result correctly.

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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The only input-adjacent note, that nothing is configurable and single messages are requested, is consistent with an empty schema.

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 names a specific resource (a status snapshot of a vehicle) and enumerates the exact fields captured: arming state, flight mode, sensor health, pre-arm check enabled/passing, battery, GPS fix, and STATUSTEXT. This is far more specific than the bare name, and the pre-arm 'false = switched off on the vehicle' clarification prevents a serious misreading.

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 tells the agent this is a read-only, non-rate-changing single-message fetch, which implies a diagnostic/checking use, but it never says when to choose it over siblings like vehicle_info or diagnose. No exclusions or alternatives are named, so the agent must infer the boundary from sibling names alone.

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