app_detach

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

No annotations exist, so the description carries the full load — and it does: it discloses an implicit side effect (flushes every dirty document via save_all before stopping), the ~500 ms shutdown latency, the fact that Altium's script-backed UI commands are blocked while attached, and the non-recoverable-without-user-action consequence of detaching. That is exactly the context an agent needs before an irreversible session-ending call.

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 imperative and the 'when finished' trigger, followed by justification and then the warning. It runs a bit long across several short paragraphs, but nearly every sentence carries a distinct, decision-relevant fact (keep-alive cadence, UI blocking, save_all, restart requirement).

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?

Covers trigger, side effects (auto-save via save_all), mechanism, latency, post-state of Altium, and the recovery path. An output schema exists so the description need only note the return ('dictionary confirming detachment'), which it does. Nothing an agent needs to call this safely is missing.

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?

Zero parameters, so no parameter semantics are needed; per the rubric a no-parameter tool baselines at 4. The description correctly refrains from inventing parameters, though it could note the absence of options (no force/keep-session flag).

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: stops the Altium MCP polling loop / keep-alive server, and is clearly distinguishable from siblings like app_attach, app_ping and app_save_all. It also names the mechanism (sends application.stop_server so the DelphiScript loop exits) so the agent knows exactly what is being terminated.

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?

Explicit imperative ('CALL THIS WHEN YOU'RE FINISHED'), an explicit timing condition ('once you've finished your Altium work for the session'), and an explicit exclusion ('Don't detach until you're confident you're done', since re-attaching requires the user to relaunch StartMCPServer manually). The alternative path (keep the session attached, or use app_save_all at intermediate checkpoints) is implied by the described consequences.

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