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

The annotations already flag this as a non-read-only write operation, and the description aligns by saying it 'creates or revises' a draft with no contradiction. It adds genuine context beyond the annotations: the draft is non-executing, records intent/metadata, does not start research, and MCP cannot read local file:// URLs. Minor gap: the 'revises' path could state whether the prior draft is replaced or superseded, and the confirmation-question round trip is only hinted at.

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 description is long but front-loaded: core purpose and applicability come first, followed by exclusions and technical constraints. Every sentence carries decision-relevant information for an agent. A small deduction for the file:// warning being duplicated verbatim in both the main description and the schema's source parameter description, which adds redundant length.

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 complex 12-parameter tool with nested objects and no output schema, the description covers the create and revise modes, module-grouping guidance, the one-question exception, and the asset-read limitation. It does not fully explain the confirmation-question flow (how answers feed back into a revised draft), though parameter descriptions partially compensate. Overall the guidance is strong enough for an agent to call the tool correctly in most scenarios.

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 100%, so all 12 parameters are already documented in detail, and the baseline is 3. The description adds some usage-level semantics—'Include every question known now in this ONE draft' for the request parameter, and the file:// constraint for source—but these largely echo schema text rather than adding meaning the schema lacks.

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 uses a specific verb and resource: 'Creates or revises a non-executing draft for a multi-question plan inside an existing Study.' It differentiates from siblings—especially run_study_questions—by explicitly stating the plan is executed 'later as one confirmed run' and that 'it does not start research.' An agent can distinguish this from every sibling without opening the 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?

The Applicability section explicitly defines when to use it ('the setup operation for every questionnaire, survey, battery, section, cohesive question set, or request containing two or more known questions—even when the user did not say “study”'), when not to ('A one-question draft is valid only for genuinely standalone research'), and implies the alternative path (executing later, which maps to run_study_questions). It also warns against the misuse pattern of splitting sets across drafts.

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