VoxelRank

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 covered without the text. The description adds genuine context beyond that: no API key is required, and it enumerates exactly what payload comes back (address, version, online status, players, votes, rank, rating, vote interval, links), which matters because there is no output 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?

A single sentence, front-loaded with the resource and its scope, with the field enumeration and the "no API key" note placed after. The field list is long but earns its place given the absence of an output schema.

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 one-parameter read tool, the definition covers auth requirements and the shape of the returned record, which is the main thing an agent would otherwise lack without an output schema. Minor gaps remain: behavior when the server does not exist, and whether votes/rank fields can be null.

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 the parameter already documents all three accepted identifier forms with examples, so the description can add nothing on that front. Baseline 3 applies: the schema carries the parameter burden entirely.

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?

"One server's public details" plus an explicit field list makes it unambiguous that this is a single-record lookup returning public metadata, distinct from the list/search siblings. It never names those siblings (search_servers, list_my_servers) as the way to obtain the identifier, so differentiation is by inference rather than statement.

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 only implied: the singular "one server" framing suggests fetching details once you already have an identifier, contrasting with the plural list/search siblings. There is no explicit when-to-use, when-not-to-use, or routing to search_servers when the id is unknown.

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 the authentication requirement (listing API key) and the self-scoping constraint, which is real value beyond the annotations, but says nothing about cost, rate limits, or how the metrics are computed.

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?

A single dense sentence that front-loads the resource and scope, then lists the returned metrics in a scannable order. Nothing is padded and the auth note is appended last where it belongs.

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 two-optional-parameter read-only aggregate tool with full schema coverage and no output schema, the description covers purpose, scope, auth and the metrics returned. Only the absence of an explicit sibling contrast keeps it short of full completeness.

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 both `days` and `server` are already fully documented, including the default and the refusal behavior for other listings. The description only restates that per-day counts span `days` days, adding no syntax or default detail beyond the schema. 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?

States a specific verb+resource ('Vote totals for your own listing') and enumerates exactly what the totals contain (today, month, all time, unique voters, rank, per-day counts). That enumeration distinguishes it from the sibling recent_votes without naming it, though an explicit contrast would be stronger.

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 'your own listing' and 'Needs your listing's API key', which makes the scope clear. But there is no explicit when-to-use versus recent_votes or top_servers, and no statement of when this tool is not appropriate.

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 and destructiveHint=false, so the safety profile is covered. The description still adds value beyond them by disclosing an auth constraint ("No API key needed") and by describing what the response contains, with and without the optional game argument.

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 short sentences, zero filler, with the base behavior stated first and the conditional behavior second. Nothing repeats the name or title needlessly.

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 one-optional-parameter read-only tool with full annotation coverage, the description covers purpose, chaining, auth, and return contents. Exact field names in the response are left unspecified, which is a minor gap given there is no output 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 coverage is 100% and the enum already enumerates valid game keys, so the schema does most of the work. The description adds meaning the schema does not: the optional game argument is not just a filter but a request to enrich the response with tags intended for search_servers, which explains why an agent would set it.

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?

"Every game VoxelRank lists, with its key and how many public servers it has" names the resource and the exact payload returned (game keys plus public server counts), and the mention of tags "for search_servers" distinguishes it from the sibling that actually queries servers. It stops short of a crisp verb-first statement but the scope is unmistakable.

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 a concrete usage cue: pass a game to get tags that feed search_servers, which tells an agent how this tool chains into a sibling. It does not state when to call this versus search_servers or top_servers directly, so there is no explicit exclusion 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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds important context beyond that: it requires an API key as a Bearer token and notes each listing has its own key, plus it specifies the return content (review/visibility state, votes, rank).

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 short and front-loads the return content, but the first sentence is a fragment and its phrasing is slightly awkward. Overall it is efficient with no wasted words.

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 covers authentication and return values, which is helpful for a no-parameter, read-only tool. However, it leaves the singular/plural ambiguity unresolved—does it return one listing or many servers?—which is a key gap given the tool name.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain any parameter semantics.

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 what information is returned (review/visibility state, votes, rank) but lacks a clear verb and is ambiguous about whether it returns a single listing or multiple servers. The tool name 'list_my_servers' suggests plural, while the description says 'the listing', creating 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?

No guidance on when to use this tool versus siblings like get_server, search_servers, or top_servers. It only mentions an authentication prerequisite, not situational context.

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?

Beyond the read-only, idempotent, and non-destructive annotations, it discloses oldest-first ordering, the exact vote fields returned, cursor-based pagination, and the API-key prerequisite. These details add substantial operational context without contradicting the 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?

Three compact sentences front-load the resource and scope, then cover result contents, pagination, and authentication. Nearly every clause provides useful operational information, with no filler or unnecessary repetition.

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 read tool with four optional parameters, it covers scope, ordering, returned vote data, pagination, and authentication, including useful result information despite the absence of an output schema. Defaults and listing-selection constraints remain documented in the schema, while annotations cover safety, leaving no material invocation 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 description coverage is 100%, establishing a baseline of 3, but the description adds the important relationship between the response's `next_after` and the `after` argument. That explains the pagination workflow more concretely than the schema's 'higher id' wording alone.

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?

It clearly identifies individual votes for the caller's own listing within the `hours` window and specifies the returned per-vote details. The record-level payload implicitly distinguishes it from `get_vote_stats`, but that sibling distinction is not stated 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?

It gives concrete invocation guidance: use the response's `next_after` as `after` for another page and provide the listing's API key. It does not explicitly explain when to choose this tool over `get_vote_stats` or another sibling.

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, so the safety profile is covered. The description earns additional credit by disclosing the auth requirement ("No API key needed") and the shape of the response (up to `limit` per page with address, players online, votes, links). Pagination caps (page 25) are left to the schema rather than the description.

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 short sentences: purpose, filters, return shape, plus one auth note. Nothing is padded and the core action is front-loaded in the first clause.

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 no output schema, the description correctly summarizes what comes back and confirms no auth is needed, which is the essential missing context for an 8-parameter search tool with all-optional params. It stops short of explaining default behavior with no filters or result-count/ordering guarantees.

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%, with enums documented and per-parameter explanations already in place, so the description only restates the filter categories. It adds no format or interaction semantics (e.g. how tag and query combine) beyond the schema; 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?

Specific verb+resource: "Search the VoxelRank server list" plus the filter dimensions (game, tag, country, keyword) and sorting. It clearly differs from get_server and list_my_servers by being a filtered list search, though it never explicitly contrasts itself with top_servers, the closest sibling.

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 context is only implied: the filter list tells the agent this is the browse/filter entry point, and "No API key needed" signals availability. There is no explicit when-to-use-this-instead-of-top_servers guidance and no statement of what happens when filters are omitted (all servers returned?).

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 read-only, idempotent, and non-destructive behavior. The description adds the time window ('this month'), ordering ('in order'), and auth context ('No API key needed'). It does not describe response fields or pagination, but with annotations covering safety and no output schema, this is still fairly transparent.

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 a single front-loaded sentence with no wasted wording. Each clause contributes useful information: timeframe, game scope, ordering, and auth requirement.

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 read-only ranking endpoint with rich annotations and full schema coverage, the description supplies the key context an agent needs: timeframe, scope, ordering, and no API key requirement. Although there is no output schema, the return shape is inferable as an ordered list of top-voted servers.

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 the schema already documents the game enum and limit range/default. The description adds that omitting the game means across all games and that results are ordered, but it adds no further syntax or semantics for limit. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource and ranking: 'most voted servers this month', with the scope 'one game or across all games' and 'in order'. This clearly distinguishes it from get_server and search_servers by being a ranked list rather than a lookup or 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 explains the parameterized scope (one game versus all games) and notes 'No API key needed', which gives useful context. However, it does not explicitly say when to use this instead of siblings like search_servers or recent_votes, and it gives no exclusions.

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?

Goes well beyond the annotations: it discloses that text is abuse-checked and the invite link is verified with Discord, that a save can be refused with a reason, which fields are immutable via API, and that an API key bound to the listing is required. Annotations only say the tool is non-readonly, idempotent and non-destructive; the description adds the real operational risk profile.

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?

Front-loaded with the core action, then layers on validation, field restrictions and auth in tight sentences with no filler. It is dense but every sentence carries distinct information; slightly more length than an ideal minimum.

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 13-parameter mutation with no output schema, it covers auth, partial-update semantics, validation failure modes and out-of-scope fields. The main omission is what a successful call returns, which forces the agent to guess the response shape.

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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: the call is a partial update ('send only the fields to change') and validation failures can reject the whole save. It stops short of clarifying interactions between fields.

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 and resource ('Change fields of your own listing') and immediately scopes it to the caller's own listing, which separates it from siblings like get_server, list_my_servers and search_servers. The reference to the voxelrank.com edit form gives the agent a concrete behavioral model for what the call does.

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?

Gives actionable usage rules: send only the fields to change, and address/game/Votifier/plugin settings must be changed on the website instead. It does not name sibling tools as alternatives (e.g. use get_server to read current values first), which keeps it from a 5.

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