Visits

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

With no annotations provided, the description carries the full burden and discharges it exceptionally well: discloses sort order (newest first), default range, conditional metrics (7/30-day counts only when the range reaches today and is wide enough), always-on aggregates (most common day/hour), and date semantics (club-local, inclusive). This goes well beyond what the schema or structured fields reveal.

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 longer than average but every sentence earns its place — purpose is front-loaded, followed by defaults, usage guidance, conditional behavior, and date semantics in logical order. It is slightly dense as one block and the "count 1" hint is compressed, but there is virtually no waste.

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 output schema exists to explain return values and all three parameters have full schema descriptions, the description is complete for correct invocation: it covers defaults, conditional output behavior, date semantics, and query-framing strategy. Nothing an agent needs to call this tool correctly is missing.

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 coverage is 100% so the baseline is 3, but the description adds real meaning: it clarifies that dates are inclusive and club-local, provides a concrete mapping from a natural query to start/end values, and explains that count=1 retrieves the total efficiently. This is meaningful value beyond the schema's own field descriptions.

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?

Opens with a specific verb+resource statement — "Gym check-ins in a date range, newest first, with totals and habits" — that immediately distinguishes it from siblings (occupancy, forecast, nearby_clubs, auth_status are all clearly different domains). An agent can identify what this tool returns without opening the schema.

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?

Provides clear usage context: defaults to 90 days, advises preferring a bounded range over pulling all history, and gives a concrete natural-language-to-parameters example ("visits in August" → start/end). It stops short of explicit when-not-to-use guidance or alternative routing to siblings, though those tools are distinct enough that confusion is unlikely.

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