set_model_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 behavioral disclosure. It does disclose the partial-update semantics ('omitted settings unchanged') and defines valid values, which helps avoid destructive overwrites. However, it omits other behavioral details such as whether the change is immediate, requires a transaction/commit, or has side effects like triggering a data refresh for storage-mode changes.

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, well-structured sentence that leads with the action and scope, then compactly lists parameters with their allowed values. Every clause earns its place, and there is no redundant repetition of the tool name or obvious padding.

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?

Given the moderate complexity of the tool (5 parameters, 4 settings with enums) and no output schema, this description is remarkably complete: it covers all relevant settings, valid values, and the partial-update behavior. The only minor gap is that the required sessionId parameter is not mentioned in the description, but its role is likely self-explanatory from the schema and the broader tool context.

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 high (80%), and the description adds value by explicitly restating the enum values, explaining 'discourageImplicitMeasures' as 'force explicit measures - a best practice', and giving a concrete culture example. The phrase 'omitted settings unchanged' clarifies the null/default semantics implied by the schema, which is valuable beyond the structured parameter descriptions.

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 uses 'Set model-level settings' as a clear verb+resource combination, and enumerates the exact settings (discourageImplicitMeasures, defaultMode, directLakeBehavior, culture). It is easily distinguished from sibling set_* tools, which target measures, columns, visuals, etc., by the model-level scope.

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 clearly establishes the use case: updating model-level settings, with the key qualifier that 'any subset; omitted settings unchanged' tells the agent when it can safely call this without affecting other settings. It does not explicitly name alternatives or exclusions, but the model-level scope is self-evident against the sibling tools.

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