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

The annotations only say destructiveHint=true generically; the description earns its keep by spelling out exactly what is destroyed ('replaces the one with that `key` outright', 'a field left out is gone from the model') and what is refused ('a collection an artifact declared is refused with `conflict`', 'Refusals name field, rule and fix'). That is the precise consequence information an agent needs before invoking a destructive, idempotent tool.

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 hook is front-loaded and every sentence carries information — no filler. It is however a single dense run-on paragraph with telegraphic phrasing ('compare (alone)', 'name, display field and every field') that takes a re-read to parse mode boundaries.

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 seven optional params, nested `define` objects, no output schema and no readOnly hint, the description does the heavy lifting: it covers all three modes, the destructive replacement contract, and the shape of refusal results. What it omits is what a plain read actually returns at the top level (e.g. pagination or listing limits), which matters for a no-arg default call.

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 already 86%, so the baseline is 3, but the description adds real semantics for the two highest-risk params: `compare` gets its 2–10 arity and conflict-reporting behavior, and `define` gets replace-vs-omit field semantics plus the refusal case. `tags`, `since`, `series`, `artifact` and `workspace` are left to the schema entirely.

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?

Opening line 'The data catalog, without rows' names the resource precisely, then enumerates three modes (read datasets/collections, compare artifacts, define a collection) with concrete outputs for each. It also explicitly routes row data away: 'Rows an artifact collected are super_data', which separates it from super_data and super_data_query without opening either schema.

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?

Mode gating is stated clearly — 'Read (the default)', '`compare` (alone): two to ten artifacts'', '`define` creates a content collection, or replaces...' — so an agent knows the exclusivity constraints. The one gap is that it never states when to prefer this catalog over super_data_query/super_data_write beyond the closing routing sentence about rows.

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