get_model_key

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

Annotations already declare readOnlyHint=true, yet the description adds real value: the index lifecycle states, the fact that the linked job projection strips free-text messages/data, and the no-auto-reactivation constraint. These are behavioral facts not present in the structured fields.

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?

Two dense sentences with no filler, and the core action (read the definition and index state) is front-loaded before the caveats.

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 read-only tool with no output schema, the description partially covers what comes back (index state, filtered job projection) but leaves the required identity parameters and their aliasing unexplained, which matters given the anyOf/alias schema.

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 carry the load, but it never names logical_name, schema_name, or include_job. It only obliquely gestures at the job-projection behavior ('excludes free-text messages/data') without tying it to the includeJob parameter.

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: 'Read one native alternate-key definition and Pending/InProgress/Active/Failed index state.' That is clearly distinguishable from create_model_key and reactivate_model_key, though it never names those siblings explicitly.

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?

Usage is implied rather than stated: the note that a key is usable only after its native index is Active and that there is 'no automatic reactivation' hints that reactivate_model_key is the alternative, but the description never says when to call this versus that tool.

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