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

Annotations (idempotent, non-destructive, closed-world) are complemented by non-obvious behavior: optimistic concurrency (reads current version and refuses an interleaved change), metadata-only with no rebuild, the one-dataset-per-name uniqueness rule, the metadata-generation rule for nonblank descriptions, and the explanation that public_projection_synced does not mean the dataset is public. No annotation is contradicted.

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?

It is information-dense but poorly front-loaded: the core 'what it does' sentence appears mid-paragraph after metadata-generation detail. It also re-lists all 18 category enum values that the schema already provides, and embeds a long example object, adding length that duplicates structured data. Most sentences carry real semantics, so this is adequate-but-bloated rather than wasteful throughout.

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?

With no output schema, the description enumerates the return shape ({dataset_id, name, description, category_id, changes, version, visibility, public_projection_synced, dashboard_url}) and interprets the ambiguous fields (visibility, public_projection_synced). Combined with the mutation, concurrency, and uniqueness behavior disclosed, an agent has everything needed to invoke and interpret this 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?

Schema description coverage is 0%, so the description must compensate, and it does: name is explained as a sticky title versus the create_dataset working title, description is explained as the search snippet / answer-engine summary with opening-paragraph rules, category_id is explained as purpose-based filing with the set-once-before-register_recipe rule, sync_only is explained as the public-page-only retry, and expected_version is explained as the precondition.

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 concrete operation and resource: 'Changes a dataset's display name, its description, or both', plus setting category_id. It distinguishes itself from siblings by naming set_dataset_visibility for visibility changes and register_recipe for sequencing. An agent can identify what this tool does and what it does not do.

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?

It gives explicit conditional guidance: send name with the description to keep a title, set category once the subject is clear and before register_recipe, and use set_dataset_visibility (not this tool) to change visibility, only when the person asks. It also gives a concrete retry path: if public_projection_synced is false, retry with {dataset_id, sync_only: true}.

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