Set User Markup Config

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, so the description's main added value is the permission requirement (ADMIN operation), the multiplicative interaction with the Ashar spread, and the statement that it returns the updated user_markup. The notable omission is what happens to a spread parameter that is left out — reset, or left unchanged — which matters for a non-idempotent partial-update 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?

Front-loaded with the core action and the ADMIN warning, followed by useful domain context and then a compact Args list. The Args section is largely redundant with a 100%-covered schema, which costs a little, but nothing is verbose and every other sentence carries real information.

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?

With no output schema, the description correctly states the return value ("the updated user_markup"), which is exactly what is needed. For a 3-param mutation tool with full annotations the definition is nearly complete; the only missing piece an agent would want is the behavior when one of the optional spread params is omitted.

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 the schema itself documents all three parameters, so the schema already carries the load. The description's Args block restates the same fields and adds the explicit "optional" marker for the two spread params, but does not clarify omitted-parameter semantics or whether the percents are additive vs multiplicative relative to the Ashar spread at the parameter level. Baseline 3 applies.

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 gives a specific verb+resource (set end-user markup for a tenant) and explains what that markup actually is — a second spread layer applied multiplicatively above the Ashar margin. That conceptual framing makes it easy to distinguish from partner-fee tools. It never names the direct read counterpart ashar_get_user_markup, so sibling routing is inferred rather than stated.

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?

It labels the tool an "ADMIN operation" and explains the architectural context (upstream only sees the Ashar partner, so end-user spread is configured locally), which implies who should call it and under what circumstances. However, there is no explicit when-not-to-use guidance and no pointer to alternatives such as ashar_get_user_markup for inspection or the partner-fee tools for the upstream layer.

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