create_study

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true. The description adds genuinely new context: the study is immutable, it is free, a failed creation can be recovered by reusing request_key, and credentials stay in the local adapter. That is meaningful disclosure beyond the annotations, though it doesn't cover side effects or rate/limit behavior.

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?

Roughly five short sentences with no filler, and the core scoping facts (immutable, two image options, A vs B only) are front-loaded. The telegraphic fragments ('Free.') are efficient rather than padded, though the opening 'Validate' verb wastes a little clarity.

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 nested-object write tool with no output schema, the description covers the essentials: what is created, its immutability, the version-1 restriction to two image options, retry recovery, and what is returned (study ID and quote). The one gap is that the ambiguous 'Validate' framing is not reconciled with the tool's creation purpose.

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 50%; the request_key description in the schema is reinforced by 'Reuse request_key to recover a failed creation', which clarifies its idempotency role. The description also adds the 'HTTPS' constraint on image options, which is stricter than the schema's generic 'format: uri', so it contributes real meaning.

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 identifies the resource (an immutable preference comparison / A vs B image test) and its scope ('Version 1 supports A vs B image tests only'), which helps separate it from siblings like quote_study and purchase_study. However, it never uses an explicit creation verb — it opens with 'Validate', which is confusing for a tool named create_study and could be misread as a validation/checking operation rather than a write.

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 useful constraints (version 1 = A vs B image tests only, 'Free', reuse request_key on failure), which implies when the tool is applicable. But it never states when to use this instead of the sibling quote_study/purchase_study flow, nor any prerequisites or when-not conditions.

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