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

Goes well beyond annotations (readOnly=false, destructive=false, idempotent=false) with high-value operational detail: UUID/RFC 4122 requirement, only 'welcome'/'submit' as non-UUID ids, the finish ('thank you') widget as a separate widget, flags vs. list items for special answers, and even the return shape ('saved: количество виджетов и разбивка по типам') despite no output schema. It tells the agent to verify the saved composition before confirming success — a real behavioral contract.

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-loads the one-line purpose, then layers the important warnings. It is dense but every clause carries a constraint (UUID format, special screens, flags, verification) relevant to a tool with nested objects. Slightly long, but no filler sentences.

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 3-parameter, write-mode tool with deeply nested entities and no output schema, the description covers the failure-prone essentials: id format, mandatory ordering, the separate finish widget, special-option flags, and result verification. Nothing critical is left to inference.

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%, so the baseline is 3. The description nonetheless adds semantics beyond the schema: the ordering rule (welcome first, submit last, unique UUIDs between), the entities-keyed-by-id relationship, and the finish-widget requirement are surfaced as narrative guidance an agent must act on.

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+resource: 'Сохраняет структуру виджетов опроса (ids + entities)' — saving the quiz widget structure. It is clearly distinguishable from read-side siblings like get_quiz_structure and from update_quiz_settings/texts/logic. It stops short of explicitly naming a sibling, so it lands at 4 rather than 5.

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?

Provides one explicit precondition — 'Перед вызовом прочитайте текущую структуру через ресурс quiz://{id}/structure' — which is genuine workflow guidance. However, it never states when to choose this tool over update_quiz_texts, update_quiz_logic, or update_quiz_settings, so the alternative-selection guidance is missing.

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