get_booking_history

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

Annotations already cover read-only, idempotent, and non-destructive behavior, yet the description adds substantive context beyond them: history is partial and not an exhaustive interval, reservation/late-cancellation labels do not prove attendance, and source names must be treated as untrusted content (a prompt-injection warning). The gym-zone caveat ("may be assumed") also discloses an implicit-context dependency. Some phrasings, such as "source flags remain explicit," are too terse to be fully actionable.

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 purpose is front-loaded in the first sentence and each subsequent sentence adds a distinct caveat rather than repeating itself. It is dense but not padded. Minor cost: several compressed jargon phrases ("source flags remain explicit") force the reader to decode intent.

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, return values need no explanation, and the description does well on trust and data-quality caveats. What is missing is the relationship to sibling tools and an explanation of how the gym context is established given the empty input schema. For a zero-argument read in a crowded booking toolset, those gaps matter.

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, which normally sets a baseline of 4. However, the description repeatedly references a "verified gym" and a "reported gym zone" without explaining where that input comes from when no parameters exist, leaving an unresolved question about how the call is scoped. That ambiguity in an otherwise parameterless tool pulls the score down.

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 opening sentence names a specific verb and resource ("Read the account holder's available historical booking view") and adds a scope detail ("at a verified gym, newest first"). It is clearly distinct from get_upcoming_bookings by the word "historical," though the sibling is never named. The phrasing "available historical booking view" is slightly abstract — it does not say whether it returns bookings, classes booked, or attendance records.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite a large sibling set (get_upcoming_bookings, get_personal_activity). The notes about limited history and non-exhaustive intervals are coverage caveats, not routing guidance. An agent must infer from the word "historical" alone when to prefer this over the other booking tools.

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