get_records

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently states that it 'Supports natural language field names with fuzzy matching and variations', and that 'Additional match details may be included depending on the field', revealing behavioral nuances. It also clarifies the scope as 'the absolute highest values ever recorded in tracked matches'. However, it does not explicitly state that the operation is read-only or safe, which a fully transparent description would include.

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 long but well-structured: it front-loads the purpose, then gives usage examples, parameter details, return format, common queries, and a full example. Every section adds value, though it could be slightly more concise. The example output is helpful but not essential.

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?

The description is highly complete for a single-parameter lookup tool: it thoroughly explains the parameter, describes the return object with field names and types, and provides a realistic example. It does not cover error cases (e.g., unknown field) or specify a limit on the number of records returned, which are minor gaps.

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 provides only the parameter name 'field' with a generic string type and 0% description coverage. The description fully compensates by listing accepted field categories (Combat, Economy, Farming, Damage, Other) with specific values like kills, gold_per_min, last_hits, and duration, and by explaining that variations like 'gpm' and 'gold_per_min' are accepted. This goes far 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 begins with 'Get top world record performances in a specific statistical field', which is a specific verb+resource combination that clearly defines the tool's function. It further distinguishes the tool from siblings by focusing on 'world record' and 'all-time best performances', and it provides multiple example user queries that uniquely map to this 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 description gives explicit usage context with 'Use this when users ask:' followed by six concrete example questions. It also includes a 'Common queries' section with specific calls, providing clear guidance on when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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