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

Annotations only declare a safe read, but the description goes far beyond: the server stores SettingsJson verbatim, never defaults and never validates keys, a guessed blob returns HTTP 200 and only fails client-side, and the value must never be null/empty even for a separator. This is exactly the failure-mode context an agent needs.

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 purpose and the imperative call-before warning, and every clause carries real information. However, the long em-dash-chained sentences pack multiple ideas together, slightly taxing readability.

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?

There is no output schema, so the description must describe returns — and it does, covering base settings, conventions/traps, type lists, and a single type's full card with example. For a zero-required-param lookup tool with high complexity, nothing needed to invoke it correctly is missing.

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%, but the description adds semantics the schema cannot express: omitting all params yields shared base settings/conventions/traps, 'category'/'search' list types, and 'itemType' returns a full settings card with a ready-to-send example plus bindable system contact attributes.

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 ('Quiz/form item types and the shape of their SettingsJson') and frames the exact artifact returned. It is clearly distinguishable from sibling schema lookups like get_fields_schema or get_operation_schema by scoping to form-item SettingsJson.

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?

Explicitly commands 'CALL THIS BEFORE creating or updating ANY form item' and gives the consequence of skipping it. It also names the three invocation modes (no args, category/search, itemType), so the agent knows which call shape to use for which need.

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