plenticore_update_settings

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

Goes well beyond the destructiveHint/non-idempotent annotations by disclosing that multi-setting writes are non-atomic, there is no automatic rollback, and a connection error after submission can leave a change applied. The 'read back before retrying' instruction is precisely the behavioral context an agent needs to avoid duplicate writes.

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?

Four short sentences, front-loaded with the dry-run default, with no filler. A couple of phrases ('Uses actual owner-accessible IDs, types and min/max', 'No installer login') are terse to the point of being slightly opaque without surrounding context.

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?

Covers the full risk profile for a destructive, non-atomic mutation: prerequisite reads, failure/recovery semantics, and the string typing of values, while the output schema handles return shape and annotations cover open-world behavior. An agent can call this safely without further reference.

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 0% schema description coverage the description carries the burden, and it does: dry_run's preview-vs-write meaning is spelled out, 'Values are strings' documents the nested map's value type, and 'Uses actual owner-accessible IDs' constrains moduleid. It never explains what the min/max or type constraints mean for a rejected value, so it is strong but not complete.

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 (update settings) plus the crucial scope qualifier that the default is a preview and only dry_run=false writes. That distinguishes it cleanly from the read_settings/list_settings siblings in the same family, and naming the read-back behavior makes the tool's role unmistakable.

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 an explicit prerequisite: 'Read list_settings and the current values first', which is the key sequencing rule for a settings mutation. It does not spell out when to prefer this over a read-only sibling or when a preview is mandatory, so it stops short of fully explicit 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.