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

The description adds behavioral details beyond the annotations: it mentions the default to the most recent captured day and the flagging of tracked rows. These are useful behavioral traits that the annotations do not convey. With readOnlyHint, idempotentHint, and destructiveHint already provided, the description benefits from the low bar and adds relevant context, though it does not cover potential edge cases like data availability or pagination.

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 exceptionally concise: two sentences plus an example question. Every sentence provides essential information: the core functionality, the default behavior, the reference to another tool, and a practical example. No filler or redundant content.

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 output schema exists (so return values are already documented) and annotations cover safety, the description is complete. It covers the main use case, the default date behavior, the need for reference data, and offers an example. The complexity of 5 parameters is adequately addressed through the conceptual mapping and example, making the tool fully understandable.

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?

The schema description coverage is 0%, but the description compensates by mapping the query terms to the parameters: 'country, platform, chart type and category' directly align with country, platform, chartType, and genreId. It also directs users to list_reference_data for valid values and provides a concrete example with a country, platform, and category. However, it does not explicitly name the parameter identifiers or describe the date pattern, leaving some semantic detail to the schema.

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 what the tool does: it reports who ranks in a given country, platform, chart type, and category on a given day, with the additional feature of flagging rows the user tracks. It uses a specific query verb ('Who ranks') and resource ('top chart'), and the example question reinforces the purpose. It also distinguishes itself from sibling tools by focusing on a single day/chart snapshot rather than historical trends or app overviews.

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 provides clear context by explaining what the tool returns and defaults to the most recent captured day. It also explicitly instructs to use list_reference_data for valid codes, which is a helpful pointer. However, it does not mention alternatives among sibling tools like get_app_history or get_apps_overview, nor does it specify when NOT to use this tool, so the usage guidance is implied rather than explicit.

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