list_hosts

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

With no annotations provided, the description takes on the full burden and delivers strong detail: host records are returned verbatim including GPS coordinates, all pages are drained by default, page_token returns a single page with a nextToken cursor, and capped drains signal incomplete=true rather than truncating silently. This is far more than a generic list statement.

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 three compact sentences, front-loading the tool's purpose before detailing pagination behavior. Every sentence earns its place: purpose, return fidelity, pagination modes, and incomplete result handling.

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 an optional single cursor parameter with an output schema, the description covers the key behaviors needed to invoke the tool correctly: default full draining, manual page fetching, continuation cursors, and incomplete results. The only minor gap is that 'capped drain' is mentioned but not defined; the trigger or threshold for the cap is not specified.

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 schema provides only type/default for page_token with no property description, so the description must compensate. It does by explaining that passing page_token fetches a single page manually and that the response carries a nextToken cursor. It could clarify where the token comes from or its exact format, but the added semantics are meaningful.

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 all UniFi consoles (hosts)', and enumerates the returned fields (firmware, WAN IP, status). This clearly distinguishes the tool from singular operations like get_host and makes its scope immediately obvious.

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 clearly explains the default behavior of draining all pages and explicitly states when to pass page_token for manual single-page fetching. It does not name sibling alternatives such as get_host for single-host lookups, so it lacks explicit when-not/alternative guidance.

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