Compare two players' libraries

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

Annotations already indicate readOnlyHint and openWorldHint, but the description adds critical behavioral details: it checks FULL libraries (unlike get_owned_games which caps at 50), the returned list is itself capped at top 50 by combined playtime, and it warns about the STEAM_API_KEY and public profile requirements. No contradiction with annotations.

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 well-structured: it starts with the core purpose, then provides key behavioral differences, prerequisites, and caveats. It is concise enough to be quickly parsed but contains all necessary information. A slight improvement could be to break it into clearer sections, but it remains efficient.

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 has an output schema (not shown but mentioned), the description explains important output concepts like 'returned' vs 'shared_count'. It covers prerequisites (STEAM_API_KEY, public profiles), limitations (capped at 50), and usage (omit steamid for self). This provides a complete understanding of the tool's behavior and results.

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% with both parameters described. The description adds valuable context beyond the schema: for steamid, it explains that omitting it uses the server's STEAM_ID and suggests using resolve_vanity_url for vanity names. This enhances understanding, though the schema already provides the pattern and minimal descriptions.

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 verb 'Find' and the resource 'games two players both own, with each one's playtime'. It provides example use cases ('what can my friend and I both play') and explicitly distinguishes itself from sibling tool 'get_owned_games' by noting the cap difference. This makes the purpose highly specific and unambiguous.

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 includes explicit guidance on when to use the tool (finding common games between two players) and when not to (if profiles are private, it returns found:false). It also explains how to omit steamid to compare against oneself and references the sibling tool 'get_owned_games' for contrast, giving complete usage context.

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