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

The description goes beyond the basic annotations (readOnlyHint=false, destructiveHint=true) by detailing the irreversible nature of the claim: allowed exactly once, locked afterward, and that changing/clearing is Studio-only. It also explicitly notes that no unclaim/swap tool exists, giving the agent a clear understanding of the long-term consequences. This fully discloses the mutating and potentially destructive behavior.

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?

The description is somewhat verbose but every sentence carries crucial information (unassigned condition, once-only rule, human confirmation, lock, Studio-only override, no unclaim, parameter source). It is front-loaded with the purpose and then explains constraints. A slightly tighter phrasing could reduce redundancy, but the length is justified given the number of important caveats.

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?

The description fully equips an agent to decide when to use the tool and what to expect: it covers the target state (unassigned), the mutation (binding), the restriction (once, locked), the source for the parameter, and the downstream limitation (Studio-only changes). There is no output schema, but the tool returns a confirmation or error implicitly, and that is sufficient. No critical context 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?

The schema already defines `company` as a required string, and the description adds that it can be either a companyId from connections_list_companies or an exact company name. This enriches the schema by providing a format/source, but it does not clarify edge cases like case sensitivity or behavior when an exact name matches multiple companies. Still, it covers the essential semantics beyond the raw 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?

The description clearly states the exact action ('bind this UNASSIGNED registration to a company') and immediately distinguishes it from siblings by emphasizing the one-time, unassigned-only nature. It also cross-references connections_list_companies, eliminating ambiguity about which tool to use for listing companies. This is a precise verb+resource+constraint specification.

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?

The description explicitly defines when the tool should be used ('only while no company is assigned'), states the prerequisite of confirming with a human, and warns about the post-claim lock and the absence of an unclaim/swap tool. It also provides a direct pointer to connections_list_companies for obtaining a valid companyId, offering complete actionable guidance without needing to inspect other tools.

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