Riddle Quiz Maker

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

Beyond the readOnly/idempotent annotations it adds real behavioral context: 'Reads the stored records only - contacts neither Google nor any webhook,' which tells the agent it is a pure local read and cannot diagnose connectivity. It also discloses that a Google Sheet can only be connected in the Creator, a constraint the annotations cannot express.

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 the purpose, then layers the return shape and two practical constraints in four tight sentences. The inline object notation is slightly dense but earns its place because there is no 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?

With no output schema, the description compensates by naming the returned fields, and it covers the publish-integration workflow and the empty-list case. Nothing an agent needs to call this correctly or interpret the result 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 both parameters (type enum, projectId with default) are already documented in the schema, so the description's mention of googlesheets/webhook filtering is largely redundant. Baseline 3 applies since 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?

States a specific verb and resource ('Lists the Google Sheets and webhook integrations of a project') and even sketches the returned item shape and fields. An agent can tell immediately this is the read path for integration records, not a create/connect operation.

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?

Explains the downstream purpose — the returned 'name' is what a build takes as publish.integrations.googlesheets/.webhook — and gives a concrete fallback when the list is empty (ask the user to add the Sheet in the Creator). It also flags the publishing precondition for FileUpload riddles, though it never states an explicit when-not-to-use condition.

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 destructive/not-idempotent annotations, the description adds substantial context: no undo, ids are not reused, dangling references stop resolving, refusals name the Riddles that block deletion, 'unused' is account-wide rather than per-Riddle, and a permission restriction limiting non-full-access callers to the AI Uploads folder.

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 action and permanence come first, then prerequisites, then the alternative workflow, then the return shape. It is a long single paragraph, but nearly every clause carries decision-relevant 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 destructive tool with no output schema, the description supplies the return shape ({deleted, mediaId, name, type, size}), the failure mode when the file is still in use, and the permission caveat. An agent has everything needed to call it safely or route elsewhere.

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 already documents both mediaId and project, including that a mediaId only resolves in its project. The description adds little parameter-specific detail beyond the account-wide framing, so it sits at the baseline.

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 ('Deletes a file from the media library permanently') and scopes it as cleanup of an unwanted or erroneous upload. It is clearly distinguishable from media_upload_link and from riddle_delete, which act on different resources.

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 explicit when-to-use cases (wrong upload, file no longer wanted), the prerequisite (file must be unused), and the exact alternative workflow when the file is in use: remove it via riddle_builder_update, then riddle_publish, then delete. It also warns to ask the user before calling.

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 say not-read-only, open-world, not-idempotent; the description adds the whole operational contract: 5-minute expiry, death on first use, 20-per-account-per-5-minutes rate limit, network allowlisting, and the file's eventual placement in the "AI Uploads" folder counting against storage. It also explains the download-twice failure mode and how media_delete reverses the effect, all consistent with 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?

Front-loaded with the purpose and the key constraint, and nearly every sentence carries operational information (the curl example, the mediaId-only warning). It is a dense single block that would scan faster as short bullets, which is the only thing keeping it off a 5.

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?

Even without an output schema, the description enumerates both response shapes ({uploadUrl, expiresAt, singleUse, maxBytes, allowedTypes, project, usage, requiresNetworkAccessTo} and {mediaId, type, width, height, size, folderId, project}) and the downstream usage of mediaId. Nothing an agent needs in order to call this safely 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?

The single "project" parameter already has 100% schema coverage, including the note that a mediaId only resolves in its own project. The description restates this ("Pass the project you will build in", "build in the same one") but adds no syntax, defaults, or edge cases beyond the schema, so baseline 3 is right.

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 and resource: "Creates a single-use link for uploading ONE media file into the media library." It also makes a scope distinction the sibling media_delete does not share, and the ONE/upload semantics are stated up front.

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?

Explicit when-to-use ("Call it when the user has a LOCAL file for a Riddle") and why-not alternatives ("this server cannot receive bytes, so the upload is yours"). It also gives ordering rules: check the file before minting, create one link immediately before each upload, batch one file at a time, and do not retry on network block.

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=false, but the description adds substantial beyond-schema behavior: values are stored as an override on one Riddle only, built-in 'default:*' palettes are duplicated into a Riddle-owned copy, newPaletteName always operates on a copy, and modifiedAt/modifiedBy are not stamped. The only minor gap is it never explains what makes the call destructive or how overwriting an existing override behaves.

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 and scope before the caveats, and no sentence is filler. It is on the long side, with the modifiedAt/drift detection paragraph dense enough that a shorter pointer to the concepts reference might have served.

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, nested-object mutation with no output schema, the description covers access prerequisites, copy/override semantics, the publish step, and change-detection signals — everything an agent needs to call it correctly and verify the result.

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 already 100%, so the baseline is 3, but the description earns extra: it explains that 'values' is a path=>value map with examples and that paths must come from the palette fields reference, and clarifies that newPaletteName applies changes to a copy leaving the original untouched. Minor omissions remain, e.g. how the 'select' flag interacts with an inherited preset.

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 ('Changes the palette ... of ONE Riddle') plus the fields it covers and the path=>value input shape. The scope contrast with siblings is explicit: it modifies a single Riddle while palette_get only reads, so an agent can route 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?

Gives concrete when-to-use context and prerequisites: paths come from palette_get or riddle://reference/palette/fields, a following riddle_publish is required for the change to reach the live embed, and the call is only valid when origin.writableByThisKey is true. It also tells the agent which detection signal to poll (context.modified.hasChanges) and warns that context.preset.drifted is unreliable alone.

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 readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real context the annotations don't: the response can run to thousands of tokens (~30 values per palette plus unrelated account presets), and omitted keys are echoed under omittedFields so a missing key never means absence. Strong disclosure, though it does not mention pagination or caching.

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 read, then the size warning and the omit mechanics, then the single-palette shortcut. Efficient and purposeful, though it restates some of the omit semantics already present in the schema and runs long enough to be dense for a 4-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?

With no output schema and 4 parameters, the description carries the burden and does so: it describes the shape of the response, the fields worth dropping, the size risk, and the path to a minimal read. Nothing needed to call it correctly 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%, so the baseline is 3, but the description goes further by explaining how the parameters interact as a workflow (omit paletteValues → list by uuid/name → feed paletteUUID), which the schema documents only in isolation. It does not add format or syntax detail beyond the schema for the individual 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 ('Reads the palettes ... of a Riddle') and enumerates exactly what comes back: all usable palettes including inherited account/project presets, the selected one, overridden values, and built-ins. An agent can distinguish it from palette_customize (write) 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?

Gives explicit routing: use omit:["paletteValues"] to find WHICH palette you want, then paletteUUID to read it in full, and selectedPaletteUuid to read just the design in effect. It also names the field reference doc for value semantics. Nothing about when to pick which mode is left implicit.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value beyond them by stating that a call exercises authentication as well as connectivity, which is the non-obvious behavioral property of this endpoint. An output schema exists, so return format needn't be explained.

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, front-loaded with the behavior and followed by the use case. The opening "A simple tool that" is minor padding but does not obscure the payload.

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 parameterless health-check tool with full annotations and an output schema, the description covers everything an agent needs: what it returns and what calling it verifies. No gap remains that would cause a misinvocation.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Nothing in the description contradicts the empty 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 behavior (returns "Pong") and resource (the MCP connection), which is unambiguous and unlike any sibling tool in the list. The only weak point is the filler phrase "A simple tool" at the start, but the operative clause is precise.

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?

Explicitly says when to use it: to test connectivity and authentication to the MCP. Clear usage context with no ambiguity; no exclusion clauses are needed because no sibling competes for this job.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new scope information: the large nested default-settings tree is deliberately excluded and lives in another tool, which prevents a wrong-tool call. It stops short of describing the permission matrix shape or failure modes for a bad id.

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, front-loaded with the payload description, then id sourcing, then the exclusion. No filler, and the negative scoping is stated rather than left to inference.

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 compensates by naming the returned fields. For a one-parameter read tool with full annotation coverage, nothing needed to call it correctly 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% with a single documented projectId, so the baseline is 3. The description adds provenance for that id (project_list or riddle_get's team), which tells the agent how to obtain a valid value rather than just its type.

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 (returns one project by id) with the returned fields enumerated (id, name, image, permission matrix). It explicitly distinguishes itself from the sibling project_get_settings by stating what is NOT included.

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?

States where the required id comes from ('project_list or the "team" of riddle_get') and routes the agent to project_get_settings when the default Riddle settings tree is actually wanted. Both the when and the when-not are explicit, with named alternatives.

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 cover only the safety profile (readOnly, idempotent, non-destructive); the description goes well beyond them by disclosing exclusions (never-published drafts, disabled areas), the internal _ids stripping, and the shape guarantee that both fields are always objects and an empty project yields {} rather than an empty list. This is exactly the non-obvious behavioral context annotations cannot carry.

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 purpose, and every clause is substantive (scope, exclusions, shape guarantees, sibling pointer). It is dense and long-winded in places, with parenthetical enumerations that could be trimmed, but 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?

With no output schema, the description carries the full burden of describing return values, and it does: field names, keying scheme, empty-case behavior, and what is deliberately omitted. An agent has everything needed to call and interpret it.

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 a single required parameter at 100% schema description coverage, so the schema already fully documents 'projectId'. The description adds no syntax or format detail beyond it, only content of the response, 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?

States a specific verb and resource ('Returns the default Riddle settings every new Riddle of the project starts from') and immediately scopes it to PUBLISHED/ENABLED content. An agent can distinguish it from project_get and riddle_get 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?

Explicitly tells the agent when to call it ('Read it to know what a project forces onto its Riddles before creating or editing one there') and names the cheaper alternative for a different need ('project_get is the cheap call for name, image and permissions'). It also states what it is not for (inspecting unpublished or disabled defaults).

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the paging envelope shape, 25-per-page/100-max limits, that a project API token only returns its own project, and that invalid page/pageSize is rejected rather than clamped. These are behaviorally meaningful traits the annotations do not convey.

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 the verb and resource, then layers in paging, entry shape, alternatives, and validation in a logical order. It is dense and slightly overloaded with the reference URI and parentheticals, but nearly every clause carries useful 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?

With no output schema, the description carries the burden of describing returns and does so fully: envelope fields, per-page counts, and entry fields (id, name, image). It also covers the token-scope edge case and parameter validation, leaving nothing an agent needs in order to call it 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 coverage is 100%, so both parameters are already fully documented in the schema, including the rejection-not-clamping rule. The description reinforces the same paging defaults and validation semantics rather than adding new meaning, 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 (Lists) and resource (projects) with an explicit scope qualifier (\"this token has access to\"). It names and differentiates the two sibling tools that operate on a single project (project_get adds permissions, project_get_settings adds default settings), so an agent can distinguish it 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 clear selection context: use project_list to page through many projects, use project_get/project_get_settings when you need one project's permissions or settings. It also notes the project-token scope limitation. No explicit when-not, but the routing to alternatives is unambiguous.

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, destructive=false, idempotent=false, and openWorld=false. The description adds important behavior beyond that: the bank starts empty, its type is fixed for life, it can only be referenced by matching Riddles in the same project, and full access is required.

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 but front-loaded: the first sentence states the core action, and the remaining sentences each add a needed constraint or workflow step. Nothing appears superfluous for a creation tool with cross-entity references.

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 still explains the key return value (the new bank's id) and how to use it in later calls. Annotations cover safety hints, and the description covers lifecycle, project scoping, type matching, and access requirements, leaving no material gap for correct invocation.

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 all three parameters are already documented in the input schema, and the description largely restates the projectId and riddleType semantics rather than adding parameter-level detail. It does reinforce the projectId omission behavior and the cross-type reference restriction, but title semantics are left entirely to 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 ("Creates a new, empty question bank") and names the required Riddle type, clearly distinguishing it from sibling mutation tools like question_bank_item_add and question_bank_rename. An agent can identify the tool's job 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?

Gives an explicit workflow: create the bank, add items with question_bank_item_add, then reference the returned id as questionBankId on a riddle_builder_create call. It also spells out selection constraints — matching Riddle type and matching project — so alternatives and prerequisites are 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 destructiveHint=true and idempotentHint=false, so the safety bar is partly covered — but the description goes well beyond: tag cleanup semantics matching question_bank_tag_remove, the counterintuitive DRAFT-vs-published-version reference counting (a block removed from a draft still holds the bank until republish), irreversibility ("no trash and no restore"), and the access requirement. These are non-obvious behaviors an agent cannot infer from structured fields.

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 verb and blast radius, then layered with constraints; nearly every clause carries operational weight (error code, permanence, template rule, doc pointer). It is dense in a way that suits a destructive tool, though the DRAFT/republish parenthetical is long enough to slightly slow scanning.

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?

No output schema exists, so the description must carry the full burden — and it does: what is destroyed, what is cleaned up, what blocks it, what is permanent, what requires elevated access, and where to read more. Nothing material for a correct, safe 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?

Only one parameter (questionBankId) with 100% schema description coverage, so the schema fully documents it. The description adds no format, ID-source, or validation detail beyond it. Baseline 3 is appropriate when the schema does the work and nothing extra is offered.

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 ("Deletes a question bank") plus the cascade scope ("every item it holds"), and explicitly contrasts with the nearest sibling: "one item alone is question_bank_item_delete". An agent can distinguish this from question_bank_discard_changes, question_bank_item_delete, and riddle_delete without opening a 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 concrete when-not conditions with the exact rejection code (QUESTION_BANK_INTERDEPENDENCY) and an alternative path for templates ("a template is copied with question_bank_duplicate, never deleted"). It also points to a specific reference doc section to read before deleting, which is exactly the routing guidance an agent needs for a destructive operation.

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 destructiveHint=true: it discloses no undo, no copy of the discarded draft, that pending item deletes are resurrected while newly added items are untouched, that only items (not title/notes metadata) are affected, and the access requirement. These are exactly the non-obvious consequences an agent cannot get from 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?

Front-loaded with the destructive action and its irreversibility, then caveats, then scope limits, then alternatives. Dense but every sentence carries distinct semantic content (undo absence, item-delete resurrection, added-item exception, metadata exemption, access rule) 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 single-param, idempotent-false destructive mutation with no output schema, the description covers blast radius, irreversibility, edge cases, preconditions, and safer alternatives. Nothing an agent needs to call it safely 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?

There is a single parameter with 100% schema description coverage, so the schema already defines questionBankId. The description adds no format, range, or sourcing guidance for the id beyond what the schema states, 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 and resource with exact scope: discards every unpublished change to a question bank's items, resetting them to last published content. It explicitly distinguishes itself from question_bank_publish and from a general 'restore the bank' operation, so an agent can tell it apart from siblings without opening schemas.

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?

Names concrete alternatives and the conditions that select them: read draft via question_bank_get_items vs published: true to compare sides, and 'prefer question_bank_publish whenever the draft is what should survive.' It also states an exclusion (rejected for public template ids) and an access prerequisite, leaving nothing 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?

Beyond annotations (readOnly=false, idempotent=false, destructive=false), it discloses that the source is untouched, copies are fully independent, a template id is accepted only here, and full access is required with a reference link. This is meaningful context annotations don't provide.

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 the core copy behavior and independence guarantee before the template/permission notes. Dense but every sentence carries distinct information; slightly crowded by the access reference link.

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-destructive write with no output schema, the description covers result semantics (new independent bank, source preserved), the project fallback, and the access requirement—everything needed to invoke 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 coverage is 100%, so baseline is 3; the description adds that projectId falls back to the key's project and that questionBankId may be a template id, reinforcing schema meaning without contradiction. Adds modest value over 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 (copies) and resource (question bank + items) with the key property that the copy is independent and the source untouched. Clearly distinguishable from siblings like question_bank_rename, publish, or discard_changes.

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?

Explicitly tells the agent this is the accepted route for a public template id and the way to edit a template (duplicate then edit the copy). This reserves the tool for a named scenario and directs away from trying other mutations.

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, yet the description adds substantial behavioral context beyond them: a template reads back without owner/tags/notes and belongs to nobody, and the draft-vs-published discrepancy between 'categories' and 'blockTypeCategoryMap' is explained. This is exactly the kind of nuance structured fields cannot carry.

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 the core retrieval statement and what's returned, then tacks on the template and categories caveats. It is somewhat dense with quoted field names, but each sentence conveys distinct, non-redundant 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?

No output schema exists, and the description compensates by naming the returned fields, clarifying the exclusion of items, and explaining the two category representations. An agent has everything needed to call it and interpret the result 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 coverage is 100% and the single parameter's description already explains it comes from question_bank_create/list or a template. The description reinforces the template-id case but adds no syntax or format detail the schema lacks, 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 and resource ('Retrieves one question bank by id') and enumerates exactly what is returned: title, riddleType, tags, notes, categories/blockTypes, unpublished-changes flag. It explicitly disambiguates from the sibling question_bank_get_items, so an agent can distinguish the two without opening schemas.

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 concrete usage scenario: call on a built-in template id obtained from question_bank_list(scope: "templates") to inspect contents before duplicating. That covers the primary when-to-use, though it doesn't spell out exclusions or the full set of sibling alternatives (e.g., when to prefer question_bank_list).

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that published items are a different set and the pool a live Riddle actually draws from, gives the response envelope shape, and warns that some response fields are intentionally omitted (pointing to a reference doc). It stops short of full detail on the omission semantics itself.

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?

Purpose and the draft/published distinction are front-loaded, and every clause carries information (filters, template preview, pagination shape, reference pointer). It is dense and em-dash-heavy in one block, which slightly hurts scannability, but there is little waste.

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 an 8-parameter read tool with no output schema, the description supplies the response envelope and routing to a reference resource for item shape and omissions, plus the counting recipe. The main residual gap is that the item shape and 'what the response leaves out' are deferred entirely to an external URI the agent may not resolve.

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 meaning the schema does not: the filters are 'the same filters a QuestionBank block draws with', a template id is a valid questionBankId, and it documents a non-obvious counting pattern (blockType/category/difficultyRange with pageSize: 1, then read 'total'). That is genuine semantics beyond the field docs.

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 ('Lists the items of a question bank') and immediately distinguishes the two content sets it can return (draft vs published). An agent can tell this apart from siblings like question_bank_get and question_bank_item 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?

Explicitly covers when to use the default (draft content), when to switch (published: true), and names an alternative workflow ('a template id from question_bank_list(scope: "templates") reads too - that is how to preview its questions before duplicating it'). It also explains what the filters mirror, so the agent knows the intended 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?

Annotations cover safety (readOnly=false, destructive=false, idempotent=false) but not lifecycle; the description supplies that the item lands in DRAFT, that question_bank_publish is required before a QuestionBank block draws it, that 'hasChanges' reports unpublished state, and that full access is required. It even disambiguates that blockTypeColumns is a document, not a tool - a real trap for an agent.

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 and sibling disambiguation, then prerequisites, then behavior. Dense and mostly waste-free, though the parenthetical about blockTypeColumns being a document and the response-field aside make it slightly longer than strictly needed.

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 mutation tool with no output schema, the description covers lifecycle (draft vs published), the response field an agent should check, permission requirements, rejection cases, and the schema-discovery prerequisite. Nothing essential to calling it correctly 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%, so the baseline is 3 and the nested 'columns' shape is already documented in detail. The description contributes beyond the schema by warning that there is no universal item shape and pointing at the exact reference document that enumerates valid blockType values and their expected column names.

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 ('Adds ONE new question/item to a question bank') and immediately distinguishes itself from the two nearest siblings by naming question_bank_item_update as the replace path and question_bank_item_delete as the remove path. The 'ONE' emphasis clarifies that this is not a bulk operation.

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 explicit when-to-use routing against both alternatives, a concrete prerequisite ('read riddle://reference/question-bank/block-type-columns before the first add into a bank you have not populated'), and a hard exclusion ('Rejected for a public template id'). The access prerequisite is stated rather than 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?

The description adds substantial context beyond the destructiveHint annotation: immediate permanent deletion for unpublished items, draft-only removal for published items, live Riddle dependency until purge, restore via discard changes, no trash/restore, and access requirements. It is fully consistent with 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?

The description is dense but front-loaded and every sentence carries operational meaning. It communicates destructive consequences, related siblings, access needs, and rejection conditions without 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 mutation tool with no output schema and fully covered parameters, the description provides the critical missing behavioral context: permanence, draft semantics, dependency on publish, restore path, and access requirements.

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 both parameters are already well documented in the schema. The description reinforces that only one item is deleted but does not add syntax or format details beyond the structured parameter definitions.

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: deletes exactly one question bank item and touches nothing else. It clearly distinguishes this from sibling operations like question_bank_delete, question_bank_publish, and question_bank_discard_changes.

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 key conditional behavior for never-published versus published items and explicitly names question_bank_publish and question_bank_discard_changes as the operations that affect the item afterward. It also states access requirements and the public-template rejection condition.

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 mark the tool destructive and non-idempotent, and the description adds substantial context beyond that: omitted columns or values are deleted, blockType is immutable, changes land only in the draft, and hasChanges indicates whether unpublished changes exist. It also discloses access requirements and public-template rejection.

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 but front-loaded with the core replace-not-merge behavior, then covers prerequisites, immutability, draft workflow, and access constraints. Every sentence contributes operational detail without redundant 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 destructive mutation tool with no output schema, the description is complete enough: it explains replacement semantics, required fields, draft visibility, publish/discard lifecycle, immutable blockType, response hasChanges, access needs, and template restrictions.

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 carries most parameter meaning. The description still adds useful semantics by emphasizing that all four content fields must be sent even when unchanged, that omitted values are removed, and that value ids must be preserved to edit existing values rather than replace them.

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: it replaces the content of ONE existing question bank item entirely, and explicitly says this is not a merge. It distinguishes the operation from alternatives such as question_bank_item_delete plus question_bank_item_add when blockType must change.

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 instructions: read with question_bank_get_items first, send back every field and value id, use question_bank_publish to make changes live, and use question_bank_discard_changes to throw away unpublished changes. It also names the alternative workflow for immutable blockType changes and notes rejection for public template ids.

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?

Although annotations already declare a safe read-only and idempotent operation, the description adds important behavior: pagination shape, template-specific itemCount versus draftItemCount semantics, and the rule that every write rejects a template id. Those details materially affect how an agent interprets and uses the results.

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 distinction between own and template scopes, and most sentences carry useful caveats. It is dense and somewhat long for a list tool, with some repetition of schema-level scope and projectId behavior, but not enough to obscure the key guidance.

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 must explain return shape; it does so by naming pagination fields, template-specific fields, null blockTypes behavior, and category examples. It also covers the critical template caveat and pre-duplication verification flow, making it complete for correct invocation.

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 parameter basics are already documented. The description adds cross-parameter context, especially that templates take only riddleType and are not pageable or searchable, but it largely restates the scope and projectId semantics 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?

The description states a specific verb and resource ("Lists question banks") and immediately distinguishes the two listing scopes, own project banks versus built-in templates. It also names the related duplication and read tools, so an agent can understand its role without opening sibling schemas.

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 explicit selection rules: use scope "own" for a project's banks, pass projectId to inspect another project, omit it for the key-scoped project, and use scope "templates" for starter banks. It also routes the agent to question_bank_get, question_bank_get_items, and question_bank_duplicate before copying a template.

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=false, but the description adds substantive context beyond them: previously published content is overwritten, a pending item delete is purged permanently, and every Riddle using the bank is republished even when nothing changed. It also discloses auth requirements (full access, with a reference path) and the public-template rejection, which no annotation conveys.

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 and what changes at view time, then layers consequences, the alternative, and prerequisites. It is dense and mostly waste-free, though the run-on first sentence and the access-reference tail could be tightened.

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 destructive mutation with no output schema, the description covers consequences (overwrite, purge), scope of side effects (all Riddles using the bank), pre-flight verification, auth requirements, and failure conditions. Nothing an agent needs to invoke it safely 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?

There is a single parameter with 100% schema description coverage, so the schema fully documents questionBankId. The description adds no format or syntax detail about the ID itself; per the high-coverage baseline, 3 is appropriate.

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 ('Makes every item's draft content its published content') and immediately grounds it in the domain ('what a QuestionBank block of a live Riddle actually draws at view time'). It also names the opposite operation, question_bank_discard_changes, so the agent can distinguish it from the sibling 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?

Explicit when-to-use guidance: 'Read question_bank_get_items with and without published: true first when unsure what will change.' It also gives exclusion conditions ('Rejected for a public template id') and points at the inverse sibling, which covers when-not-to-use.

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 the change is immediate and permanent, is untouched by publishing or discarding, never counts as an unpublished change, and fails on public template ids. It also names the authorization requirement and points at the access reference. That is exactly the kind of side-effect and permission context an agent cannot infer from destructiveHint/idempotentHint 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?

Front-loaded with the core action in the first sentence, then the side-effect, then the failure/authorization constraints. Efficient overall, though the capitalized "AND permanently" emphasis and the run-on middle sentence are slightly noisier than needed.

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, non-open-world mutation with full schema coverage and annotations declaring the safety profile, this covers side effects, permissions, and the main rejection case. Only the return behavior and behavior on a nonexistent id are left unstated, which is minor since 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 100%, so the baseline is 3, but the description adds real meaning to the `title` parameter by classifying it as metadata rather than DRAFT content and spelling out the consequences of that classification. `questionBankId` gains only the implicit constraint that public template ids are rejected.

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 ("Sets the title of a question bank") and immediately differentiates itself from the publishing/draft workflow siblings by explaining that the title is metadata rather than DRAFT content. An agent can distinguish this from question_bank_publish, question_bank_discard_changes, and question_bank_update_notes 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 two concrete preconditions that select or block use: it is "Rejected for a public template id" and "Needs full access" with a reference pointer. It does not explicitly contrast with nearby siblings such as question_bank_create or question_bank_duplicate, but the context is clear enough to place the call correctly.

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 idempotentHint=true and destructiveHint=false, so the bar is lower, yet the description still adds genuine context: reuse-or-create semantics, 're-tagging changes nothing', rejection on public templates, and the 'Needs full access' auth requirement with a reference link. No contradictions with 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?

Front-loaded with the action and the exclusivity constraint, and every sentence carries information. Slightly long in the middle where the one-set-per-project explanation is repeated ('which is why the ids come from riddle_tag_list').

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-parameter mutation with no output schema, the description covers the mutation profile, idempotency, error conditions (public template), and auth requirements. What it returns is implicit but low-risk given the idempotent, additive nature.

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; the description earns above that by restating the oneOf constraint and explaining create-if-absent behavior for tagName. It does not spell out format/ID expectations for questionBankId, keeping it just shy of 5.

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: 'Adds a tag to a question bank', and immediately distinguishes itself from the closely-named siblings riddle_tag_add and question_bank_tag_remove. An agent can select it 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?

Explicit when-to-use and how: 'exactly one of the two' (tagName or tagId), ids sourced from riddle_tag_list, removal routed to question_bank_tag_remove. It also names an exclusion ('Rejected for a public template id') and the access prerequisite.

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?

Despite annotations already flagging destructiveHint=true, the description adds non-obvious cascade semantics: an orphaned tag is deleted from the project only if neither banks nor Riddles use it, and bank deletion cleans up the same way. It also discloses that a missing tag is an error rather than a create, and the full-access prerequisite.

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 action and packs a lot of high-value edge-case detail into tight sentences. The cascade explanation is dense but each clause carries distinct behavioral information; slightly heavier than ideal for a three-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 destructive mutation with cascade effects and no output schema, the description covers error conditions, the exact scope of mutation, the cleanup rule, the access requirement, and the sibling tool to use for project-level deletion. Nothing needed to call it safely 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%, so the baseline is 3, but the description adds that the two identifier parameters are mutually exclusive and that tagName lookups never create. The schema already encodes the oneOf constraint, limiting the added value.

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 opens with a specific verb and resource ('Removes a tag from a question bank') and immediately clarifies the two lookup modes. It clearly distinguishes itself from riddle_tag_delete and riddle_tag_remove by scoping the effect to THIS bank.

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 states the exactly-one-of rule, points to riddle_tag_list as the source of valid values, and contrasts with riddle_tag_delete for project-wide removal. It also notes rejection for a public template id and the required access scope. It stops short of explicitly calling out riddle_tag_remove as the riddle-level alternative.

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 destructiveHint=true by disclosing that previous notes are overwritten entirely (not appended), that the change is immediate and permanent, and that it is unaffected by publishing or discarding and never counts as an unpublished change. For a non-idempotent destructive mutation, these are exactly the traits an agent needs.

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 the destructive replacement behavior in the first sentence, then adds constraints efficiently. Density is high but essentially every clause carries information, though it is close to over-packed for a two-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?

With no output schema needed, the description covers the destructive overwrite risk, permanence, interaction with draft/publish lifecycle, auth requirement, and a rejection case. Nothing an agent needs to invoke this safely 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%, so both parameters (questionBankId, notes) are already fully documented, including the replace-not-append semantics of notes. The description reinforces this but adds little parameter-level detail 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 and resource: replaces the plain-text maintainer notes of a question bank, with the scope qualifier that notes are never shown to participants. An agent can immediately distinguish this from question_bank_get, question_bank_rename, or question_bank_item_update.

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?

Explicitly instructs reading notes with question_bank_get first and sending the full desired content, and states a hard exclusion: rejected for a public template id. It also names the access prerequisite with a reference path.

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 (readOnly, idempotent, non-destructive, closed-world) are fully consistent, and the description adds behavior they don't cover: documents are long and cost real context (~20 KB unscoped block-types vs ~5.5 KB scoped), filters are silently ignored on topics with no per-type split ('whole document returned, stated in the response'), and the availableTopics catalogue is delivered once per session (~2.5 KB) unless overridden. This is exactly the context an agent needs to avoid blowing its window.

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?

Purpose is front-loaded in the first clause, and the sizing advice plus the scoping workflow are genuinely load-bearing. The closing paragraph is dense and slightly tangled (the riddleType/blockTypes/filtering interplay in one block), costing some readability, but 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?

For a documentation-fetch tool with an output schema and full annotation coverage, nothing an agent needs is missing: it knows what the tool returns, how large it will be, how to scope it, and when to reach for it versus guessing or retrying a failed 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 coverage is 100% and the topics enum already enumerates every document, so the baseline is 3. The description nevertheless adds cross-parameter semantics the schema does not spell out as clearly — that block-types is never returned unscoped and must be narrowed via blockTypes, that fieldTypes covers both form-field-types and form-field-defaults in one read, and that the per-entity families need no filter because the address itself is the filter.

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 this server's own documentation' — and immediately enumerates what the documents contain (block types, form field types, result blocks, palette values, response shapes). It explicitly frames itself as the authoritative parameter reference for the riddle_builder_* and palette_* siblings, so an agent can tell it apart from every other tool in the list without opening a 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 concrete when-to-use rules: read the relevant topic BEFORE the first call rather than guessing property names, and re-read it on a VALIDATION_ERROR. It also routes by situation — read the index when you don't know which topic you need, getting-started when unsure which tool to use, a prompts/* playbook when the user states a GOAL rather than an operation — and warns to pass only the topics actually needed because most are long.

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 this is a non-read-only, non-idempotent, open-world creation operation, so the safety profile is covered. The description adds useful behavior beyond that: the compact return envelope, the 'queued': true marker when queue is set, and where the view URL appears before and after publishing. It does not cover authorization or rate-limit behavior, but the added return and publishing context is substantial.

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 purpose, then alternatives, then return behavior, which suits a complex nine-type builder. It is dense and long, but most of the length is justified by type-specific creation semantics and cross-references. Some sentences are verbose, so it is not maximally concise.

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 complex creation tool with nine Riddle types, nested configuration, and no output schema, the description explains the return envelope and key URL locations. It also points to exhaustive references for per-type shapes, block types, and response format. Combined with a fully described input schema, an agent has enough context to invoke it 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%, and the schema itself deeply documents the parameters and nested build fields. The top-level description mainly routes the reader to the schema and external references rather than adding new per-parameter meaning beyond what is already structured. Baseline 3 is appropriate.

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 first sentence states a specific verb and resource: it builds a new Riddle from a build configuration. It also distinguishes this creation tool from riddle_builder_update and riddle_builder_validate by naming both siblings and their purposes. An agent can identify the tool without opening its 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?

The description explicitly says to use riddle_builder_update when changing an existing Riddle and riddle_builder_validate when only checking a configuration. It also clarifies the top-level publish boolean versus the stored publish configuration, reducing misuse. These are concrete when-to-use and when-not-to-use instructions.

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 flag destructiveHint=true and non-idempotent, but the description adds real behavioral depth beyond them: omitted fields are left untouched, deleting a block still referenced by CUSTOM logic is rejected unless a replacement tree or $reset is sent, conditions are replaced wholesale and re-sorted so a read-back differs from what was sent, and results replaces all pages. It also states the permission prerequisite and the return envelope.

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 merge-vs-rebuild distinction, then the block grammar, then preconditions and return shape, so the most decision-relevant information comes first. It is dense but mostly earns its length; the grammar recap overlaps with the per-parameter schema descriptions.

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, deeply nested mutation with no output schema, the description supplies the missing pieces: the return envelope, the read-before-edit workflow, the access precondition, and the classes of rejected edits. Nothing an agent needs to invoke it correctly is absent.

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 baseline is 3, but the description adds the crucial cross-reference that the "build" object is exactly the shape riddle_get returns under "build" and riddle_builder_create accepts, which tells the agent how to construct an undocumented nested payload. The $create/$delete/$blocksOrder grammar is largely restated from the schema, keeping it below a 5.

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 ("Edits an existing Riddle of any type") and immediately distinguishes itself from riddle_builder_create by framing the operation as "a merge, not a rebuild". An agent can tell the difference between this and the create sibling without reading 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?

Explicitly directs to read the Riddle with riddle_get first to obtain the build shape and block IDs, warns "send only what you mean to change," and routes publish-only intent to riddle_publish instead. It also names a precondition (origin.writableByThisKey via riddle_get/riddle_list), so when-not-to-use is covered.

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, but the description adds non-obvious behavior beyond them: a deep-copied scratch Riddle is discarded, nothing is persisted or published, no event is dispatched, and one genuine side effect (a live HEAD request per media URL) is disclosed — consistent with openWorldHint. It also bounds the tool honestly by naming what it cannot catch (flush/publish-time DB constraints, queue-worker behaviour).

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 capability and the discard semantics are front-loaded, and every sentence carries real information. However, it is a single dense paragraph with no visual structure, and the "project" caveat is repeated almost verbatim between description and 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 two-parameter, no-output-schema tool this is thorough: it names the return envelope keys ({validate, valid, summary, items}), the ordering guarantee, the 1–20 batching, and points to riddle://reference/riddle-builder/riddle-types for per-type build shapes. An agent has enough to call it and interpret the result.

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 both parameters already carry detailed descriptions, including the project-scope false-negative warning and the edit-entry origin gate. The description largely restates that same material, adding little syntax or format detail beyond the schema, 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?

States a specific verb and scope: "Dry-runs one or many Riddle Builder creates and/or edits without creating or changing anything". This immediately distinguishes it from riddle_builder_create and riddle_builder_update, whose payloads it mirrors.

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 explicit when-to-use guidance: "Use it to see why a config would be rejected before spending a real create/edit on it, and to pre-flight a set of similar Riddles in one call." It also states a concrete when-not/what-it-misses clause and a prerequisite-type rule (pass "project" for project-scoped references, and the origin-gate requirement for edit entries).

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 destructive annotation, it discloses nuanced behavior: bulk delete is non-atomic, does not stop early, retries dependent Riddles once, and reports per-entry errors. It also explains dryRun validation and the shape of the dry-run response, which is valuable behavioral context for a destructive tool.

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-loads the key deletion and dry-run guidance. It is longer than typical but justified by the complex bulk and retry semantics, though some reference-link phrasing could be tightened.

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?

It covers most behavior an agent needs for a destructive batch delete, including atomicity, retries, per-item errors, dry-run behavior, and access conditions. It does not describe the normal successful delete response, but the annotations and dry-run detail reduce that 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 the schema already documents UUID, UUIDs, and dryRun. The description adds useful meaning by clarifying the either/or relationship, the 100-item limit, and especially the dryRun result fields and validation 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 a specific verb and resource: deletes one or many Riddles. It clearly distinguishes UUID single deletion from UUIDs bulk deletion and references sibling tools like riddle_list and riddle_get for context.

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 explicit when-to-use guidance: pass UUID for one, UUIDs for several, and dryRun first whenever the set was not created by you. It also names riddle_list as a source for the UUIDs to bulk-clean and explains the writableByThisKey access condition.

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 a safe, idempotent read, and the description adds substantial behavior beyond them: content the config cannot express is surfaced in "warnings" rather than failing the call, bulk reads degrade to compact state with "truncated": true past a size budget, omitted sections are echoed in "omittedFields", and the three states of "published" are enumerated. This is exactly the extra context annotations cannot carry.

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 purpose and response shape are front-loaded, which is good, but the remainder is one dense run-on paragraph that largely restates the omit/omittedDefaults/UUIDs semantics already documented in the schema fields. Information-dense rather than wasteful, yet the duplication with structured fields costs it a point.

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?

Despite having no output schema, the description fully describes the returned envelope (uuid, type, modifiedAt, build, nextBlockId, warnings, published, context), explains what build versus published mean, and points to reference resources for field-by-field detail. An agent can consume and act on the result without further clarification.

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 per-parameter descriptions are already rich, so the baseline is 3. The top-level description still adds meaning the schema does not spell out as directly, notably that partial defaults are intentionally absent and must NOT be resent because presence itself enables features, and the ordering advice ("put the Riddles you need in full first").

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 opening sentence names a specific verb (Reads) and resource (one Riddle - or several, with UUIDs) and immediately specifies the response artifact: the compact build-configuration envelope. It even ties the output back to the consumer tools ("build" is exactly what the riddle_builder_* tools accept back), which lets an agent place this tool in a workflow 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?

It gives clear operational context: single UUID vs UUIDs, the max-20 bulk cap with the reason it is lower than sibling bulk tools, the incompatibility of UUIDs with includeRiddleData, and when to inflate the response (omit/omittedDefaults/includeRiddleData). What it lacks is explicit routing against the closest siblings (riddle_list for compact state, riddle_preview), so the agent must infer when this is the right read versus those.

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 the safety profile (readOnly, idempotent, non-destructive), but the description adds a genuinely useful behavioral fact not in the structured data: the code is returned even for unpublished Riddles, yet the embedded URL will not serve until publish. That caveat directly prevents a 'the embed is broken' misdiagnosis. It stops short of describing the returned markup (script vs iframe) or any rate/auth concerns.

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 tight sentences, zero padding, with the identification and the key publish-state caveat both stated up front. Every clause carries 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 single-parameter read with no output schema, the description covers the critical gotcha (unpublished Riddles) and the retrieval key. It leaves the shape of the returned code undocumented, though that is a minor gap for a string-returning lookup.

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 single UUID parameter is fully documented in the schema, so the description adds nothing beyond restating 'by its UUID'. Baseline 3 applies when the schema already does the work.

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 ('Gets') and a precise resource ('the HTML embed code for a Riddle'), which is materially narrower than riddle_get or riddle_preview. It never explicitly contrasts itself with those siblings, so an agent must infer that 'embed code' differs from previewing the Riddle.

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 by the resource name: an agent wanting markup to place on a page will pick this. There is no statement of when to prefer riddle_get or riddle_preview, and no prerequisites or 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 cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so this score reflects added value: the description discloses rejection-rather-than-ignore semantics for inapplicable filters in account scope and summarizes the pagination envelope. It does not describe auth/permission requirements beyond a passing reference in the origin parameter.

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?

Purpose and default scope are front-loaded, and the paragraph is dense with payload rather than filler. It is slightly long for a single block and could be split, but every sentence carries distinct 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 an 11-parameter, zero-required list tool with no output schema, the description supplies the response shape ({items, page, pageSize, total, hasMore}) plus the meaning of total/hasMore, and resolves the ambiguous scope/filter interactions. Nothing needed to invoke it correctly appears 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 description coverage is 100%, so the 3 baseline is already met by the schema. The description adds meaning beyond it by explaining cross-scope filter applicability — notably that projectId and notType are rejected (not ignored) under scope "account", a behavior the schema does not state.

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?

Opens with a specific verb+resource ("Returns a paginated list of Riddles") and immediately disambiguates the two listing scopes, so an agent can tell what this returns without opening the schema. It is clearly distinguishable from sibling list tools (riddle_template_list, question_bank_list) by resource.

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?

Explicitly states when to use each scope: "project" (default) for a single project, "account" for the personal project plus every accessible team project. It also names the key condition that changes behavior (projectId omitted = API-key-scoped project) and states that projectId/notType are rejected in account scope.

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 annotations, the description discloses important behavioral traits: check mode changes nothing, move mode is atomic and validates the whole set first, moves drop project-specific ad blocks and update the published version, and the new project's design is not adopted. It also clarifies the access prerequisite via origin.writableByThisKey and references access documentation.

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 long, but the length is justified by the tool's complexity and the importance of atomicity and check-mode semantics. It is generally front-loaded with the core move/check distinction, though the single-paragraph structure makes some details harder to scan than necessary.

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, and the description compensates by naming the check-mode response fields and the move-mode response shape. Given the complex atomic bulk behavior, the description is complete enough for an agent to invoke the tool correctly and interpret the likely results.

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?

Although the schema coverage is 100%, the description adds substantial meaning beyond the schema: omitting projectId triggers check mode, dryRun is pointless without projectId, projectId may come from project_list or be the literal "personal", and UUIDs for a move must represent the complete set that moves together. These are operational semantics not fully conveyed by the structured fields 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?

The description states a specific verb and resource (move Riddles into another project or personal project) and clearly distinguishes the two operational modes: check mode and move mode. It also differentiates this tool's atomic bulk behavior from other bulk tools, which helps an agent select it correctly among 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?

The description gives explicit when-to-use guidance: run check mode first whenever the Riddles were not all created by you, or to explain why a move is impossible. It also explains how to resolve blocked cases via addUUIDs and when to consult additional references.

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 cover the safe-read profile; the description adds substantially more: no mutation occurs, the draft is served from a temporary cache, the previewUrl is anonymous, it expires after previewExpiresInSeconds, and re-calling renews it. It also discloses client-dependent behavior (renders a widget in UI clients, returns a URL elsewhere), which no structured field conveys.

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 core (what it previews, when to call, when not to) is front-loaded and the sizing is justified by the amount of behavioral detail. A few clauses are redundant, notably restating 'the Riddle as it looks right now' and the trailing reference_get pointer, which mildly dilutes an otherwise dense paragraph.

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?

Return values are covered by an output schema, so the description is free of that burden, and it still explains previewUrl semantics and expiry that the agent needs to act on. Client-rendering divergence, publication state fields, and renewal behavior are all covered, so nothing an agent needs to call this correctly 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?

There is a single required parameter with 100% schema description coverage, so the schema already does the work and the baseline is 3. The description doesn't add format, sourcing, or lookup guidance for the UUID beyond referring to 'a Riddle', leaving nothing extra but nothing missing either.

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+resource ('Shows the user the current DRAFT of a Riddle as a playable preview') and immediately scopes it to the draft-vs-live distinction, which separates it from riddle_get and riddle_publish. An agent can tell exactly what this does 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?

Gives explicit triggers ('after riddle_builder_create or riddle_builder_update whenever the user wants to see the result') and an explicit anti-pattern ('do not call it on every edit of a multi-step build, once at the end is enough'). It also notes the equivalence right after riddle_publish, so the agent knows when calling is pointless.

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 mark destructiveHint=true and idempotentHint=false, but the description goes far beyond: non-atomic bulk semantics (per-entry errors, rest proceed), exact error codes (RIDDLE_PUBLISH_VALIDATE, RIDDLE_UNPUBLISH), validationWarnings appearing even on success, and the unpublish no-op message quirk. This is unusually rich behavioral 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?

Front-loads the core verb and the publish:false inversion, then layers PUBLISHING/UNPUBLISHING sections. Dense but nearly every clause is actionable; the only cost is readability from a long single block with heavy parentheticals.

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 carries the return-value burden fully: names context.viewUrl as the public URL to report, context.published state, the compact bulk envelope, validationErrors/Warnings, and the no-op 'message'. Complete for a mutating tool of this complexity.

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 real meaning: publish:false semantics, omit shrinking the single-UUID response, the UUID-vs-UUIDs response shape divergence, and the max-100 bulk cap. It meaningfully enriches parameters beyond the schema's field-level descriptions.

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?

Opens with a specific verb+resource ('Publishes one or many Riddles') and immediately clarifies the inverse mode via publish:false, noting 'there is no unpublish tool.' It distinguishes itself from siblings by name, contrasting its validation output with riddle_builder_validate and its unpublish path with riddle_delete.

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 explicit routing: use riddle_delete instead when a live Leaderboard blocks unpublish, and clarifies that riddle_builder_validate dry-runs a build config rather than a publish. States the condition (origin.writableByThisKey) under which the tool applies. Nothing 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the writability precondition and the fact that only a partial confirmation (uuid, title, modified state) comes back rather than the whole Riddle. It does not say what happens on a gate failure or whether the prior title is recoverable, which keeps 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?

Three short sentences: operation, return scope, precondition -- front-loaded and free of filler. The final sentence is telegraphically compressed ("Only if ... : riddle://reference/concepts/access"), which costs a little readability but wastes no 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 two-parameter mutation with full annotations and no output schema, the definition covers what it does, what comes back, and the permission gate. Only the failure mode when writableByThisKey is false is left unstated, a minor gap rather than a blocking one.

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 both parameters are fully documented in the structured schema. The description restates UUID and the new title but adds no format, constraint, or uniqueness semantics beyond what the schema already provides, 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?

"Renames a Riddle with the specified UUID" states a specific verb and resource, and the second sentence bounds the result to a confirmation payload. An agent can distinguish this from riddle_builder_update, riddle_move, or question_bank_rename without opening another 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?

The description gives an explicit precondition for invocation -- origin.writableByThisKey must be true -- and names riddle_get / riddle_list as the way to check, plus a reference URI for access concepts. It lacks a stated when-not or alternative path for the case where the gate fails, but the eligibility condition itself 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 this as a non-read-only, idempotent, non-destructive operation, and the description is consistent with that while adding important behavior: tag creation in each Riddle's own project, cross-project bulk calls, no publish requirement, per-item bulk error handling, and the permission gate. This is substantial context beyond what the annotations provide.

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 purpose and key constraints are front-loaded, and the density is justified by the tool's bulk and dual-parameter modes. However, it is a single packed paragraph with repeated schema details, so readability and concision could be improved with sentence breaks or less restatement.

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 carries the return-value burden; it explains that the tag and all tags of the Riddle are returned, and it describes the bulk envelope and per-entry error shape. It also covers permissions, project scoping, and idempotency, leaving little for an agent to infer.

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 useful cross-parameter meaning: tagName may create the tag in each Riddle's own project, and tagId is project-scoped and therefore only valid for that project's Riddles. Some of the parameter detail repeats the schema, so it does not quite reach the top score.

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 states a specific verb and resource: putting a tag on Riddles, with the scope constraint of one assignment per Riddle. It explicitly distinguishes itself from riddle_tag_list, riddle_tag_remove, and riddle_tag_delete, so an agent can identify its role without opening sibling schemas.

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 names the sibling alternatives and what each does, clarifies when to use UUID versus UUIDs, and explains the tagName-versus-tagId choice. It also states the writableByThisKey prerequisite, which gives the agent a concrete condition for whether the tool can be used.

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=false; the description adds genuinely new behavior: the call detaches nothing, it fails with a message naming how many riddles/question banks still carry the tag, deletion is permanent, and IDs are not reused so a stored riddle_list filter on the old id silently stops matching. It also flags the full-access requirement via riddle://reference/concepts/access.

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 destructive action and the rarity warning, and each sentence carries distinct information (alternative, failure mode, pre-check, permanence, id reuse, access). Slightly dense with ALL-CAPS emphasis and a long run-on pre-check clause, which costs a point.

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 two-parameter tool with annotations covering the safety profile and no output schema, the description covers the precondition, the failure behavior, irreversibility, id-reuse side effects, and the auth requirement. Nothing an agent needs before calling 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 description coverage is 100%, so both parameters are already documented, including the 'deleted by id, not by name' point the description repeats. The only added meaning is the gating condition (a tag is free only when count AND bankCount are 0), which is relevant but not a semantic clarification of the parameters themselves. 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 and resource ('Deletes the TAG ITSELF from a project - the label') and immediately scopes it negatively: no riddle, question bank, or assignment is affected. It explicitly contrasts with the sibling riddle_tag_remove, so an agent can distinguish 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?

Gives explicit when-to-use ('for a leftover from before that cleanup existed'), when-not-to-use (untagging the last carrier is handled by riddle_tag_remove), and a mandatory pre-check ('check with riddle_tag_list first ... and untag the carriers before calling this'). The exclusion and the alternative are both 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/closed-world, but the description adds substantial non-annotation context: unpaginated result, project-scoped tag identity ('Campaign 2026' differs across projects), and the count vs bankCount split that determines whether a tag is actually unused. This is real behavioral disclosure, not a restatement of the flags.

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?

Return shape is front-loaded, which is correct, and every sentence carries information. It is dense with parenthetical asides and the final sentence is long enough to be a small readability cost, though nothing is truly 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?

No output schema exists, yet the description supplies the exact response shape, the counting semantics, and the cross-tool relationships (riddle_tag_add, riddle_tag_delete, question_bank_tag_*). An agent can call it and interpret results without further inference.

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 baseline is 3; the description earns credit for adding semantics the schema lacks by defining that tags are scoped per project, which is why projectId matters. It doesn't restate the omit/default behavior for projectId, leaving that to 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?

Specific verb + resource ('Lists the tags of a project') plus the exact return shape {items: [{id, name, count, bankCount}]}, and it explicitly distinguishes itself from siblings riddle_list (whose 'tags' filter consumes these ids) and question_bank_tag_add/_remove.

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 explicit when-to-use: 'Read this before riddle_tag_add, which creates a tag it does not find, to tag with the name a project already has rather than a second one beside it.

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?

Far exceeds the annotations: it discloses the cascading delete of the tag itself when the last carrier is untagged, that this deletion is permanent (re-adding creates a new id), that a nonexistent tag is a per-Riddle error, that nothing is created, and how bulk partial failures are reported. These are exactly the destructive side effects an agent must know about.

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 and information-dense, but the second sentence is an extremely long, parenthetical-laden run-on that bundles return format, bulk envelope, error semantics, and permissions together. Every fact earns its place, yet the packing hurts scannability.

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?

No output schema exists, and the description compensates by spelling out the returns (tag plus remaining tags; {bulk, operation, summary, results} envelope for UUIDs) and the permission gate. Nothing material is missing for a destructive, non-idempotent mutation.

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 each parameter, but the description adds real meaning: tagName never creates (unlike an add tool), a name the project lacks is an error for that Riddle, and the 100-item cap and UUID/UUIDs exclusivity are restated in context. Slightly redundant with the schema but adds error 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?

States a specific verb+resource ('Takes a tag off Riddles') and immediately distinguishes itself from both siblings by naming riddle_tag_add and riddle_tag_delete with the exact semantic difference. An agent can route 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?

Explicitly names the alternatives and their conditions, plus guidance on when NOT to bother ('a tag rarely has to be deleted by hand'), and states the precondition (origin.writableByThisKey must be true, cross-referencing riddle_get/riddle_list).

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?

The description adds substantial behavior beyond the annotations: it clarifies snapshot semantics ('The template is a copy taken at this moment... later changes to it do not reach the template'), states copy scope ('copies what the Riddle currently has stored, published or not'), describes permission requirements, and enumerates the return object's fields. These details are not present in the annotations, which only declare readOnlyHint=false, destructiveHint=false, etc.

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 purpose and follows with tightly relevant behavioral, permission, and return-value details. Every sentence adds value, and there is no repetition or filler; even the reference link to access concepts is 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?

Although there is no output schema, the description explicitly lists return fields ('{id, title, type, category, isPublic, isQuickCreate, blocksCount, image, icon, createdAt, riddle}'). Combined with rich annotations and a fully described input schema, the definition covers everything an agent needs to call the tool 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?

With 100% schema description coverage, the schema already documents all five parameters. The description still adds meaningful semantics by clarifying the scope of the copy triggered by the UUID parameter ('copies what the Riddle currently has stored, published or not') and by noting that omitting fields preserves the Riddle's own values, though it does not individually explain each 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 first sentence states a specific verb and resource: 'Stores an existing Riddle as a template of its project (or of the user, for a personal Riddle)'. It explicitly names the sibling tool riddle_template_use as the consumer of the created template, so an agent can distinguish creation from usage 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?

The description gives clear usage context: it explains that the template enables creation via riddle_template_use, and it states permission prerequisites ('Requires the template-create permission') plus an access caveat for non-full-access callers. It does not explicitly list when-not-to-use cases or name an alternative creation pathway, which keeps it at 4 rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds meaningful behavior beyond them: the conditional presence of "preset.paletteValues", the deliberate absence of paletteValues on built-in palettes (with the reference to fall back on), the empty-"build" + warning case, and the size warning that omittedDefaults maps measure 85-90% of 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?

The key purpose is front-loaded and each sentence carries real information, but the prose is dense with nested parentheticals and repeated cross-references to sibling tools, so it is longer than strictly necessary while remaining on-topic.

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 takes on the burden of return values and does so explicitly, enumerating the returned fields and explaining the build/preset/warnings edge cases. Nothing an agent needs to call it correctly 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%, so the baseline is 3, but the description adds rationale the schema lacks: why id ties back to templateId lineage, and that omittedDefaults is "to read, never to resend" and should be true only to learn what THIS template left at its default. This meaningfully guides correct parameter choice.

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?

"Reads one template, by default INCLUDING its build configuration" names a specific verb, resource, and default scope, and explicitly distinguishes the result from what riddle_get returns and riddle_builder_create accepts. An agent can tell it apart from riddle_template_use (copies whole) and riddle_template_list 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 explicit when-to-use and when-not: adapt via riddle_builder_create with this id as "templateId", or if "Not changing anything? riddle_template_use is one call and copies the template whole." It even routes the no-build-config case ("use riddle_template_use for those"). Alternatives and conditions are fully 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add what they don't: that isQuickCreate templates are merged into the same list, that results are not paginated so total is an exact count, and that build configuration is excluded. Missing only auth/scope caveats beyond the schema's note on API-key scoping.

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: scope and the sibling exclusion come first, then quick-create behavior, then the return shape. Every clause carries information, though the formatting as one run-on paragraph with inline literals is slightly harder to scan than it could be.

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 steps in and enumerates the returned fields (id, title, type, blocksCount, image, icon, createdAt, riddle, isPublic, isQuickCreate) plus the total envelope, and explains the non-pagination semantics and where the build configuration lives. Nothing an agent needs to call this correctly is absent.

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 both parameters are fully documented there, including the type enum values and the projectId default behavior. The description only restates that type filters by Riddle type and adds no syntax or format detail beyond the schema, 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?

States a specific verb (Lists) and resource (templates of a project or your personal ones), and explicitly carves out what it is NOT: Riddle's public ones, which it names as returned by riddle_template_public_list. An agent can distinguish it from riddle_template_create, riddle_template_get, and riddle_template_public_list 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?

Explicitly names the alternative (riddle_template_public_list) for public templates, and routes onward: read build config with riddle_template_get, or hand the id to riddle_template_use. It also clarifies that there is no separate listing for quick-create templates, closing a likely agent assumption.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds non-obvious behavioral context: results are grouped by category rather than returned as a flat 'items' list, and the build configuration is deliberately omitted. It does not discuss pagination or limits, hence not 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?

Front-loaded with the core purpose in the first clause, and every remaining sentence carries information (grouping behavior, return shape, alternatives). It is a dense, somewhat run-on single paragraph with nested quoting, which costs it a point on readability, but little 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 no output schema, the description compensates by spelling out the return shape ({categories: {<category>: [{id, title, type, blocksCount, image, icon, createdAt, riddle, isPublic}]}, total}) and the key structural quirk (grouped, not flat). Combined with sibling routing, an agent has everything needed to call and interpret it.

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 both parameters in detail (the exact Riddle types, the snake_case category slug). The description only notes that 'category' and 'type' narrow the results and that omitting category reveals existing ones, which largely duplicates the schema. Baseline 3 is correct.

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 (lists public templates) and immediately differentiates from the sibling riddle_template_list ('as opposed to riddle_template_list's own ones'). It also clarifies what this tool does NOT include (build configuration) versus riddle_template_get. An agent can distinguish it from siblings 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?

Explicitly states that calling with no arguments is how you discover the available categories, and names the alternatives: riddle_template_get for the build configuration, or handing the id to riddle_template_use. Both when-to-use and routing to alternatives are present.

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 flag destructiveHint=true and idempotentHint=true, but the description adds real behavioral context beyond them: partial-update semantics ('only what you pass changes'), the URL-backed media storage caveat (deleting the file breaks the image), fallback behavior suggestion via the remove param, and admin/access gating. It also notes the return shape mirrors riddle_template_create.

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 core action and the partial-update rule are front-loaded, and every sentence carries information. The trailing access-condition sentence is dense and cryptic ('without full access only for a Riddle whose origin.writableByThisKey is true'), relying on a reference link rather than plain language.

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?

No output schema exists, and the description substitutes by saying the return matches riddle_template_create. It covers permissions, image lifecycle, and the immutability of content, but leaves open edge behavior such as passing remove and coverMediaId together, or what happens for an unknown id.

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; the description earns above that by explaining the mediaId workflow (upload first via media_upload_link) and the storage-by-URL consequence for coverMediaId/iconMediaId, which the schema only gestures at. It does not add detail on how remove interacts with coverMediaId/iconMediaId in the same call.

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 (changes a template's title, gallery image, icon) and immediately scopes it against siblings by noting the template's content cannot be changed and that riddle_template_create should be used instead. An agent can distinguish this from riddle_template_create, riddle_template_get, and riddle_builder_update without reading 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?

Explicitly names the prerequisite workflow for images (media_upload_link into the template's project, then pass the reported mediaId), the alternative for content edits (create a new template from the edited Riddle), and the permission condition (public templates only by Riddle admins; otherwise requires origin.writableByThisKey). When-to-use and when-not-to-use are both present.

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 by disclosing the publish state of the result (DRAFT, with the exception that embedded/dependent Riddles such as a Form or Leaderboard are copied and published immediately), the required permissions ('template-use plus Riddle-create in the target project'), and that riddle_get reports it as context.duplicated. Minor gap: no mention of what happens if the template is deleted or whether a copy can be made repeatedly beyond idempotentHint=false.

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 and the alternative, then the draft/publish nuance, return shape and permissions. It is a single dense paragraph and the embed/dependency exception is slightly convoluted ('and so is the new Riddle when one of them depends on it'), but 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?

With no output schema, the description compensates by describing the return ('the standard build-configuration envelope') and the omit trimming. It also covers the mutation's side effects and auth requirements, so an agent has everything needed to invoke it 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 the schema already documents id, omit, title and projectId in detail; the baseline of 3 applies. The description only restates the omit parameter ('takes riddle_get's "omit" to leave sections of it out') without adding syntax or defaults beyond the schema, and never mentions title or projectId.

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 ('Creates a new Riddle from a template') plus the exact semantics of the operation ('an unchanged copy of it - content, settings and design preset'). It also distinguishes the outcome from the sibling that produces an edited Riddle, so an agent can tell riddle_template_use from riddle_builder_create 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?

Gives an explicit selection rule: 'Use this whenever the template is what you want; to adapt it first, read it with riddle_template_get and build the edited configuration with riddle_builder_create instead.' Both the use case and the alternative path with its prerequisite step 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 cover readOnly/idempotent/non-destructive safety, and the description goes well beyond them by disclosing the response document shape, where metrics live, the interval aggregation caveat, the USER-key requirement, and the crucial empty-vs-zero distinction. Slightly short of 5 only because the wall-of-text delivery blurs some of these points.

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?

Every sentence carries real signal (empty vs zero, interval total not daily, publish check), so it earns its length in content, but it is delivered as one dense run-on paragraph with no headings or front-loading of the most critical pitfalls. Structure could be far better for such a rich 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?

There is no output schema, so the description fully carries the burden of explaining return values, and it does: the core_metrics/stats location, block stats, timeseries interval structure, and breakdown shapes per namespace. An agent has enough to call correctly and interpret results.

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; the description adds meaning by tying entityId sources to project_list/whoami/riddle_list, clarifying that the account-wide summary rejects entityId, and explaining date defaults and per-view behavior. It mostly reinforces the schema rather than introducing new syntax.

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-plus-resource (views/starts/submissions of one entity) and immediately explains how namespace+entityId select the target and how 'view' controls depth. No sibling tool measures statistics, so the purpose stands apart without ambiguity.

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 when-to-use guidance per view: prefer a short range or one Riddle on a big project, narrow with projectIds rather than paging on a big account, and the account-wide summary requires a USER API key and takes no entityId. It also names the prerequisites for breaking down a Riddle and how to interpret empty results.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: that the plan is purely informational and never causes a refusal, plus null semantics for 'userName' and trial 'termEnd'/'daysLeft'. It does not discuss error/auth-failure behavior, so not 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?

Front-loading is good - the core purpose opens the description - but the remaining text is a dense run-on packed with nested parentheticals that makes field semantics hard to scan. Information density is high and most content is justified given the absent output schema, but the structure could be broken into cleaner clauses.

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 and no parameters, the description must carry the full burden of return-value explanation, and it does: it names the fields, describes the subscription object's members, explains null cases, and disambiguates key id vs user id vs project id. Nothing an agent needs to interpret the response 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?

The tool takes zero parameters, which sets the baseline at 4 by the rubric. The description uses its space instead to document return-value field names and null conditions, which is appropriate given there are no inputs to explain.

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?

Opening clause 'Reports the current API key' gives a specific verb and resource, immediately followed by the concrete payload (authenticated user, project/team, plan). It is unmistakably distinct from siblings like project_get or stats_fetch, which is reinforced by the explicit id-disambiguation against those tools.

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 explicit when-to-use statement, but the description does route the agent across tools by noting that the response's 'user' field is the entityId the stats tools want, and by clarifying that riddle_get's 'plan' is a different concept. This is useful implied guidance, but the basic 'call this to identify the connected account' framing 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.