reload_instance

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the risk profile is known. The description adds that the action 'acts on the instances immediately', implying no confirmation or undo step, but says nothing about service interruption, rollback on failure, or what changes if the test rejects the config.

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 short, front-loaded sentences with no filler, and the alternative is named before the caveat. Minor flaw: 'Acts on the instances immediately' uses a plural noun for a single-instance tool, which slightly muddies the scope it just established.

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 destructive single-instance mutation with no output schema, the definition covers what it does and the sibling choice, but leaves out operational consequences an agent should weigh: service disruption during reload, what happens when the config test fails, and whether the previous config is retained.

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 'test' parameter already documents the non-dry-run semantics in detail. The description only echoes the default ('testing it first by default') and adds no syntax, format, or hostname-selection guidance beyond the schema. 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?

States a specific verb and resource ('Reload configuration on one instance') plus the default behavior (test first), and explicitly contrasts with the sibling 'reload_instances'. An agent can pick between the singular and bulk tools without opening either schema.

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?

'Use reload_instances for all' names the alternative and the condition that selects it, giving clear scope guidance. It stops short of stating when a reload should be avoided (e.g. healthy instances or maintenance windows), so there is no explicit when-not.

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