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

Annotations cover only readOnly/idempotent/destructive flags, but the description adds substantial behavior: the admin-only adminsql/sql/sqlparameters fields, that name/scope_id also write Stammdaten, that recipients always come from the formdef and never the POST, and that buttons/template_file/template_filename live inside the formdef JSON rather than being top-level params. These are exactly the non-obvious traits an agent needs and none are recoverable from annotations.

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?

Content is relevant and the core purpose is front-loaded, but it is a dense unbroken block that mixes field schema, permissions, buttons, Excel/PDF templating and placeholder syntax into one paragraph. It is appropriately sized for the tool's complexity yet poorly structured for scanning.

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, nested-object, no-output-schema tool, the description covers field structure, permissions, button types, PDF template wiring and placeholder syntax thoroughly. It stops short of describing the response or error behavior, which is a minor residual gap given no output schema is declared.

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% at the top level, so the baseline is 3, but the description goes well beyond it for the nested formdef object: per-field requirements (key regex, widget, label, optional required/options/source/validation), the full widget enum, and the reserved-key list. This meaningfully compensates for the fact that the nested structure cannot be fully expressed in the schema.

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 ('Formular-DEFINITION speichern') and immediately scopes it as 'der EINZIGE Schreibweg fuer formdef', which tells an agent how it relates to siblings like onto_formdef_create and onto_formdef_list_templates. The purpose is unambiguous even 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?

Gives concrete preconditions: required fields (version>=1, title, answer_type as existing object type, non-empty fields) and permission requirements (form_writer/admin + scope write access). It does not explicitly state when to prefer this over onto_formdef_create or show_formdef, so the alternative-routing guidance is implicit rather than explicit.

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