Update tenant

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds the important nuance that only passed fields mutate and that passing null clears a field, which is behavior an agent could not infer from the schema. It still omits permission/auth requirements and the meaning of the confirm gate, so it is not fully transparent.

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?

Three short, front-loaded sentences with no filler; the partial-update rule and the relocation payload are both actionable. The parenthetical cross-reference to add_tenant is slightly compressed but earns its place.

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?

No output schema, nested objects, and a free-form fields map, so the description carries real weight. It covers mutation semantics and the one non-obvious operation (moving properties), leaving only the confirm gate and return/response behavior unaddressed.

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 only 33%, so the description must compensate. It does explain 'fields' thoroughly (partial semantics, null clearing, and the propertyDetailsId move idiom), but says nothing about tenantId or confirm, and the free-form field vocabulary is only externalised by reference to add_tenant. Partial compensation warrants a baseline-plus score.

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 ('Change fields on a tenant') and extends scope to relocation ('Move a tenant to another property'). It points at sibling add_tenant for the field vocabulary, which helps an agent separate the two, though it does not fully state the relationship (add vs. mutate) outright.

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 clear usage semantics: partial update, null clears, and the exact payload for relocating a tenant to another property. It does not state when not to use it (e.g. vs. delete_tenant/add_tenant for other operations), so it stops short of full when/when-not guidance.

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