register_deployment

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

Delivers high-value behavior that annotations cannot express: the response contains authentication and registry credentials exactly once, they are exposed in the MCP transcript, and the agent must store them securely and never log them. Also discloses enterprise gating and the 403 error on ineligible plans. This goes well beyond the flag-only annotations (readOnlyHint=false, idempotentHint=false) and meaningfully shapes how the agent should handle the return value.

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?

Purpose is front-loaded and the structure flows well (purpose → context → security → error). However, 'Enterprise-gated' appears verbatim twice in a roughly 50-word description, which is redundant and sloppy. The credential warning is also somewhat wordy but earns its place given its criticality.

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 the essential non-schema context: when to use it, the sibling alternative, the one-time credential exposure and storage imperative, the logging prohibition, the enterprise-plan restriction, and the 403 failure mode. With a 100%-covered 13-parameter schema and an output schema present, nothing an agent needs to call this correctly 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?

Schema description coverage is 100%, so every one of the 13 parameters is already documented; baseline 3 applies. The description adds no parameter-level meaning beyond what the schema provides, though the credential warning indirectly implies the response varies with parameters. This is acceptable given the schema carries the full load.

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 ('Register a self-hosted Gateway deployment') plus the precise triggering context ('when onboarding a new control-plane target'). It also names the sibling it is not ('use list_deployments for existing registrations'), so an agent can distinguish it from the deployment family without opening the 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?

Explicitly ties usage to a condition ('when onboarding a new control-plane target') and names the alternative for existing registrations (list_deployments). The 403-on-non-Enterprise caveat also tells an agent when the operation will fail. It does not explicitly route modifications of existing registrations to update_deployment, which is a minor gap given that sibling exists.

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