create_instance

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing idempotency-adjacent behavior (fails if the instance already exists) and, crucially, the asynchronous contract: the record is persisted to the database and the scheduler applies it later, so the tool cannot confirm the instance is live. That propagation caveat is exactly the kind of context an agent would otherwise get wrong.

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 opening clause is front-loaded with the verb and resource, and every subsequent clause carries new information (hostname format, defaults, failure mode, sibling routing, async caveat). It reads as a dense semicolon chain rather than clean sentences, which makes the default values slightly harder to parse.

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 7-parameter creation tool with no output schema, the description covers purpose, failure, defaults, and post-write propagation well. It does not say whether the tool returns the created instance's identifier or the stored record, nor how the optional port/https_port/listen_https fields interact with a port embedded in hostname, leaving real ambiguity for an agent assembling the call.

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%, so the baseline is 3, but the description adds real meaning: hostname may carry a scheme and port (with a concrete "https://host:5443" example), and name/method fall back to 'manual instance' and 'api'. The stated name fallback actually conflicts with the schema's declared default of null, which slightly muddies rather than clarifies that one parameter.

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?

"Register an instance" gives a specific verb and resource, and the description immediately names the sibling it is not ("Use update_instance to change one"). An agent can distinguish this from create_service, update_instance, and list_instances without opening any 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?

It explicitly routes modification to update_instance and states the failure condition ("fails if it exists"), which tells the agent when not to call it. It stops short of stating prerequisites such as required permissions or how to check for an existing instance first (list_instances / get_instance are never mentioned).

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