User

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

Annotations declare readOnlyHint=false, which would otherwise puzzle an agent calling a simple profile lookup; the description resolves this by disclosing that it is a "read-like POST" that does not publish to social platforms. It also adds two genuinely non-schema facts: possible paid credit consumption and the confirm=true gate. It omits rate-limit or failure behavior, keeping it below a 5.

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 sentences, front-loaded with the payload contents before operational caveats. Every sentence carries information, and the credit/confirm note is placed after the core purpose. The read-like-POST clarification is slightly boilerplate but earns its place given readOnlyHint=false.

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?

There is no output schema, but the description enumerates the returned fields, which compensates. It covers the credit cost and confirm requirement, and the identifier input forms. It leaves gaps around what happens without confirm and whether the identifier parameters are alternatives, so it is strong but not exhaustive.

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 all four parameters are already documented by the schema, making 3 the baseline. The sentence "Pass username, handle, or a full GitHub user url" mostly restates the url/handle descriptions and does not clarify the alternative semantics of the account parameter or whether url/handle are mutually exclusive.

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 ("Retrieves public GitHub user details") and enumerates the returned fields (name, bio, avatar, company, location, blog, follower counts, repo counts, timestamps). The scope is unmistakably the profile-lookup tool rather than the sibling github_repositories or github_followers. It stops short of explicitly naming a sibling to differentiate against, so it lands just under a 5.

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 tells the agent what to pass (username, handle, or full GitHub url) and that confirm=true is required, which is actionable. However, it never contrasts with alternatives such as github_followers, github_contributions, or github_repositories, and gives no when-not guidance. Usage is implied rather than instructed.

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