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

Annotations have readOnlyHint=true and openWorldHint=false, so the tool is read-only. The description adds the media_quota cap semantics (cap null means unlimited), which is beyond annotations and gives important behavioral context for a trip capacity check. It doesn't contradict annotations. It also explains the media_quota field directly in the description, which is beyond the schema (schema only says 'must not be empty' for trip_id). This adds value for the agent, but it could be more explicit about what happens when a trip is not found (error behavior).

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 two sentences, which is appropriately concise. It front-loads the purpose ('Where a trip stands') and then gives usage context. The media_quota detail is relevant but perhaps could be trimmed, but it's not excessive. Every sentence serves a purpose: the first describes the tool's output, the second gives usage guidance. It's well-structured.

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?

Given the tool has one parameter (trip_id) and no output schema, the description covers the main relevant aspects: what the tool reports (progress, cover, media quota). The only missing piece is error behavior (e.g., invalid trip_id), but since the schema enforces non-empty, and the read-only nature is in annotations, this is sufficient for the agent to call it correctly. The description is complete for a simple check tool.

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 100%, so the schema documents trip_id. The description does not elaborate on trip_id format, but it's a simple ID with a must-not-be-empty constraint. The description adds value by clarifying the media_quota field (a parameter-like construct) even though it's not in the input schema. Since the coverage is high, a baseline 3 applies, but the description adds context about the quota semantics, which nudges it to a 4.

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?

Description clearly states it checks trip progress: how much is written, what's missing, whether cover exists. It also mentions the media_quota field, which is a specific aspect. This is a specific verb+resource (check trip state) and the main purpose is unambiguous. The title is an adequate shorthand already, but the description adds specific details like cover and media_quota.

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?

Explicitly says 'Call this when picking a trip back up' and mentions to check media_quota before a big batch. This gives clear when-to-use guidance. It also differentiates from the start, though it doesn't explicitly say 'don't use for X', but the context of picking up a trip is specific enough. Words like 'where a trip stands' and 'before a big batch' give actionable scenarios.

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