create_model_key

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

Annotations already flag destructiveHint=true and non-idempotency, but the description adds substantial context beyond them: a default preview/dry-run mode, asynchronous server-side validation of index size and existing uniqueness, and the state caveat that 'Pending/unknown is not Active'. It also draws explicit boundaries around side effects ('No record scan, index reactivation, save replay or implicit publication'), which is exactly what an agent needs before committing a destructive mutation.

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 core action and column limit, and the following sentences are dense with distinct facts rather than repetition. The telegraphic fragment 'Pending/unknown is not Active' and the clipped negation list at the end cost some readability but still carry information.

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 destructive, non-idempotent create tool with no output schema and only 33% schema coverage, the description does solid work on side-effect boundaries, async validation and preview semantics. The main gap is that it never clarifies the effectively-required parameter set (all five logical fields, in either casing) or what the preview payload actually contains.

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 only 33%, so the description must compensate and it only partly does: '1–16 columns' maps to key_attributes' maxItems, 'solution/publisher' maps to solution_unique_name, and 'type, field-security and duplicate checks' gesture at validation behavior. It says nothing about the five logical parameters (logical_name, schema_name, display_name, key_attributes, solution_unique_name), their dual snake_case/camelCase aliasing, or which are effectively required.

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 and resource: 'Create a native alternate-key definition on 1–16 columns', which clearly separates it from create_model_column, create_model_relationship and create_model_table. The clause 'No ... index reactivation' implicitly distinguishes it from reactivate_model_key, but no sibling is named explicitly, so it stops short of the top score.

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?

'Default preview' and 'No ... save replay or implicit publication' imply the intended workflow (dry-run first, publish separately), which is useful context. However, it never states when to prefer this tool over reactivate_model_key or get_model_key, nor does it spell out prerequisites such as an existing unmanaged solution, so usage is only implied.

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