Modify a plan constant

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses that the operation 'may notify recipients or change tenant data' and requires 'operator write opt-in and confirm:true'. This adds important side-effect and authorization context that the annotations alone do not provide, and it does not contradict any annotation.

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 compact and information-dense: purpose, endpoint, body fields, reference, and key behavioral requirements are all conveyed in three sentences with no filler. Critical details are front-loaded.

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?

For a mutation tool with nested body, confirmation requirement, and no output schema, the description covers the essential operational aspects: what it modifies, what fields to provide, the need for confirm and write opt-in, and potential side effects. It does not describe response/error handling, but that is less critical here and the description is otherwise sufficient.

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 schema coverage at 75% and the body schema using a generic 'Complete API JSON payload', the description compensates by listing the body fields (id, name, value, description), giving concrete meaning beyond the schema. The confirm parameter's const is already in the schema, so no extra credit there, but the body field list is valuable.

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?

Description states a specific verb ('Modify') and resource ('plan constant'), and includes the HTTP method and endpoint, making the operation unambiguous. It is clearly distinct from sibling tools such as create/delete plan constant.

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 purpose is implied by 'Modify a plan constant' and the endpoint, but there is no explicit guidance about when to choose this over create/delete or other alternatives. It does not mention exclusions or prerequisites beyond write opt-in, so usage guidance is adequate but largely implicit.

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