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

Beyond the annotations it discloses the significant behaviors: a plan below the confidence bar is queued for review, the response reports that fact, the queue is inspectable via list_rosetta_review, and calls fail with 403 until the workspace is claimed by a person (sandbox self-registration keys are refused). Auth requirements and the refusal mode are exactly the context annotations cannot convey.

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?

Front-loaded with the result shape, then the input contract, then the review-queue caveat, then the credential/workspace gates. It is dense but every sentence carries distinct information; the auth caveat is slightly repetitive ('Needs a claimed ... Needs a claimed ...') but not padded.

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?

There is no output schema, yet the description spells out the return payload (per-field mapping, transform, confidence, provenance, plus plan-level confidence and tier) and the conditional queue-for-review path. Combined with the auth and failure-mode notes, an agent has enough to call this correctly and interpret the answer.

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% and the nested field schema is fully annotated, so the bar is a baseline 3. The description does add a usable distinction the schema states only in passing: canonical_schema accepts either an id pulled from list_canonical_schemas or a whole inline schema, and source_schema is always id+fields of paths and types.

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?

Opens with a concrete verb+resource (ask Rosetta how a source schema maps onto a canonical one) and even enumerates the per-field output (target field, transform, confidence, provenance, plan confidence, tier). It does not differentiate itself from nearby Rosetta verbs such as translate_with_rosetta, normalize_with_rosetta or ingest_with_rosetta, so an agent must infer the boundary.

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 prerequisites (claimed Last Price credential, claimed workspace, 403 for sandbox keys) and a downstream hand-off (list_rosetta_review shows the queue), which is real usage context. What is missing is the when-to-use-this-vs-alternative statement: nothing says to call this instead of translate_with_rosetta or ingest_with_rosetta, or when a mapping plan is not warranted.

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