Update custom_sensor

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

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds one genuinely behavioral fact beyond that – unspecified fields retain their values (true partial update) – but says nothing about how a field is cleared, whether unknown keys are rejected, or what errors occur on a bad id.

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?

A single compact sentence with the resource front-loaded and the merge behavior trailing as supporting detail – no filler anywhere. It is arguably too terse for the free-form `changes` bag, but nothing written is wasted.

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?

This is a mutation over a nested, entirely free-form `changes` object with no output schema. The description never says which fields can be changed, how to unset a value, or what is returned, so an agent must call list_custom_sensors or guess to learn the valid key set. Annotations only supply the read-only/idempotency profile.

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% and both parameters are described ("custom_sensor id or exact name", "Fields to change"), so the baseline is 3 under the high-coverage rule. The description's patch phrasing clarifies that `changes` is a partial bag, but neither schema nor description enumerates which keys are valid inside an object typed as additionalProperties: {}.

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 names a specific verb ("Change fields") and resource ("existing custom sensor"), so an agent can distinguish this mutation from create_custom_sensor and delete_custom_sensor. It does not, however, contrast itself with sibling update_* tools, so the differentiation stop-point is generic rather than explicit.

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?

Usage is only implied: "existing custom sensor" tells the agent the target must already exist, and "fields not given keep their values" implies patch semantics rather than replacement. There is no explicit statement of when to use this instead of create/delete, and no prerequisites or failure conditions are named.

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