Scorekeeper

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

Adds substantial context beyond the annotations: the board is publicly shareable, title and team names become public, free boards cap spectators at 50 views and show branding, and the identical requestId plus input should be retried after a timeout. That retry guidance directly operationalizes the idempotentHint in a way annotations alone cannot.

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 dense sentences, front-loaded with what the tool produces, then the intent precondition, then the visibility/limit caveats and the retry rule. No filler sentences.

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 public mutation with an output schema and rich annotations, the description covers the important unknowns: visibility of inputs, free-tier limits, and idempotent retry behavior. Ownership or what a duplicate board creation returns is not addressed, a minor 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?

With 0% schema description coverage, the description carries the load and does so meaningfully: it explains that title and team names are publicly visible and that requestId must be reused identically on retry. It does not cover the requestId pattern or the exactly-two-teams constraint, which remain discoverable only from 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?

States a specific verb and resource ('Create a public, shareable two-team scoreboard'), which cleanly distinguishes it from get_scoreboard, list_scoreboards, update_scoreboard, and hand_off_scoreboard. The trailing fragment 'at zero' is unclear but does not obscure the core action.

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 an explicit precondition ('Requires explicit user intent to create'), which tells the agent when this tool is appropriate rather than a read or update. It does not explicitly name a sibling alternative for modification scenarios, so it falls 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.

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

readOnlyHint=true and openWorldHint=false already declare the safety and locality profile, so the description only needs incremental context. It adds the ownership constraint on the target resource, but says nothing about what happens for unknown/foreign ids (error vs. empty) and its note about output contents partly duplicates the existing 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?

One compact sentence with the resource and the scoping constraint front-loaded; nothing is padded. The trailing clause about team IDs and revision is slightly informational rather than operational, but it is brief.

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 annotations and an output schema present, the description needn't explain return values or safety. It is still missing how to source/format the required id and the failure behavior for ids outside the account, which are the two things an agent needs 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 0% and the single `id` parameter has a pattern constraint but no prose meaning in the schema. The description never mentions the id argument, where to obtain it, or that it must match the pattern, so the coverage gap is left unfilled.

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 ("read a scoreboard") and narrows the scope to scoreboards created through this API by the connected account, which distinguishes it from a generic lookup. It does not explicitly name the sibling it differs from (list_scoreboards), but the singular-object scope makes the distinction inferable.

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 phrase "created through this API by the connected account" implies the usage precondition (only scoreboards owned by the caller are reachable), but no when-to-use/when-not guidance or alternatives are named. An agent must infer that list_scoreboards is the route for discovery and this tool for a known id.

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 beyond the annotations by disclosing that ownership is not transferred, that the returned link is sensitive and should be scoped to one scorer, and that requestId should be reused on retries (reinforcing idempotentHint=true). It does not say whether earlier links are invalidated, whether the link expires, or that readOnlyHint=false means state changes on the server.

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?

Four short sentences, front-loaded with what is returned, followed by the sharing constraint and the two key behavioral caveats. No sentence is filler.

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?

Output schema and annotations already cover return shape and safety profile, so the description only needs to fill in semantics and cautions. It does that for secrecy and idempotency but leaves the identity of 'id' and the lifecycle of the link (expiry, single-use, invalidation of previous links) unstated.

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 carry parameter meaning. It explains retry semantics for requestId but never defines what 'id' identifies (scoreboard vs. session) and adds no constraint guidance beyond the schema's pattern 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: it returns the connected account owner's private management link, which is clearly distinct from get/list/update/create scoreboard siblings. It does not explicitly tie the link to the required 'id' parameter, so an agent must infer that the link is scoped to a specific scoreboard.

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?

"Share it only with the intended scorer, never spectators" constrains downstream use of the result but says nothing about when to call this tool versus get_scoreboard or update_scoreboard. Usage is implied by the hand-off framing rather than stated as a selection rule.

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 read-only, non-open-world operation. The description adds useful behavioral detail beyond annotations: pagination continues by passing nextCursor as cursor until null, and a filtered page may legitimately be empty.

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 with the primary purpose front-loaded, followed by the key exclusion and pagination behavior. There is little wasted text.

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 and read-only annotations, the description covers scope, exclusions, and pagination well enough to call the tool correctly. The main remaining gap is that limit semantics are left entirely to 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 0%, so the description must compensate. It explains cursor semantics and continuation behavior, but does not explain the limit parameter or its 1–100 range.

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 (list scoreboards) and narrows scope to the connected account's API-created generic scoreboards, explicitly excluding unrelated legacy boards. This distinguishes it clearly from the get/create/update siblings.

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 clear usage context for listing API-created generic scoreboards and explicitly notes that legacy boards are not returned. It also explains cursor continuation, though it does not explicitly route to a sibling tool such as get_scoreboard.

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 the operation destructive, open-world, and idempotent, but the description adds meaningful context beyond them: updates are atomic, changes appear publicly immediately, revision conflicts require re-reading, and identical retry IDs return the previous result. It does not discuss permissions or the full scope of what may be overwritten, so it stops short of a 5.

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 dense and front-loaded: it starts with the operations, then gives revision handling and retry semantics. Every sentence carries operational value with no filler.

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 destructive, open-world mutation tool with an output schema, the description covers atomicity, public visibility, conflict handling, and retry idempotency well. It is missing explicit sibling selection guidance and does not reconcile the empty input schema with its references to team IDs, revisions, and retry IDs.

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 declared parameters, so the baseline is 4. The description adds conceptual guidance about stable team IDs, last read revision, and retry IDs, though those inputs are not present in the empty schema, which limits how actionable that guidance can be.

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 specific operations (set exact scores, increment scores, rename teams, change title) on an implied scoreboard resource, so the agent can tell what the tool does. It does not explicitly differentiate this from siblings like hand_off_scoreboard or get_scoreboard, 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?

It gives useful operating guidance for conflicts and retries, including reading the board again on revision_conflict and not blindly replaying stale increments. However, it does not say when to use this tool versus alternatives such as hand_off_scoreboard or get_scoreboard.

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