get_my_rank

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: it raises RuntimeError when YPT credentials are not configured (an auth prerequisite), returns 1-based ranks, and returns None when no rank exists. It does not discuss permissions, rate limits, or whether country/category must match the profile, so it stops short of complete.

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 purpose sentence is front-loaded and efficient, but the Sphinx-style :type: lines restate the integer types already present in the input schema, adding noise without new meaning. The :returns:/:rtype: block is also partly redundant given the output schema exists.

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 simple 2-param read tool with an output schema, the description covers purpose, parameter provenance, the None return case, and the credential error path. The main remaining gap is the absence of any relationship to the get_leaderboard sibling.

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, and it does: both category_id and country_id are documented with their provenance ('as returned by get_profile'), which tells the agent where to obtain valid values. It adds no format/range constraints beyond that.

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+resource ('Return your position in a category leaderboard') and the possessive 'your' implicitly separates it from the general get_leaderboard sibling. However, it never names get_leaderboard or otherwise explicitly differentiates itself, so sibling disambiguation is left to inference.

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?

Usage is implied by the personal-rank framing and the note that both IDs come 'as returned by get_profile', which is a useful call-order hint. But there is no explicit when-to-use / when-not-to-use guidance or statement of how it relates to get_leaderboard.

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