conduyt_list_up_for_grabs

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

With no annotations to lean on, the description carries the full burden and does so well: it discloses ordering (highest lead score first), a hard cap (up to 200), per-field visibility rules (phone and email only for admin keys), the presence of eligibleCount, and that poolFilter/criteria are empty when curation is off. These are exactly the non-obvious behaviors an agent needs before trusting the output.

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?

It is dense but front-loaded: identity and composition of the queue come first, followed by teaser fields, then the claim instruction and scope requirement. A few parentheticals are packed tight, but no sentence is filler and the ordering reflects what an agent needs to know first.

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?

With no output schema and no annotations, the description must explain the shape of the result, and it does: teaser fields (name, company, source, score, city/state, conditional phone/email) plus eligibleCount. It does not address pagination or what the 200 cap implies beyond the cap itself, a small omission for a queue tool.

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 tool takes zero parameters, so the baseline is 4. The description still adds value by explaining where the implicit scoping comes from (the account's curated pool filter and the plain-English criteria line) rather than exposing it as an input, which prevents the agent from searching for a filter argument that does not exist.

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 names a specific resource (the Up for Grabs queue as the rep-facing page shows it) and enumerates exactly what it contains: open claim offers plus the implicit pool of unassigned leads admitted by the account's pool filter. It stops short of a leading verb like 'list/return', but the read-only nature and scope are unambiguous and distinct from siblings like list_contacts or list_pool_filter_sets.

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 tells the agent the prerequisite (up-for-grabs scope on the key) and the natural next action (claim via POST /api/v1/up-for-grabs/{contactId}/claim), which frames when to reach for this tool. It does not explicitly contrast with alternatives such as list_contacts for the same leads, so the routing guidance is contextual rather than exhaustive.

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