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

The annotations already establish read-only and non-destructive behavior, and the description adds useful scope details: contacts come from one chosen Airtable base, only mapped fields are returned, and remaining fields require read_body. It does not cover pagination or connection/permission requirements, but with rich annotations and an output schema, this is a solid addition rather than a critical gap.

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 short and front-loaded with the primary behavior and scope. It is slightly redundant with the annotations by restating read-only behavior, and the read_body reference is not self-explanatory, but there is little wasted text.

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 seven-parameter tool with a nested object and low schema description coverage, the description omits key calling details such as what companyId and connectionId select, how table relates to the chosen Airtable base, and how pagination works. The output schema and annotations reduce the burden, but the description is still incomplete for correct invocation.

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?

Schema description coverage is only 14% across seven parameters, so the description must compensate, but it explains only the optional text filter, agent_name, and the notion of a chosen base. It says nothing about companyId, connectionId, pageToken, maxResults, or the nested UUID wrapper, leaving most parameters semantically unclear.

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 states a specific verb and resource: listing contacts from the company's connected CRM, specifically Airtable with one chosen base. The mapped fields and optional text filter make the tool's scope concrete and distinguish it from Dex-contact or generic connected-data listings.

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 some usage context: an optional text filter, passing agent_name, and using read_body for remaining record fields. However, it does not explicitly say when to choose this tool over related siblings such as connection_list_dex_contacts or other connection-list tools.

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