list_datasets

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds useful non-redundant details: it is 'not separately rate-limited', lists only the active API key's organization, and enumerates the exact fields returned in the datasets array. This goes beyond the annotations without contradicting them.

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 longer than strictly necessary but every sentence earns its place: purpose, workflow guidance, safety/scope, return shape, and sibling routing. It is front-loaded with the core purpose and ends with the alternative. A bit dense but well organized.

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 tool with no output schema, the description enumerates all return fields and pagination metadata. It covers scope (organization), safety (non-destructive, not rate-limited), usage patterns, and sibling distinction. An agent has everything needed to call it correctly and interpret results.

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 100%, so parameters are already documented. The description adds value by suggesting a combination (search plus compact mode for low-token discovery) and clarifying that limit defaults to 'all visible datasets, max 200 when set', which is not in the schema. It also lists the returned fields, aiding interpretation. Slight deduction because the description doesn't elaborate on every parameter, but it complements the schema well.

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 specific verb ('List') and resource ('registered datasets') and adds the key output ('model tier'). It also distinguishes itself from sibling list_data by describing what it covers (semantically trained datasets vs connection-backed). Clear and specific.

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?

Explicitly states when to use this tool vs list_data: 'browse semantically trained datasets with status and model_tier; use list_data for connection-backed datasets from connect_data or register_source.' Also gives a workflow hint: 'Use search plus compact mode for low-token discovery, then poll status or use the primary data tools once you choose a dataset.' No ambiguity about context.

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