list_sites

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It explains the siteId semantics (Fabric ObjectId vs proxy-path UUID), the default full-page drain, manual pagination with nextToken, and the incomplete=true flag for capped drains. This goes well beyond a basic list operation.

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 summary sentence is front-loaded and precise, followed by compact, high-value notes on ID semantics and pagination. Every sentence earns its place without unnecessary filler.

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 that the tool has only one optional parameter and an output schema exists, the description covers all essential context: what is returned, the unusual ID meaning, how to reference sites, and pagination behavior. It is complete enough for an agent to call the tool correctly.

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?

Despite 0% schema description coverage, the description fully compensates by explaining how page_token works: default drains all pages, passing it fetches one page manually, and the response provides a nextToken cursor. This adds clear meaning beyond the raw string/null type in the schema.

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 states a specific action and scope: 'List all sites with device/client counts and ISP info.' This clearly identifies the resource and payload. However, it does not explicitly distinguish this tool from siblings like list_local_sites or list_all_sites_aggregated.

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 provides useful context about how to use the tool, such as passing site names and the page_token behavior. It implies that this tool is for listing all sites, but it does not explicitly state when to use it versus alternatives or when not to use it.

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