Update a Rootr form (fields/targetDatabaseId/config)

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

Annotations only indicate no read-only or destructive hint, but the description adds critical behavioral details: fields array replacement is complete (omitted fields dropped), database unlinking via null, and the importance of preserving field ids for response attribution. This goes well beyond the 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?

The description is somewhat lengthy but well-structured with important points front-loaded. Each sentence provides useful information, though minor redundancy could be trimmed. Still effectively concise for the complexity.

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?

Given the tool's complexity (nested fields, merge-patch semantics, database linking), the description covers all necessary aspects: field replacement behavior, id stability, type definitions, options requirement, and unlinking. No output schema, but the description adequately explains the mutation effects.

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?

With 100% schema coverage, the description still adds significant value: explains that the fields array is replaced entirely, clarifies the role of the id field for stability, describes field types and the options structure for select types, and explains the effect of targetDatabaseId being null.

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 clearly states the tool performs a merge-patch update on a Rootr form, specifying the verb (merge-patch), resource (form), and key behaviors like replacing the fields array or unlinking a database. It distinguishes from sibling tools like rootr_read_form by advising to read first.

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 explicit when-to-use guidance: call rootr_read_form first to preserve field ids, and warns about the consequences of dropping fields. It also explains how to unlink a mirrored database (targetDatabaseId: null), giving clear usage context.

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