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

Annotations are minimal (only idempotentHint: false), so the description carries nearly the whole behavioral burden, and it shoulders it well: it discloses that each call builds a new Riddle, that queue set adds 'queued': true to the response and makes creation asynchronous, that publish defaults to false (draft), and that passing templateId records the new Riddle in the template's lineage (reported by riddle_get as context.duplicated). No contradiction with the non-idempotent hint — everything aligns with a state-changing create operation.

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 top-level description is a compact three sentences with the most important facts front-loaded: what it builds, where full options live, and what it returns. The parameter-level prose is lengthy, but nearly every sentence carries actionable density (defaults, pitfalls, rejection rules). A few lines — such as 'Same parameter as riddle_get's.' and the repeat of the enumerated omit values — are mildly redundant with the schema, keeping this a session below 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?

For a tool with nested structure, six parameters meaning two publish-related fields with the same name, and no output schema, the description closes the important gaps: it names the return envelope, points to the response-format reference for exact key semantics, explains project/publish/queue/template defaults, and documents block construction rules for both the PickTheWinner and GuessTheScore variants. An agent has everything needed to construct valid inputs and anticipate what comes back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the bar for added value is high, yet the description goes well beyond the schema: omit gets a concrete operational recommendation (omit: ['build.omittedDefaults'] drops ~85-90% of the read-back), publish is explicitly differentiated from the publish object nested in the build config, and templateId explains a non-obvious effect — the full template design is applied, including parts no build config can express. Edge cases such as ambiguous labels being rejected and [0,0] clearing a correctResult are exactly the semantic details an agent needs.

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: 'Builds a Predictor from a build configuration.' This makes the tool's purpose unambiguous at a glance. It clearly distinguishes this from the sibling family (riddle_builder_quiz, riddle_builder_poll, riddle_builder_story, etc.) by naming the result type, and from riddle_builder_update by framing the build shape as 'the exact same shape' that update takes — i.e., this one creates while that one edits.

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?

Context is clearly established: this is the creation path, and the build parameter explicitly names riddle_builder_update as the editing counterpart and riddle_builder_validate as the dry-run counterpart, saying the shape is shared across all three. It also gives when-not-to guidance: correctResult 'is rejected when the block is being created... since an outcome only exists once the Riddle does.' Missing is an explicit routing statement for the builder family (e.g., 'other riddle types use riddle_builder_quiz/form/...'), which the naming already implies but the description never states.

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