update_ui_settings

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. 'Show/hide UI components' implies a mutation, but it does not mention whether the change is reversible, what side effects occur, whether permissions are required, or what the response might look like. This is a significant gap for a mutation tool.

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 a single sentence with no fluff, directly stating the core action. It is appropriately concise and front-loaded, though it lacks any structured detail that could help usage.

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 tool has no output schema, no annotations, an open input schema, and a vague description. It fails to explain what UI components are affected, how to specify them, what the expected return is, or any prerequisites. For a tool with an open schema, this level of incompleteness is severely inadequate.

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?

The input schema is open (additionalProperties: true) with zero documented parameters, so the description must compensate by explaining what parameters to pass. It only says 'Show/hide UI components,' which hints at component names and visibility toggles but provides no concrete parameter names, value formats, or examples. This leaves agents guessing about how to structure the API call.

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 'Show/hide UI components' states a specific action (show/hide) and a resource (UI components), but it is vague about which components are affected and how this relates to the broader UI settings. It does not clearly distinguish itself from sibling tools like update_navigation or update_branding, which also handle UI aspects.

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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or context where the tool is appropriate. There is no implied usage beyond the generic statement of functionality.

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