qrvote

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

Annotations already declare destructiveHint=false, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds the auth requirement (organizer key), which is genuinely beyond the annotations, but omits what happens on duplicate entries or to existing ones.

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, front-loaded statements with essentially zero waste. It is slightly run-on (no punctuation between the two clauses), but nothing is padded.

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 two-parameter mutation with no output schema, the description covers the key precondition (organizer key) and is backed by annotations for safety flags. It still leaves entrants/duplicate behavior and result format unexplained, so it is adequate but not complete.

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 only 50%, and the description adds no parameter meaning at all – it never mentions slug or the entrants array. The schema itself documents slug well and partially documents entrant fields, but the description does not compensate for the coverage gap.

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 a specific verb and resource ('Add entries ... or checkpoints') and clarifies that the same tool targets two campaign types. It does not distinguish itself from siblings like add_judge, so it stops short of 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?

'Needs the organizer key' states a real precondition for invoking the tool, which is useful. However, there is no guidance on when to use this versus other add_* siblings or any exclusions, leaving usage largely implied.

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 declare the safety profile (readOnly=false, destructive=false, idempotent=false), but the description adds meaningful extras: the organizer-key auth requirement, the side effect that the judge will appear at getDashboard → judging.judges, and the private scorecard link format that must be shared only with that judge. It does not address re-adding an existing judge or failure modes, keeping it below 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 sentence opens by restating the title verbatim ('Contests: add a judge (judging must be on)') before delivering new content, then crams preconditions, auth, return behavior and a URL template into one run-on sentence. The actionable information is present but not well front-loaded or organized.

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 usefully explains what the agent gets back (the judge listed on the dashboard with a private scorecard link) and what auth is needed. Only the undocumented 'name' parameter leaves a small gap for a two-parameter mutation tool.

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 only 50%: the slug property carries its own pattern description, while 'name' is undocumented. The description surfaces the slug's role through the example link but adds no constraints on the judge name (e.g., the 60-char limit), so it only partially compensates for the coverage gap.

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 gives a specific verb+resource ('add a judge') and states the precondition ('judging must be on'), which clearly separates it from siblings like remove_judge and add_entries. It never explicitly names an alternative, so it stops short of the sibling-differentiation bar for 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?

'Judging must be on' and 'Needs the organizer key' give a clear precondition and authorization requirement, and 'Give it to that judge only' prescribes a follow-up action. It provides solid context but no explicit instruction on when to choose this over other judge-related 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 only give the generic safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds genuinely non-derivable behavior: a 5-per-day-per-connection rate limit, the return of a public link plus a one-time claim link valid 24 hours, the organizer-dashboard grant, and the explicit security instruction never to ask for or share the organizer key.

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 action and its auth prerequisite are front-loaded in the first clause, and every clause carries information (scope, rate limit, outputs, security rule, alternative). It is a dense compound sentence with an inline URL, which slightly hurts scannability but does not waste 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?

For a 13-parameter creation tool with no output schema, the description usefully covers auth scope, rate limit, resulting links and the fallback tool, so an agent knows the preconditions and the side effects. It does not say which parameter groups each kind needs (entries for contests/hunts, questions for surveys/quizzes), a gap partially absorbed by the schema's field descriptions.

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 77% and the schema already carries the meanings of kind, entries, questions, categories, mode, results and closesAt. The description adds no parameter-level guidance beyond what the schema documents (e.g. it never explains which parameters are required per kind), so this sits at the baseline the rubric prescribes for high schema coverage.

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 action (create now, immediately manageable on this connection) and the resource is unambiguous from the title and the 'kind' enum context. It explicitly positions itself against the sibling draft_contest, so an agent can route between the two without opening either schema.

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 names the prerequisite (signed-in connection with Manage scope), the condition that selects a different tool ('Without signing in, use draft_contest'), and the constraint that this connection can manage the result right away. Nothing about when to use versus when not to use is left to inference.

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?

Adds substantial behavior beyond the annotations: nothing is created until a human clicks Create, the link requires a human check, and the follow-up management path is spelled out. This human-in-the-loop constraint is the single most important thing to know and annotations alone would not convey it. Consistent with readOnlyHint=true.

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, front-loaded with the core action and outcome, no filler. The closing organizer URL is slightly tangential to invoking the tool but is a legitimate handoff note.

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 draft tool with no output schema, the description explains what is produced (a link), what the link contains, what the recipient must do, and what happens next. Remaining gaps (validation behavior, error cases) are minor and largely covered by 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 coverage is 77%, and the description's field list ('name, entries or questions, rules, closing time, look') supplies natural-language meaning for several of the undocumented params (title, entries/questions, theme, closesAt). It stops short of syntax or format detail, so it complements rather than replaces 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 precise verb and artifact: 'Make a link that opens QRvote's create form already filled in', and lists what the link pre-fills. It implicitly but clearly separates itself from the sibling create_contest by stating 'Nothing is created until they do' — the agent knows this drafts, not creates.

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: hand the link to a person who checks it and clicks Create, and points to the organizer endpoint for subsequent management. It does not explicitly name create_contest as the alternative for programmatic creation, so the when-not case is only implied.

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 non-openWorld, so the safety profile is covered. The description adds a genuine behavioral fact the annotations do not carry: an organizer key is required for authorization.

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 front-loaded sentence with the resource list first. It is efficient, though the missing punctuation between 'CSV' and 'Needs' makes the two ideas run together.

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 exporter this is largely adequate: destination format (CSV) and auth requirement are stated. However, with no output schema, it gives no hint about what columns or scope the export contains, leaving a small 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?

There is only one parameter (slug) and schema description coverage is 100%, with the schema even providing a concrete URL example. The description adds nothing about the parameter, so the baseline of 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 (Download) and the exact resources available (votes, survey responses, hunt players) in CSV form. It is clear enough to separate from generic readers, but it never explicitly distinguishes itself from close siblings like get_results or list_responses, which cover overlapping data.

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 'Needs the organizer key' signals a prerequisite but says nothing about when to choose this over get_results or list_responses. Usage is only implied by the CSV output format.

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=true and idempotentHint=true, so the safety profile is covered. The description adds one concrete behavioral detail: entry QR codes are never included when scanning is required. That's useful but thin; there's no note on what gets returned or pagination. Not contradictory, but the added value over annotations is modest.

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 opening clause duplicates the title verbatim, and the sentence lists data types without a clear action verb. It is short but not front-loaded with what the tool does, making it hard to scan.

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 one required parameter, no output schema, and full annotation coverage, the description is mostly adequate on structured fields but fails to state the tool's core action. It leaves ambiguity about whether this retrieves, searches, or modifies a campaign.

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 slug parameter already has a detailed description with pattern and example. The description adds no parameter-level detail (e.g., error behavior on unknown slug). Baseline 3 applies when the schema fully documents the parameter.

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 restates the title/name rather than stating what the tool does. It is a noun phrase ('A contest, survey or hunt as the public sees it') with no verb indicating retrieval, and no differentiation from siblings like get_results or get_dashboard. The added sentence about entries/questions/checkpoints describes data fields, not the tool's 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?

The phrase 'Public: no key needed' implies a read access context, which suggests when it can be used (unauthenticated public view). However, it offers no explicit when-to-use vs when-not-to-use guidance and names no alternatives among the many sibling 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 cover safety (readOnly, idempotent, non-destructive), so the extra value here is real: it discloses the authorization requirement ('Needs the organizer key') and explains the semantics of campaign.note as a moderator message to relay to the organizer. That is behavioral context an agent cannot get from the schema or 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?

Dense and front-loaded with payload contents, then the auth requirement and the non-obvious note semantics. The opening sentence is slightly malformed (title and content run together), but every clause earns its place.

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 in play, the description has to convey what comes back, and it does by listing the dashboard sections plus the special campaign.note field and the auth prerequisite. It stops short of describing size or pagination, but nothing critical for correct invocation is missing.

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 slug parameter is documented with a concrete URL example, so the schema carries this dimension. The description adds nothing about slug format or behavior.

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 enumerates what the dashboard returns (settings, entries with vote counts, ballot tickets, fairness signals, survey/hunt data), which is more specific than the title's 'everything on the organizer dashboard'. It reads as a read/retrieval tool and is distinguishable from narrower siblings like get_results or get_campaign, though it never states a verb outright.

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: an agent can infer this is the broad 'get the whole dashboard' call versus narrower siblings, but nothing says when to prefer it over get_campaign or get_results, or whether it's expensive/heavy. No exclusions or alternatives are named.

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 bar is lower. The description adds real behavioral context beyond them: visibility gating, what contests return (categoryResults, judgeResults), and explicit exclusions (written answers and individual judge scores are never included). That privacy boundary is valuable disclosure.

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?

Content is front-loaded and dense with useful facts, but the opening clause simply restates the tool title before getting to the visibility rule. Minor redundancy, otherwise no wasted 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?

There is no output schema, so the description correctly compensates by describing the returned result shapes and the privacy exclusions. It covers enough for an agent to call and interpret the tool, though the public/private visibility semantics could be spelled out slightly more.

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 there is a single slug parameter whose format and example origin are fully documented in the schema. The description adds nothing about the parameter, so the 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?

The description names a specific verb+resource (retrieving results) and enumerates the three shapes it can return (vote tallies, survey totals, hunt leaderboard), which is concrete. It does not explicitly distinguish itself from siblings like list_responses or export_csv, so it stops short of 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 one conditional: 'Public when the organizer made results visible; otherwise send the organizer key,' which is useful auth guidance. However, it never says when to choose get_results over export_csv or list_responses, so alternative-selection guidance is only implied.

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?

Adds substantial behavior beyond the annotations: the legal state machine, the 409 failure mode, the auto-advance clock (hostSecs per question, 8 s per answer reveal), and how pause/resume and manual steps interact with that clock. It also discloses the organizer-key auth requirement, which the annotations (only readOnly/destructive/idempotent/openWorld) do not cover.

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 action list, then tight sentences on ordering, timing, and auth — every clause carries information. The only waste is the opening clause duplicating the title almost verbatim.

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 non-idempotent mutation tool with no output schema, the description covers auth, legal ordering, failure codes, and timing side effects, which is nearly everything an agent needs. It omits any indication of what a successful call returns, a minor gap given no output schema exists.

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 50% — slug is documented in the schema but the action enum is not. The description compensates by spelling out the body shape and describing what pause/resume actually do to the clock, giving real meaning to two enum values the schema leaves bare.

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 ('Run a live quiz') and enumerates the exact state transitions it performs (start, reveal, next, finish, pause/resume). No sibling tool in the list does this, so an agent can distinguish it immediately from get_dashboard, get_results, or update_settings.

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 concrete applicability conditions: only for quizzes with host = true, and it requires the organizer key. It also specifies the legal call ordering (lobby → question → reveal → … → done) and that anything else returns 409. It does not name an alternative tool for the non-host case, but the gating condition is explicit.

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, closed-world, non-destructive. The description adds genuinely new behavioral context: results are truncated at 500 rows and ordered newest-first, quiz responses carry scores, and an organizer key is required. It stops short of saying what happens past 500 (silent truncation vs. 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?

Two short sentences with zero filler; the scope constraints (ordering, cap, quiz scores) are front-loaded and the precondition is last. Every clause earns its place.

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 does the work of describing the return payload (ordered responses, up to 500, with quiz scores) and the auth requirement. It is complete enough to call correctly, though it omits overflow behavior beyond the 500 cap.

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 single 'slug' parameter is documented in the schema with both pattern and a worked example URL. The description adds no meaning beyond the schema, 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?

States a specific verb+resource ('Survey responses') with concrete scope modifiers: newest-first ordering and a 500-row cap, plus conditional content for quizzes (scores included). It does not, however, differentiate itself from close siblings like get_results or export_csv, so the agent must infer the boundary.

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 only guidance is a prerequisite ('Needs the organizer key'), which is a prerequisite rather than a when-to-use rule. Nothing says when to choose this over get_results (aggregate results) or export_csv (file export), and no exclusions are given.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the cascade (link and scores are also removed) and the authorization requirement (organizer key), both of which affect how an agent should invoke it.

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?

Very short and the purpose is front-loaded, which is good, but it is a run-on sentence with a missing break before 'Needs', making it feel like a tidied title rather than a crafted 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?

For a destructive cascade-removal tool, the description does disclose the auth requirement and what else gets deleted, and annotations carry the destructive/idempotent hints. However, it never explains the 'id' parameter, and with no output schema the agent gets no sense of the response beyond annotations.

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 only 50% – 'slug' is documented with a pattern and example, but 'id' has no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented half of the inputs.

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 ('remove') and resource ('a judge') plus the scope of the removal ('their link and their scores'), which distinguishes it cleanly from the sibling add_judge. An agent can identify this as the inverse of judge creation without opening the schema.

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 a prerequisite ('Needs the organizer key') but no when-to-use or when-not-to-use guidance against alternatives. Usage is implied by the verb rather than stated, so it clears the minimum bar but leaves routing to inference.

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 declare this is a non-readOnly, idempotent, non-destructive mutation; the description goes well beyond that by disclosing the downstream side effect (all scores recompute), the timing allowance (after people have answered), the auth need (organizer key), and a hard constraint on nulling questions. It does this without contradicting the hints.

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-loads purpose, then body format, then semantics and guards in a tight sequence with no filler. The only waste is restating the title verbatim in the first clause, which duplicates structured data.

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 no-output-schema mutation with a nested free-form parameter, the description covers format, side effects, guards, and auth. It stops short of saying whether an update merges with or replaces the existing key, and how invalid or unscored keys are reported back.

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 only 50% and the answers object is a free-form map with no schema description at all, so the description carries the full burden — and does: answer-key format per question type (index, index list, accepted-text list), yes/no encoding (1=yes, 0=no), matching normalization (case/accents/punctuation ignored), and the meaning of null. That is everything an agent needs to construct the nested object.

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 ('Fix a quiz's answer key') and immediately names the consequence ('every score updates'), so the agent knows this rewrites scoring configuration rather than responses or settings. This is clearly distinguishable from siblings like update_settings, add_entries, and add_judge.

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 a real usage precondition — 'allowed after people have answered' — which is exactly the fact an agent needs to know it can be called late in a campaign's life. It also states the guard ('At least one question must stay scored') and the auth requirement, but never names an alternative tool or an explicit when-not-to-use case.

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: accepted formats (JPEG, PNG, WebP), a 3 MB size cap, that hidden metadata (GPS, camera) is stripped, that any existing photo is replaced, and that an organizer key is required. These are non-obvious behaviors an agent could not infer from the schema alone.

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 action, then packs format limits, metadata handling, replacement semantics, and auth requirement with zero filler. Every clause earns its place.

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 3-param mutation with no output schema, the description supplies formats, size limit, metadata stripping, replacement behavior, and auth. The only unmet piece is what happens on success/failure (e.g., error on oversized or non-https URL already implied), a minor gap for a setter.

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 only 33% (only 'entry' is described). The description compensates meaningfully by constraining photo_url (https, JPEG/PNG/WebP, up to 3 MB), which the schema only weakly hints at with a ^https:// pattern and maxLength. It does not restate slug or entry semantics, so it is helpful but not exhaustive.

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 ('Give an entry (or hunt checkpoint) a photo') with the source (public https image URL). No sibling tool touches photos, so it is trivially distinguishable from add_entries, set_questions, update_settings, etc.

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?

Provides the operative context: the photo must come from a public https URL, and the tool 'Needs the organizer key', which is a real prerequisite. It also notes replacement behavior, so an agent knows this is an overwrite rather than an add. It stops short of explicit when-not guidance, but there is no competing sibling for this action.

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?

Adds real context beyond the annotations: the whole list is replaced rather than merged, the organizer key is required, a 409 is returned once anyone has answered, and sending a question's id preserves its picture. Only minor gaps remain, e.g. whether repeated calls re-create ids, which is partly implied by idempotentHint=true.

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?

Dense but front-loaded: the scope constraint and replacement semantics come before the field reference. The opening repeats the title verbatim and the middle is a run-on field dump, but essentially every sentence carries operational information.

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-parameter, fully-replacing mutation with no output schema, the description covers input grammar, auth, ordering, limits, and the 409 failure path. It does not state what the call returns (e.g. whether newly assigned question ids come back), which is the main remaining unknown.

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 ~50% and the description more than compensates: it enumerates each question field (type, prompt length, required, options, max, answer, id), defines all seven type values and their option counts, and specifies answer-key formats per type including the yesno 1/0 convention. This is substantially richer than the schema's bare enums.

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 (replace the questions of a survey/quiz) plus a hard scope qualifier ('only until the first response'). The agent can distinguish this from set_answer_key and update_settings without opening any schema.

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 and failure mode: works only until the first response, otherwise refused with 409, and setAnswerKey is named as the path for fixing the answer key afterwards. It stops short of routing an agent that wants to append or edit individual questions, but the when/when-not is clear.

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=false, idempotent=true, and destructive=false. The description adds the auth requirement (organizer key) and clarifies the voting toggle behavior, which is genuinely useful beyond the annotations. However it does not say what a settings change affects, whether changes are reversible, or how partial updates behave across the 14 parameters.

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?

It is very short and front-loads the purpose, but the run-on 'voting Needs the organizer key' (missing punctuation) reads as a structure defect. Content is minimal rather than tight, so it is barely 'appropriately sized' for a 14-parameter tool.

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 14-parameter mutation tool with 43% schema coverage and no output schema, the description is far too thin. It names the auth prerequisite and the voting toggle but leaves the bulk of configurable settings undocumented, so an agent lacks enough to invoke it confidently.

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 only 43% across 14 parameters, so the description must carry more of the semantic load, yet it adds almost nothing. 'end / reopen voting' loosely maps to the closed parameter, but fields like ipLimit, results, opensAt, closesAt, allowChange, and requireBallot remain unexplained in both the schema and 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 specific verb and resource ('Change settings') plus a distinct capability ('end / reopen voting'), so an agent can tell it is the generic settings-mutation tool. It does not explicitly differentiate itself from siblings like set_questions or set_answer_key, which also mutate contest state, so it falls short of 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?

Provides a critical prerequisite ('Needs the organizer key') but gives no when-to-use vs when-not guidance and names no alternatives. Usage is only implied by the generic 'settings' scope. Adequate but with clear gaps.

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