Claim a finding before working on it

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

With no annotations provided, the description fully discloses behavior: the claim lasts 30 minutes, auto-releases on close or expiry, renewing by claiming again is safe, and release:true gives the finding back without closing. It also covers what happens on contention (someone else holds it). This is comprehensive transparency for a lease-mutating operation.

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 appropriately sized for the tool's complexity. It starts with the core action, then seamlessly covers sequencing, conflict handling, lease mechanics, renewal, and release. No sentence is wasted; all information contributes to correct usage.

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 3-parameter tool with no output schema, the description fully covers when to use it, how to handle contention, lease duration and renewal, and the release semantics. It also aligns with siblings by referencing list_findings and close_finding. Nothing critical 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?

While schema description coverage is 100%, the description adds significant practical meaning: id is sourced from list_findings, minutes has a default of 30 with a caution to only request more for genuinely long fixes, and release is tied to the explicit abandonment scenario. This enriches the schema with usage intent and constraints.

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 action: 'Take a finding so no other agent starts on the same one.' It uses a specific verb and resource, and it distinguishes itself from siblings like list_findings and get_finding by establishing this as the locking/claiming step before work begins.

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?

Explicit when-to-use guidance: 'Call this after get_finding and before writing any code.' It also gives a clear exclusion: if someone else holds it, do not work on it and 'pick the next finding from the list instead.' The release parameter is also explained as the abandonment path, providing workflow direction.

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