list_listings

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does a strong job: it reveals the default specialStatus[]=active filter, explains that availability filters behave exactly as Hostaway does, warns that amenities expect IDs rather than free-text names, constrains check-in/out hours to 0–23, and notes that denylisted fields are stripped from responses. Minor gaps include pagination and return shape, but the description is transparent about the tool's notable behaviors.

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 tightly written: four short sentences, each carrying distinct information. It is front-loaded with the main purpose, then covers default behavior, filtering semantics, and caveats without 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?

For a read-only listing tool with no output schema and no annotations, the description covers the main invocation details: default filters, optional parameters, value formats, and stripped fields. It falls slightly short of full completeness because it does not mention pagination or the overall response envelope, but the essential information needed to select and call the tool correctly is present.

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 67%, not at the high threshold, so the description meaningfully compensates. It explains that availabilityDateStart, availabilityDateEnd, and availabilityGuestNumber work together as Hostaway-style filters, and it clarifies the default active status relevant to includeArchived. However, the `city` parameter is left undocumented in both schema and description, which prevents a perfect score.

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 opens with a specific verb and resource: 'List Hostaway listings.' It immediately distinguishes this from sibling list tools (list_reservations, list_conversations, list_messages) because the resource is clearly listings, not another entity. Additional context about default active status and stripped fields further clarifies exactly what this tool returns.

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 makes the usage context clear: it lists Hostaway listings, defaults to active entries, and supports optional availability-based filtering. It does not explicitly state 'use this instead of get_listing' or 'do not use for reservations,' but the resource target is obvious from the first sentence and sibling tools.

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