who_is_staying

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

With no annotations, the description carries the full burden and does well by disclosing the exact stay date condition, the default behavior, and the internal data window (~last year of changed bookings). It does not mention auth, rate limits, or pagination, but for a non-mutating query tool these are less critical.

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?

Three sentences, each earning its place: purpose, returned row structure, and default/implementation note. Front-loaded with the main verb and resource, and no wasted words.

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?

The description is sufficiently complete for a simple read-only tool with one optional parameter. It defines the row semantics and the internal data limitation, although it does not address edge cases like bookings older than the ~year window or output ordering. The presence of an output schema (not shown) likely covers return details.

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 only parameter, on_date, has no schema description, but the tool description compensates by explaining its meaning ('Defaults to today') and how it fits in the active-stay predicate. It doesn't specify the expected date format, but the parameter is simple and optional.

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 uses a specific verb ('Show') and clearly identifies the resource ('who is currently staying in each property'). It differentiates from sibling tools like list_bookings by focusing on active/in-house guests and explicitly defines the active stay condition (arrival <= on_date < departure), making the purpose unmistakable.

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?

The description gives clear context: it defaults to today and explains the date filtering logic, implying when the tool is appropriate (current occupancy). However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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