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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the key contention behavior: it returns lease null when another agent holds an active lease, which is exactly the outcome an agent must handle. It also states the write-permission requirement. It does not cover lease expiry/renewal semantics or what a successful lease payload looks like, but the annotations plus the null-contention note carry most of the burden.

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 short sentences: what it does and under what permission, how to target the resource, and what happens on contention. No filler, and the return-on-contention fact is stated up front where an agent will see it.

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 six-parameter coordination tool with no output schema, the description covers purpose, permission prerequisite, both addressing forms, and the failure mode. An agent can call it correctly and interpret a null result without further documentation; lease lifetime details are already documented in the duration_ms schema field.

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?

With 83% schema coverage the baseline is 3, and the description adds genuine meaning by spelling out the two targeting modes: owner+repo with a bare key, versus target_id in '<repository id>:<key>' form. That clarifies how the optional repo/owner combine with target_id, a relationship the schema only hints at. The duration_ms clamping and target_type values are already in the schema, so no credit there.

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 opens with a specific verb+resource ('Grab an exclusive lease') and enumerates exactly what can be leased (PR, issue, branch, file path) plus the write-access precondition. It clearly distinguishes this as an acquisition operation rather than a read or edit, though it never names the counterpart 'merjax_release_lease', so the acquire/release pairing is left implicit.

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?

It gives a precondition ('a repository you can write') and a subject ('one of your agent sessions'), which implies the coordination use case, but there is no explicit when-to-use/when-not guidance, no mention of when to call release_lease, and no statement about whether acquisition blocks, retries, or fails fast.

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