DXRating

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds only the achievement unit encoding (1/10000 of a percent) and does not say what happens with unresolvable song names, whether lookups are case-sensitive, or how partial score lists are handled.

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?

Two sentences, both dense with substance and no filler; the unit caveat is placed last where it is needed. The opening is a noun phrase rather than a verb-led sentence, which makes it slightly less scannable, but nothing is wasted.

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?

With an output schema present, return values need not be explained, and the description correctly focuses on inputs and computation. However, for a calculation tool that overlaps with a sibling, the omission of how it differs from calculate_rating and of tie-breaking or missing-chart behavior leaves a real gap.

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%, so every parameter is already documented inline, including the achievement encoding and enum values, which the description partly repeats. The description adds no new meaning for 'server', 'version' beyond what the schema states, or 'suggestions' beyond the default of 10.

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 names the specific domain object (a maimai DX player's Best 50 rating) and enumerates the concrete outputs: b15, b35, per-chart ratings, and ranked improvement suggestions. That is far beyond restating the title, but it never distinguishes this from the sibling calculate_rating, which is the obvious source of agent confusion.

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?

There is no statement of when to use this tool versus calculate_rating, no prerequisite about needing a complete score list, and no explanation of the tradeoff when to raise or lower 'suggestions'. Usage must be inferred entirely from the description of what is computed.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety needs no restating. The description adds a genuine behavioral detail — that chart lookup uses the chart's *current* internal level, which varies by server — but the achievement unit encoding it also explains is already spelled out in the schema.

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 with no filler, but the lead sentence is a dense enumeration without a main verb, which slows parsing. The unit-conversion example partly duplicates the achievement field description.

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?

With 8 all-optional parameters and a rich output schema, the description should clarify which parameter combinations are valid (song+type+difficulty vs internal_level; achievement vs target_rating). It gestures at the first split but not the second, leaving ambiguity about a zero-required-argument call.

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 every parameter including server, combo and internal_level is already documented. The description only reinforces the song-vs-internal_level choice and the achievement encoding, adding little beyond the schema and nothing about how song/type/difficulty combine.

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?

Names the three computations (rating from achievement, achievement needed for a target rating, rating of each rank S–SSS+), which is specific enough to separate it from calculate_best50 and the lookup tools. The opening sentence is a verbless list of noun phrases, so the reader has to infer 'calculate' from the tool name, and no sibling is named explicitly.

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?

"Give a chart ... or an internal level" implies the two input modes but never states when to use this tool over calculate_best50 or get_sheet. It also does not say that achievement and target_rating are alternative purposes rather than combinable inputs, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered and the description need not repeat it. What the description adds is content scope — notably that internal levels are reported both now and in past versions, and that servers/community tags are included. It says nothing about behavior on a miss (unknown song, ambiguous title) or about response volume, which would be the genuinely valuable additions here.

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?

Two sentences, front-loaded with the resource and the returned fields, then the filtering scope. No filler or hedging. It is dense with Japanese terms and parenthetical glosses, which is justified for domain naming but makes it slightly harder to scan than a plainer phrasing would.

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?

An output schema exists, so return values need not be described, and the description nonetheless summarizes the payload well; annotations cover safety, and the schema fully documents all five parameters. The remaining gap is workflow placement — nothing tells the agent this is typically called with an ID obtained from search_songs (that hint appears only inside the schema).

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% and every parameter carries enum values or a precise description, so the schema does the heavy lifting; baseline 3 applies. The description's 'filter by type, difficulty and server' merely restates the schema's parameter names and adds no syntax, defaulting, or interaction details beyond it. The nuance that a server filter yields that server's own level where it differs lives in the schema, not the description.

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 concrete verb-and-resource pair: returns details of a maimai DX song and its charts, and enumerates the specific data returned (level, internal level across versions, note counts, designer, release date, servers, tags). That is far more specific than the title alone. It does not explicitly distinguish itself from the sibling search_songs, so an agent must infer that this is the detail/lookup tool versus the discovery tool.

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 closing sentence 'Filter by type, difficulty and server' implies the narrowing use case for the optional parameters, which is useful context. However, there is no explicit when-to-use statement, no mention that this is the follow-up call after search_songs, and no guidance on when to prefer or avoid it over the sibling calculate_* tools.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds meaningful behavioral detail beyond that: ordering is newest first, results are grouped by release date, both new songs and new charts for older songs are included, and dates are Japan-based.

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 behavior and contains no obvious filler. The first sentence is dense but informative, and the later sentences about usage and Japan dates are short and purposeful.

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?

With full schema coverage, rich annotations, and an output schema, the description covers enough for an agent to understand the tool. One minor gap is that 'Release dates are those of Japan' could be read as slightly at odds with the server parameter's server-specific date semantics.

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 the schema already documents days, limit, since, and server thoroughly. The description adds some date-related context in saying release dates are those of Japan, but it does not materially clarify parameter behavior beyond 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 states a specific verb and resource: lists recently released maimai DX songs and charts, newest first, including new songs and newly added charts for older songs. It also distinguishes the use case as 'what is new' questions, which separates it from a general song search.

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 gives clear usage context: use it for 'what is new' questions. It does not explicitly name alternatives such as search_songs or state when not to use it, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior those annotations cannot convey: results are ranked best-match-first and each chart carries its level and internal level (譜面定数), which tells the agent what to expect from the response.

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?

Two sentences, front-loaded with the match fields and result ordering, ending with the concrete use case. No filler and nothing repeated from the schema verbatim beyond necessary framing.

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?

An output schema exists, so return values need not be fully explained, yet the description still flags the key payload (level and internal level per chart). Combined with 100% schema coverage and clear annotations, an agent has everything needed to call this 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 100%, so query, type and limit are all documented in the schema itself, including normalization rules (width, case, kana and punctuation ignored). The description restates the query field's scope and adds the ranking order but does not extend the type or limit parameters, so baseline 3 applies.

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?

Names a specific verb and resource ('Finds maimai DX songs') and enumerates the matchable fields (title, alias, nickname, romanization, artist) plus result ordering and returned chart data. It does not explicitly distinguish itself from the nearest sibling list_recent_songs, which keeps it from 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?

'Use it to get the song ID of a song the user names' gives a concrete triggering condition, which is more than implied usage. It stops short of naming alternatives or when-not-to-use cases (e.g., browsing recently played songs vs. searching by name).

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