get_people_unclaimed

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It openly discloses a notable deviation from the API default: it sets limit=100 (FUB's max) rather than the underlying default of 10, and explains the intent ('bulk requests are the common case here'). It also describes the pagination contract, telling the agent to check _metadata and use offset or the _metadata.next cursor. This is substantial and useful transparency, though it does not explicitly state read-only behavior or any rate-limit/authorization implications.

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 sentences, no wasted words. The first is a clear purpose statement, the second explains the default-limit override with a rationale, and the third provides actionable pagination guidance. Every sentence earns its place, and the most important information is front-loaded.

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 simple list endpoint with no output schema and three optional parameters, the description gives the essential operational context: what it returns, the altered default, and the pagination mechanics. It does not describe the shape of each returned lead object, but that is likely standard for the API. It also leaves extraQuery usage to the schema alone, which already has a clear description. Overall, the description covers the most important contextual needs for an agent to invoke the tool correctly.

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?

All three parameters are already described in the input schema (100% coverage), which sets the baseline at 3. The description adds practical meaning to two of them: it explains why limit defaults to 100 and when to use offset (when _metadata shows more results). This goes beyond the schema's dry definitions. However, it does not mention extraQuery at all, leaving that entirely to the schema description, so it does not fully elevate beyond the baseline.

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 pair, 'Get unclaimed leads,' and reinforces it with the API endpoint (GET /people/unclaimed). The qualifier 'unclaimed' cleanly differentiates this from sibling tools like list_people (which retrieves all people) and post_people_claim (which modifies ownership). An agent can immediately understand what the tool does and how it differs from nearby alternatives.

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 gives no explicit guidance on when to prefer this tool over siblings such as list_people, get_person, or post_people_claim. It mentions that bulk requests are common, but that is a default-behavior note, not tool-selection advice. There is no 'use this when...' or 'use this instead of...' framing, leaving the agent to infer the usage context from the name alone.

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