twitter_community_memberships

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It reveals that this is a 'pooled read' and that role/can_join/is_pinned/viewer_relationship_type are always null. It also discloses that an empty array is a real success, not an error, and that the result includes the full community object shape. This adds substantial behavioral context that annotations alone do not provide, and it does not contradict them.

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 relatively long but every sentence earns its place: it starts with the core purpose, then differentiates from siblings, explains the return shape, warns about the id type, clarifies empty results, and notes pooled-read quirks. It is front-loaded with the primary use case. Though not the shortest, the density of essential information justifies its length.

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?

Despite having no output schema, the description fully explains what the caller will receive: 'Each row is the FULL community object (the same shape twitter_community_info returns...), so no follow-up call per community is needed.' It also covers pagination via cursor, the empty-array case, and the null fields on pooled reads. For a 3-parameter tool with no output schema, this is highly complete and self-sufficient.

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 schema already documents all three parameters clearly. The description adds extra value by emphasizing that user_id is NOT a @handle and NOT a community id, and by recommending resolving a handle with twitter_user_info first to avoid a hidden second call. It also confirms count defaults and clamping, reinforcing the schema. This exceeds the baseline of 3 for high coverage.

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's purpose: 'given a numeric X USER id, list the communities that account belongs to'. It uses a specific verb (list) and resource (communities) and explicitly differentiates from other community tools by calling itself the 'INVERSE community lookup' and noting that every other community tool starts from a community, while this one starts from an account. This fully distinguishes it among siblings.

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 explicit when-to-use guidance: 'makes it the tool for profiling which audiences a person sits inside'. It also provides when-not-to-use details: 'Takes a numeric user id ONLY, not a @handle: resolve a handle with twitter_user_info first' and warns about the cost of resolving a handle here. It also clarifies that an empty array is a successful answer, not a not-found, which prevents misinterpretation. These are strong usage guidelines.

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