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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: the Instagram-only limitation for follow relationships, the condition 'only for people who have messaged', and the absence of follower lists on any channel. It also implies the refresh parameter behavior by mentioning re-reading from the channel in the schema, but the description itself doesn't discuss rate limits or error behavior. Still, it adds meaningful context beyond annotations.

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 two sentences, front-loaded with the most important information (what a contact is and what fields are returned), followed by a crucial limitation. Every sentence earns its place; there is no fluff or repetition of schema details. The structure is ideal for an agent scanning quickly.

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 read-only tool with a simple schema (one required id, two optional params), the description covers the return fields and key limitations. It doesn't describe the output format (no output schema exists), but the field list effectively substitutes for that. It also doesn't mention pagination or error cases, but for a single-contact read that's less critical. The main gap is not explicitly stating when to use this vs. list_conversations or list_accounts, but the description's clarity about what it returns makes it complete enough for most agents.

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 67% (refresh and workspaceId have descriptions; id has none). The description doesn't explicitly explain the id parameter, but it's obvious from context that id identifies the contact. The description adds meaning by clarifying what data is returned for a given contact, which helps an agent understand what the id refers to. The refresh and workspaceId parameters are already well-described in the schema, so the description doesn't need to repeat them. This is slightly above baseline because the description clarifies the overall purpose of the parameters.

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 tool reads a single contact and enumerates the exact fields returned (name, username, follow relationships, follower count, tags, opt-out, messaging window close). It also distinguishes itself from sibling tools by noting follower lists don't exist on any channel, making this the closest thing. The verb 'read' matches the title and readOnlyHint.

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 provides clear context on when to use this tool: when you need contact details, especially follow relationships and messaging window info. It explicitly notes the Instagram-only limitation and that follower lists don't exist, which helps an agent avoid expecting a list tool. However, it doesn't explicitly name alternative sibling tools like list_conversations or list_accounts for when a list is needed, so it falls just short of a 5.

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