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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds real context beyond them: the operation does not delete hosting, it returns a human review request (i.e., not immediate execution), and credentials are entered privately. It does not explain the review/approval lifecycle or required permissions, but it meaningfully enriches the safety picture.

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?

Three front-loaded clauses with the core action first, then the scope boundary, then the return/security behavior. Every clause carries distinct information and there is no filler.

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 destructive, open-world mutation with no output schema, the description covers the action, its scope limit, the human-review return path, and credential handling. It is largely complete, though it omits permission requirements and the exact meaning/format of revision and connection_id.

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 50%: request_id and organization_id are documented in the schema, while connection_id and revision are not. The description's only parameter reference ('Idempotent request_id') merely restates what the schema already says, so it does not compensate for the undocumented parameters.

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?

The description states a specific verb+resource ('Remove BYOT registration and access') and immediately bounds the scope with 'does not delete hosting'. This clearly positions it against register/update custom-tool siblings, though it never names them explicitly, so it stops short of full sibling differentiation.

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?

Usage is only implied: the verb tells the agent it is used to tear down a BYOT registration, and 'does not delete hosting' implies when it is NOT appropriate. There is no explicit when-to-use, prerequisite, or named alternative against beon_register_custom_tool / beon_update_custom_tool.

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