dashbrr_save_settings

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

Beyond the annotations (destructiveHint=true), the description discloses that api_key is write-only and can be omitted to preserve the existing key during updates. It also clarifies that access_url is optional. This adds meaningful behavioral context about update semantics.

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 tight sentences. Front-loaded with the core action, followed by parameter clarifications. No redundant phrases or filler. The structure is logical and every sentence adds value.

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?

The description covers the main behavior, key parameter nuances, and safety considerations. An output schema is present, so return value details are not required. It is missing only a note about whether the operation overwrites the entire config, but 'create or update' implies that. Overall, sufficient for an agent to use effectively.

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 compensates for three of five parameters: instance (type-prefixed), api_key (write-only, omit to keep), and access_url (optional). However, display_name and url are left undefined, leaving the required fields partially unexplained.

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 states 'Create or update a service configuration on the dashbrr instance', a specific verb+resource pairing. This clearly distinguishes it from sibling tools like dashbrr_get_settings or dashbrr_delete_settings, and the scope is immediately evident.

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention that creation/update differs from deletion or that it should be used in conjunction with get_settings. The parameter examples provide some context, but there are no usage criteria or exclusions.

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