create_question

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

Annotations mark the operation as non-readonly and non-idempotent, so mutation is expected. The description adds useful behavioral context: creating a question returns a JSON object with assigned id and order, clone behavior via from_id, default-empty text, the grid-only subtype requirement, and the Nextcloud-specific datetime rejection. This goes well beyond what the annotations and schema alone communicate.

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 well-organized into Args and Returns sections. Every sentence adds substantive information: parameter semantics, constraints, edge cases, and follow-up actions. There is no fluff or repetition despite the length, and the most important usage caveat (datetime rejection) is clearly highlighted.

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 creation tool with a non-trivial parameter set and no schema descriptions, the description is complete. It covers all parameters, required context for question types, the clone option, return behavior, and related downstream tooling (create_options). The output schema exists, so the description wisely summarizes the result without over-explaining the response structure.

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 0%, so the description carries the full burden—and it delivers. It explains every parameter: form_id as numeric, question_type with all valid values and human-readable meanings, the datetime exception, text default and later update path, subtype scoped to grid with its valid cell types, and from_id as an optional clone source. This is far richer than the bare 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?

Description opens with a specific verb and resource: 'Add a question to a form.' It goes beyond a simple label by clarifying the return value ('JSON of the new question'), the clone behavior via from_id, and explicitly distinguishes the tool from create_options by directing choice-type setup to that sibling.

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 description provides clear contextual guidance: it notes that text defaults to empty and can be set later via update_question, tells users to use create_options for choice types, and warns that datetime is rejected in favor of separate date/time questions. It lacks an explicit general 'use this instead of X' statement for update_question/reorder_questions, but the key alternatives are named.

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