trmnl_complete_installation

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds a modest confirmation ('Changes remote state or starts work') and 'once' implicitly aligns with non-idempotency, but it never says what state transition completion performs, what happens on a second call, or what error conditions exist.

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?

Short and front-loaded with the action, but the second sentence is a raw, oddly punctuated endpoint dump ('TRMNL POST /api/...'), and the lead clause 'Complete an installation once' is a fragment. No sentence is wasted, yet the structure reads as generated rather than authored.

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 non-idempotent state-changing call with a nested path object, no output schema, and generic boilerplate, this is borderline. An agent knows the verb, the target resource, and that it mutates remote state, but lacks any statement of the resulting installation state or failure modes, so it is incomplete for confident invocation.

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 only 50% -- the profile parameter is documented, but plugin_installation_id has no description beyond its UUID format. The endpoint template in the description confirms that the ID is a path segment, adding a little positional meaning, but it says nothing about what 'completing' does to that installation or how profile selection affects the outcome.

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 ('Complete an installation') and even names the underlying HTTP operation, which lets an agent distinguish it from siblings such as trmnl_prepare_installation or trmnl_cancel_installation. The trailing 'once' is fragmentary and slightly ambiguous, and no sibling is named explicitly, so it stops short of a 5.

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?

There is no when-to-use guidance, no prerequisite (e.g. 'installation must be prepared/connected first'), and no explicit alternative named. 'Run only within the user-authorized scope' is a generic safety boilerplate statement rather than routing guidance.

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