authorize_managed_docker_session

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

Adds substantial behavioral context beyond annotations: it never builds or pulls an image, requires fresh explicit user consent, and clarifies that allowed_modes must exactly match the summary mode set. These are non-obvious constraints that materially affect invocation, and they do not contradict the destructiveHing 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?

A ll sentences carry information with no fluff, and the safety-critical constraints are front-loaded. The first sentence captures scope, and subsequent sentences add permissions and mode-handling rules. Slightly long four-sentence definition but still disciplined.

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?

Given the high-stakes nature and output schema presence, the description covers purpose, consent, no-build/no-pull, exact-mode requirements, and re-authorization. It does not mention how to retrieve the summary or how this relates to revoke/preview siblings, but those are inferable from context and sibling names.

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 0%, so the description carries the burden. It clearly explains allowed_modes semantics: required, non-empty, must exactly equal the summary set, and expansion requires new authorization. It does not describe the individual enum values, but those are self-evident in the schema, and the authorization parameter's exact const phrase is already encoded in the schema.

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 precise verb ('Authorize') and a specific resource: the immutable image, command, mounts, resource limits, modes, and budget pinned in the project's Docker policy. It clearly distinguishes the 'managed' flavor from the generic sibling authorize_docker_session by emphasizing policy-pinned exactness and adding the no-build/no-pull constraint.

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?

Gives an explicit precondition: a fresh user reply to the exact summary is required and MCP tool permission is not workload consent. It also defines when allowed_modes can be used and when re-authorization is needed, though it does not directly compare against sibling authorize tools such as authorize_docker_session or authorize_docker_optimization_session.

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