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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: it notes that learned_voice is read-only and never overwrites the brand profile, that performance_profile may return null with a reason for non-Pro plans, and that connect_session polling should stop at connected, failed, cancelled, or expired. It also mentions that connection status reasons/dates are returned but never tokens. These additions significantly enhance transparency, though rate limits or auth requirements are not covered.

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 information-dense and front-loads the overall purpose before detailing each view. Every sentence serves to explain a view's behavior or a specific constraint. It is somewhat lengthy but justified by the tool's complexity (four views, multiple parameters), though it could be structured with clearer separation (e.g., bullet points) for readability.

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?

Given the tool's complexity (multiple views, five parameters, no output schema) and rich annotations, the description is mostly complete: it covers what each view returns (summaries, traits, stats, status polling) and includes critical usage details (read-only nature, plan requirement, polling stop conditions). It lacks minor details like pagination behavior or error handling, but these are not essential 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?

Schema description coverage is 100%, so the baseline is 3 even without additional parameter info in the description. The description does reiterate the purpose of each view and the connection filter, but it largely duplicates what the schema already provides (e.g., the schema already describes account_id's required views and workspace_id filtering). It adds marginal semantic clarity beyond the schema, such as the Instagram-specific check, but does not compensate for any schema gaps.

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 ('list' implied by name) and resource ('connected social accounts') and elaborates on the multiple views (accounts, learned_voice, performance_profile, connect_session) that this tool uniquely serves. It distinguishes itself from siblings like list_platforms (which likely lists available platforms, not connected accounts) through the detailed view breakdown.

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 clear usage context for each view and specific conditional guidance, such as 'check this before Instagram user_tags or collaborators' and 'Pass connection=needs_reconnect to list only accounts that need a reconnect.' However, it does not explicitly name alternative tools or state when to use this tool versus sibling listing tools, leaving some implicit.

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