Check Follow Relationship

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, and the description corroborates rather than repeats them by adding operational facts the annotations cannot carry: an API key is required, it makes one request per call at roughly 1 unit cost, and the response includes a cost estimate. Only the exact failure behavior (e.g. what happens for a nonexistent or protected account) is left unstated.

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 compact sentences, front-loaded with the core action and output semantics, then the username fallback, then the cost/auth note. Every sentence adds distinct information with no restatement of the name or title.

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?

An output schema exists so return values need not be detailed, yet the description still describes both result fields and their direction. Combined with the auth, cost, and prerequisite guidance, an agent has everything needed to invoke this two-parameter 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 coverage is 100% and the schema already describes subjectId as the potential follower and targetId as the potentially followed account. The description reinforces the ordering semantics ('the first follows the second', 'the second follows back'), which removes any lingering ambiguity about which returned field maps to which argument.

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?

States a specific verb and resource ('Check the follow relationship between two accounts by numeric user ID') and additionally defines both output fields, following and followedBy, so the direction of the relationship is unambiguous. This clearly distinguishes it from siblings like tweetapi_user_followers_ids or tweetapi_user_following_list, which enumerate relationships rather than test a single pair.

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?

Gives an explicit routing rule: 'Use tweetapi_user_by_username first if you only have usernames,' which covers the most likely precondition failure. It stops short of excluding alternatives such as the followers/following list tools for bulk checks, so it falls short of a full when/when-not statement.

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