player_avatar

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

With no annotations present, the description carries the full burden and delivers richly: it discloses that it makes a logical HTTP request, inspects the 302 Location without following it, does not download image bytes, that the URL may change, that a returned avatar does not prove account existence, and that no credentials or game writes are involved. This comprehensively sets expectations for a read-only resolve operation.

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 front-loaded with the core purpose, followed by behavioral details and caveats. Each of the six short sentences adds a distinct piece of information: purpose, mechanism, output fields, domain constraint, no-download behavior, volatility, non-proof of account, and safety. No fluff or redundancy.

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 single-parameter tool with no output schema? The description explicitly lists the return fields (avatar_url, image_url, redirect_status) and covers critical caveats like URL volatility, domain restrictions, and lack of account-existence proof. The tool's complexity is fully addressed; an agent has everything needed to call it 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 0%, so the description must compensate. It implicitly ties the single 'name' parameter to the player via 'one player's legacy profile image link,' but does not explicitly state that the 'name' parameter is the player account name or what format is expected. A clearer explicit mapping would be needed to fully compensate for the schema's silence.

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 ('Resolve'), a resource ('one player's legacy profile image link'), and explicitly distinguishes it from the avatar-builder character by noting 'is not the avatar-builder character.' This disambiguates it from sibling tools like player_custom_avatar without needing to open schemas.

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 context by positioning itself as resolving the legacy profile image link and contrasting with the avatar-builder character, implicitly indicating when to use this tool. It does not explicitly name alternatives or state 'when not to use,' but the distinction is unambiguous enough for an agent to route correctly.

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