list_site_devices

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

With no annotations, the description carries full burden. It discloses the default full-drain behavior, manual pagination with offset/limit, surfaced totalCount, upstream filter passthrough, and the incomplete=true cap behavior. This goes well beyond a simple 'list' and prepares the agent for edge cases, though it doesn't mention potential errors or authentication requirements.

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?

Packed with essential detail in a compact block. Each sentence adds value; the parameter explanations are structured with colon-separated keys. Slightly dense but not bloated.

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?

Covers pagination, filtering, and partial-result signaling, which are the tricky parts of this tool. Output shape is left to the output schema, so no gap there. The only nuance not addressed is what a 'capped drain' cap actually is, and no mention of authentication or permissions, but for a list operation that's acceptable. A strong, self-sufficient description.

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 has zero property descriptions, so the description must compensate. It does: explains host formats (console name, ID, composite ID), site name or ID, offset/limit manual paging semantics, filter expression with concrete examples and the fact it is omitted when unset. Excellent param coverage.

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?

States a clear action and resource: 'List all adopted devices for a site via connector proxy.' It distinguishes itself from fleet-level lists by mentioning 'for a site' and 'via connector proxy,' though it doesn't explicitly contrast with sibling tools like list_devices or list_all_devices.

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 explicit guidance about when to choose this tool over siblings. It doesn't mention alternatives, exclusions, or prerequisites (e.g., 'use list_all_devices for fleet-wide'). The behavioral notes about paging are useful but don't address selection criteria.

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