Embers: Tabletop RPG Toolkit

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

Annotations already mark this as non-read-only, so a create operation is expected. The description adds useful behavioral context beyond that: the submission is filed on the calling user's behalf, it returns the created submission, and the user can track it via the listed tools. No contradiction 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?

Three tight sentences cover what the tool does, required inputs and the attachment source, and what happens with the result. The most important information is front-loaded before optional detail.

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 4-parameter creation tool with a full schema, required and optional fields are clear, the attachment dependency is stated, and related tracking tools are named. The only omitted items, such as auth or rate limits, are not expected for this kind of straightforward submission tool.

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

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

Schema coverage is 100%, so the schema carries the parameter details. The description still adds value by naming the required parameters in order and clarifying that attachments must be IDs from upload_submission_screenshot, a relationship not fully expressed in 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 leads with a specific verb and resource: 'File a bug report or a feature request with Embers...' and explicitly distinguishes the two type values. This makes the tool's purpose unmistakable and sets it apart from tracking tools like get_submission and list_my_submissions.

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 context for when to use it: to file a bug or request on the user's behalf. It also points to upload_submission_screenshot for attachments and to get_submission/list_my_submissions for tracking, but it does not explicitly state when not to use it or mention reply_to_submission as the follow-up 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing the safety profile. The description adds meaningful behavioral context by specifying the exact contents returned (original report, screenshots, current status, activity feed with replies and status changes) and the access restriction. This goes beyond what 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 description is a single, information-dense sentence that leads with the core purpose, then details the return contents, the source of the parameter, and the restriction. Every clause earns its place, and there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is an output schema (not shown but indicated), the description need not explain return format. It covers the scope, the contents, the parameter source, and the access constraint. For a simple read tool with one parameter, this is complete and unambiguous.

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 schema already provides a complete description of submissionId ('Mongo `_id` of one of the caller's submissions (from list_my_submissions)') with 100% coverage. The description repeats the source (list_my_submissions) but adds no new semantics beyond what the schema already states, so it stays at the baseline of 3.

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 clearly states the verb ('Read') and the resource ('one of the calling user's submissions') and enumerates exactly what is returned (original report, screenshots, current status, activity feed). It also differentiates this from list_my_submissions by referencing it as the source of the ID, and from other submission tools (create, reply, upload) by its read-only nature.

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 instructs how to obtain the parameter ('Pass `submissionId` from list_my_submissions') and includes a strong constraint ('Another user's submission is forbidden'). However, it does not explicitly contrast with alternative tools like reply_to_submission or upload_submission_screenshot, though the read-only intent is clear from the description and annotations.

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 convey that this is a mutating, non-destructive, non-idempotent operation, so the description does not need to repeat those. It adds useful ownership context and the no-default-ruleset caveat, but it does not disclose side effects, failure modes, or any creation-time behavior beyond that.

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 sentences, no wasted words, and the most important information is front-loaded. The ownership, required fields, and ruleset caveat are all stated efficiently.

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 20-parameter create tool with nested objects, the description establishes ownership and required fields but leaves optional behavior, defaults, status semantics, and nested-object handling to the schema. The output schema and annotations help, but the description alone is only minimally complete.

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

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

The description adds essentially no parameter meaning beyond the schema: name and ruleset being required is already in the schema, and 'Other fields pass through to imagine' is vague. With 20 parameters and moderate schema coverage, the description does little to help an agent understand optional-field behavior or nested structures.

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 ('Create'), a unique resource ('adventure'), and scoping ('owned by the calling user'), making it easy to distinguish from sibling tools like imagine_create_world and imagine_create_adventure_page. The required-field note reinforces the core action without blurring the purpose.

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 clearly establishes the context: use this when creating a new adventure for the calling user, and it calls out the ruleset requirement and the lack of a default. It does not explicitly name alternatives for when not to use this tool, so it falls just short of a 5.

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

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

Annotations already establish this as a mutating, non-idempotent, non-destructive operation, and the description adds behavioral nuance beyond that: 'Set the tags array so the page is filterable' and 'documentType is also auto-added to the searchable keyword set.' It does not contradict any annotation.

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 required fields, and most sentences earn their place by adding use cases or exclusions. The only mild redundancy is restating the documentType enum that already exists in the input schema, but it remains compact and scannable.

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 24-parameter create tool, the description covers the essentials: required fields, permitted document types, non-goals, and tag/filter behavior. The output schema covers return values and the input schema documents most optional fields, so an agent can safely select and invoke the tool; a minor gap is that omitting documentType is not addressed.

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 schema covers 67% of parameters, and the description adds useful semantics for the most decision-critical ones: required adventureId/name, the valid documentType enum, and tag filtering behavior. However, it does not compensate for the several schema-undocumented optional fields such as goal, mapPin, locationKey, aliases, and menuOrder.

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 leads with a specific verb and resource: 'Create a new page inside an adventure.' It reinforces scope with concrete use cases ('scene descriptions, encounter rooms, NPC profiles, plot beats') and clearly distinguishes itself from vault item/rule creation tools by stating those are NOT page types.

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 when to use the tool and gives an exclusion with routing guidance: 'Items and rules are NOT page types; author them in vault and reference them, not as adventure pages.' This tells an agent both what this tool is for and when to choose an 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?

The description adds useful behavior beyond annotations: creation is scoped to the calling user, optional fields pass through to imagine for validation/defaulting, and worlds have no independent ruleset. The annotations already convey mutation (readOnlyHint=false), non-idempotency, and non-destructiveness, so the description builds rather than repeats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences with no filler, front-loaded with the core action and required field. The ruleset note adds value without bloating the description, although the list of pass-through fields is partial and slightly ambiguous.

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 create operation with an output schema and annotations covering safety/idempotency, the description supplies essential context: ownership, required field, validation/defaulting behavior, and world-ruleset relationship. The remaining gaps are field-level details, most of which live in the input schema, but the 15-parameter surface keeps it from fully complete.

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

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

Schema covers only 53% of parameters, and the description names just three optional fields (summary, description, link) beyond required name. The general 'pass through... validates and assigns defaults' clause is helpful but does not compensate for undocumented fields like image, favicon, keywords, and showInvite, leaving some parameter semantics to inference.

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 ('Create'), a precise resource ('new world'), and ownership ('by the calling user'), clearly identifying the operation. It also calls out 'Required: name' and distinguishes worlds from adventures by noting the ruleset does not live on worlds.

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?

Purpose context is clear: use this tool to create a world for the calling user. It gives an implicit exclusion by stating that worlds do not carry their own ruleset and that rulesets live on adventures, which helps route ruleset-related work to adventure tools, though it does not name a specific 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?

It reveals non-obvious behaviors beyond the annotations: gm pages 404 for non-contributors and vanish from lists, masked pages still appear under maskName with hidden content, and documentType is auto-added to the keyword set. Since annotations only establish that this is a non-read-only, non-idempotent world operation, this behavioral detail is valuable and not contradicted.

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 every sentence earns its place: required fields and purpose first, then valid types, then tag behavior, then visibility semantics. Despite covering a 28-parameter tool, it avoids fluff and does not repeat parameter names for their own sake.

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 create operation with complex visibility behavior and an output schema, the description covers the substantive choices an agent must make: page category, required identifiers, tag/filter behavior, and public/gm/masked visibility. The optional nested fields remain discoverable in the schema, so no critical guidance 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?

With schema coverage at only 46%, the description compensates by spelling out the decision-critical parameters (required worldId and name, documentType values, tags filtering, visibility modes and maskName default). It does not explain many optional fields (parentId, outboundLinks, eventDate, menu fields, etc.), though those are less decision-critical for a create 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?

Opens with a precise verb and resource ('Create a new page inside a world'), then narrows the scope with concrete use cases (NPCs, locations, organizations, events) and an explicit list of valid documentTypes. It clearly differentiates world pages from the vault-item/rule authoring path and, by naming the world context, from adventure-page 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 states exactly what the tool is for ('Use this for NPCs...') and gives an explicit when-not: 'Items and rules are NOT page types; author them in vault and reference them.' It also tells the agent to set tags for downstream filtering and explains how to achieve GM-only vs masked visibility, so an agent can decide correctly before invoking.

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?

Even with annotations already marking destructiveHint=true and readOnlyHint=false, the description adds valuable behavioral detail: soft-delete semantics, movement to the deleted list, restoration via UI, tombstoning of pages, required permission, and the instruction to confirm with the user. This goes well beyond the annotations and gives the agent a clear model of side effects.

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 compact and front-loaded: the core action appears first, followed by key behavioral consequences and usage warnings. Every sentence contributes useful information, and there is no redundancy or 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 one-parameter delete tool with an output schema present, the description covers the essential action, side effects, permission requirement, restore path, and safety caveat. Nothing an agent needs to invoke 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?

The schema already provides 100% coverage for the single `id` parameter, describing it as the Mongo `_id` of the adventure. The description adds no further parameter detail, but with full schema coverage, the baseline score of 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 description states a specific verb and resource: 'Soft-delete an adventure by id.' It also clarifies the deletion mode (soft-delete) and names the target resource (adventure), making it easy to distinguish from sibling tools like imagine_delete_adventure_page or imagine_delete_world.

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 provides clear usage context: the caller must have 'edit', must confirm with the user first, and the operation is destructive. It also explains that the adventure is moved to a deleted-adventures list and can be restored via the UI, which gives practical guidance. It does not explicitly name an alternative tool for when-not-to-use, but the resource scoping 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?

Description clearly discloses irreversibility ('unrecoverable', 'does not soft-delete'), access requirements, and destructiveness. This adds meaningful context beyond the destructiveHint and idempotentHint annotations, especially emphasizing the need for user confirmation.

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, information-dense sentences with no filler. The main action is front-loaded, followed by critical irreversibility, access, and safety guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter destructive operation with output schema presentfallback, the description covers the essential behavioral aspects: what it does, irreversibility, access requirements, and user-confirmation requirement. Nothing an agent needs to call 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%: the only parameter 'id' is fully described as a Mongo _id. The description adds only 'by id', which repeats the schema. No additional parameter meaning is necessary, so 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 (delete) and resource (adventure page by id). The phrase 'Permanently delete' plus 'does not soft-delete' distinguishes this from similar delete tools for other resources and from update 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?

Provides explicit context: caller must own or have edit access, and should confirm with the user first. It does not explicitly name alternatives or exclusion conditions, but the prerequisites and confirmation guidance make usage conditions 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?

The annotations already carry destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description adds meaningful behavioral context beyond those flags: soft-delete rather than hard delete, the deleted-worlds list side effect, restorability from the UI, child tombstoning, and the edit permission requirement. No contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences deliver the core action, side effects, access requirement, and a safety caution without redundancy. The most important facts are front-loaded, and every sentence adds 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?

The definition fully covers what happens, what else is affected, who may call it, and the required user confirmation. With a single parameter, a well-documented schema, and the presence of an output schema, nothing essential is missing for an agent to select and invoke 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?

Schema coverage is 100% and the single parameter already has a clear description as the Mongo `_id` of the world. The description only repeats 'by id' without adding format, source, or validation details, so it doesn't add much beyond the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('soft-delete'), a clear resource ('a world by id'), and precise scope ('the world is moved to the user's deleted-worlds list'). It also distinguishes this from sibling delete tools by noting pages and adventures are tombstoned with it, so an agent can tell it apart from imagine_delete_adventure and imagine_delete_world_page.

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 context: the caller needs 'edit' access, the operation is destructive, and the user must confirm first. It doesn't explicitly name alternatives or state when not to use it, but the soft-delete/restore framing plus the sibling list makes the appropriate usage reasonably 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 indicate destructiveHint=true, but the description adds crucial context: the page moves to trash, keeps link and aliases reserved, restore window of 45 days, and permanent purge after. This goes beyond annotations by clarifying the soft-delete nature, which is essential for the agent to know the action is reversible. Slight deduction for not specifying exact response format, but the description is behaviorally rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a compact paragraph of four sentences, each with a purpose: what it does, what happens after, who can call it, and the safety warning. It front-loads the key actionable verb 'soft-delete' and does not waste words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is simple with one parameter, the description covers the action, outcome, permissions, reversibility, and safety confirmation. It doesn't describe return values, but there is an output schema (though its content is not provided in the context), so the description needn't. It also doesn't mention error conditions, but for a delete tool this is not critical. Overall, it is nearly complete.

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

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

Schema coverage is 100% and the schema describes the 'id' parameter as 'Mongo _id of the world page.' The description doesn't add much about the parameter, but since the schema is complete, baseline is 3. Credit for the description's phrase 'by id' which reinforces the parameter's role, but most semantic weight is on the schema. Thus 4 is justified for not needing more.

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 clearly states the verb (soft-delete), the resource (world page by id), and the key behavioral nuance (soft-delete vs delete). It distinguishes itself from sibling delete tools like imagine_delete_world and imagine_delete_adventure_page by specifying 'world page' and the soft-delete mechanism.

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: caller must own or have edit access, and confirms the user before use. It also implies when not to use by contrasting with other delete tools (which likely do hard deletes) via the soft-delete detail. It provides clear prerequisites and safety steps.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read/generation operation. The description adds the behavioral trait that it returns an array of names, which is useful. However, it does not disclose details like randomness, uniqueness, or whether the same input yields different outputs, which would be valuable for a generation tool. The description does not contradict 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 two sentences and front-loads the core purpose. The second sentence about the return type is useful but could be considered redundant given the output schema exists. Still, it is concise and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the output schema, and the annotations covering safety, the description is nearly complete. It could mention that the tool is non-deterministic or that names are randomly generated, but for a simple name generator with fully documented parameters, the current description is adequate.

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 all three parameters (count, length, includeEpithet) with descriptions and defaults. The description adds no additional parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('generate') and resource ('draconic names'), and the title 'imagine_generate_draconic_name' is clearly reflected. It distinguishes itself from sibling tools like imagine_generate_npc by focusing on name generation, and the description's mention of 'harsh phonetics of the Draconic tongue' adds flavor that clarifies the 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?

The description implies a creative-generation use case, and the sibling list shows many other generation tools (e.g., imagine_generate_npc, vault_build_monster), but the description does not explicitly state when to use this tool versus alternatives. It is clear enough for an agent to infer that this is for generating draconic names, not NPCs or other entities, but it lacks explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false. The description adds useful context by noting the output is a random NPC object and that a secret may be included. It does not contradict the annotations, though it adds only modest behavioral detail beyond what annotations 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?

A single sentence communicates the tool's purpose, contents, optionality, and return type with no filler. Every element earns its place, and the core action is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter, full schema coverage, an output schema, and safety annotations, the description is sufficiently complete. It lacks explicit usage guidance or alternatives, but nothing essential to invoking 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%, and the single parameter includeSecret already has a clear description with its default value. The main description's phrase '(optionally) a secret' adds no meaningful information 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?

The description states a specific action ('Generate'), a clear resource ('a random NPC'), and the key content fields (personality, occupation, optional secret), plus the return type. This clearly distinguishes it from sibling tools like vault_create_character or imagine_generate_draconic_name, even without explicitly naming them.

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 intended use is implied: call this when you need a random NPC with personality and occupation. However, it does not mention alternatives or exclusion criteria, such as when to use vault_build_pc/vault_create_character for a hand-crafted character instead. The context is clear but not explicit.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds the permission exception (private adventure + campaign member => recaps-only 200 instead of 403) and shape variations (`recapsOnly`, `hasLinkedCampaigns` vs `playCampaignIds`). It also clarifies the informational campaign-link behavior, which is not visible in 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 long but every clause carries a distinct fact: payload, campaign non-sync, parent-series handling, and the auth exception. The main action is front-loaded, with edge-case detail following in a logical order.

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 a one-parameter schema and an output schema present, the description covers all call-relevant context: access requirements, exceptions, related-tool routing, and linked-campaign behavior. No critical gap remains for an agent 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?

The single `id` parameter is already described in the schema as a Mongo `_id` with minLength 1 (coverage 100%), so the description has little left to add. It reinforces that the operation is by-id and mentions `parent` ids, but does not alter or extend the schema 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 opens with a specific verb+resource: 'Fetch one adventure by id,' and enumerates the payload components (settings, ruleset, recommended level, linked play campaigns). It clearly differentiates from the sibling list/recap tools, and the parent-series clause names the exact sibling for related parts.

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 explicitly routes to imagine_list_adventure_parts when a parent is populated, and notes the minimal shape is 'enough to call imagine_get_adventure_recaps.' It also warns that imagine and play do not auto-sync state, preventing misuse of the campaign link.

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 discloses the default dereferencing behavior, the fact that rule-* shortcodes are NOT expanded and why, and the raw:true escape hatch. It also explains the shape of cross-references (parent, worldPageRefs, vaultRefs) and how to resolve them. This goes well beyond the annotations (readOnly, idempotent, non-destructive) and adds real behavioral context.

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 well-organized: it front-loads the core fetch behavior, then explains expansion behavior, then cross-reference resolution, then pairing with the list tool. Every sentence earns its place, though the cross-reference sentence is long and could be slightly more scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the annotations cover safety, the description covers everything an agent needs: what is returned, how expansion works, when to use raw, how to resolve cross-references, and how to find the id. No critical gap remains.

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 both parameters. The description adds value by explaining the default vs raw behavior and the round-tripping use case, which enriches the raw parameter's meaning beyond the schema's description. The id parameter is straightforward and needs no extra explanation.

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 clearly states the tool fetches one adventure page by id, and specifies the returned content (markdown body, tags, parent reference). It also distinguishes itself from sibling tools like imagine_get_adventure_pages (plural) and imagine_get_world_page by naming the resource type and the resolution targets.

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 explains when to use raw:true (round-tripping through imagine_update_adventure_page) and when not to (default expansion). It also tells the agent to pair with imagine_list_adventure_pages to locate the id first, and gives resolution guidance for cross-references. This is strong usage guidance.

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

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

Annotations already mark the tool read-only and idempotent; the description adds valuable behavior beyond that: silent omission into a `missing` array instead of failing the batch, the 50-id cap, and default shortcode expansion with a raw escape hatch. These details materially affect how an agent interprets 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?

Four dense sentences cover operation+cap, use case, return shape, and failure semantics with no filler. The most decision-relevant facts are front-loaded, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Together with the rich schema and output schema, the description gives the agent everything needed to invoke the tool correctly: batch limits, per-page output shape, shortcode behavior, and the distinction between returned pages and missing ids. Nothing relevant is left unexplained.

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 input schema already documents both parameters in detail: Mongo `_id` list, 50-id cap, silent missing behavior, and the raw toggle. The description adds the return-shape relationship to imagine_get_adventure_page, but that is contextual framing rather than new parameter-level semantics. With 100% schema 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 operation and resource: 'Batch read of adventure pages by id.' The 50-per-call cap and the reference to imagine_get_adventure_page clearly distinguish this from the single-page sibling, so an agent can identify it at a glance.

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 recommends this tool when walking an act and reading several scenes' bodies, framing it as one call instead of one tool invocation per page. It doesn't explicitly spell out the reverse case ('use imagine_get_adventure_page for a single page'), but the use context and sibling relationship are clear enough.

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 readOnly/idempotent/non-destructive annotations, the description discloses important behavioral details: caller must be a campaign member, visibility follows play page rules, campaigns without tagged sessions are omitted, and the empty result shape is `{ campaigns: [] }`. This is exactly the kind of access-control and filtering context annotations do not capture.

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 purposeful, covering purpose, data shape, access rules, empty behavior, and the manual alternative in roughly four sentences. It is front-loaded with the core action and grouping, though the middle data-shape sentence is somewhat detailed given that an output schema already exists.

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 read-only fetch tool with one well-documented parameter and an output schema, the description is complete: it explains what is fetched, how results are grouped, who can access what, when campaigns are omitted, and what the empty response looks like. Nothing an agent needs to invoke 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?

The single parameter `id` is already fully documented in the schema as the Mongo `_id` of the adventure, so the schema description coverage is 100%. The description adds no new parameter-level detail, but it does reference 'this adventure' contextually; baseline 3 is appropriate when the schema carries the parameter meaning.

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 ('Fetch'), a precise resource ('play-session recaps written while running this adventure'), and the grouping behavior ('grouped by linked play campaign'). It also explicitly distinguishes itself from the manual walk of play_list_campaign_sessions + play_list_pages, so an agent can separate it from 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 clear context: it is the recaps-only path for private adventures, requires membership in a linked campaign, and is positioned as the replacement for a manual multi-tool walk. It does not explicitly state when-not to use it versus sibling listing tools, but the alternative is named and the access conditions make usage 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond that: the campaign link is informational only and not auto-synced, and the caller must have view access. These details help the agent understand the tool's side effects and authorization requirements, which annotations do not 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 description is three sentences with no waste. The first sentence states the primary purpose and return content, the second clarifies a critical caveat, and the third states a permission prerequisite. It is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (indicated) and only one parameter, the description is complete for correct invocation. It covers what the tool returns, the caveat about campaign links, and the required access level. No essential behavioral or usage information 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% for the single parameter 'id', which is described as 'Mongo _id of the world'. The description does not add additional semantics beyond restating that it fetches by id; it does not provide format examples or extra constraints. Since the schema fully documents the parameter, a baseline score of 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 description clearly states the verb 'Fetch', the resource 'world', the identifier 'by id', and enumerates the specific data returned (settings, membership, user-linked play campaigns). It differentiates from sibling tools like imagine_get_world_page or imagine_list_my_worlds by specifying the exact scope and fields, so an agent can distinguish it without opening other 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 provides a clear context: it is for fetching a single world by id with specific details, and it explicitly states the permission requirement ('Caller must have at least view access'). However, it does not explicitly mention when not to use it or name alternatives (e.g., imagine_list_my_worlds for listing), so it lacks explicit exclusions but still gives clear usage context.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description discloses the default expansion behavior (dereferencing shortcodes and inlining <expansion> blocks) and the preservation of the original literal. It also clarifies the effect of raw:true, providing substantial behavioral detail that the annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but each sentence serves a purpose: it starts with the core operation, then explains the default expansion, the raw override, cross-reference resolution, and how to locate the id. It is longer than strictly necessary but well-structured and front-loaded with the main function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description appropriately omits return format details, but it adds valuable cross-reference resolution hints (parent and vaultCharacterId) and workflow guidance on locating the id. The tool is fully contextualized for an agent 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?

Both parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description re-explains the raw parameter's behavior and adds a round-tripping use case, but this adds only marginal value beyond the schema, not enough to raise the 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?

The description opens with a specific verb and resource ('Fetch one world page by id') and enumerates the returned content (full markdown body, tags, parent reference). It differentiates itself from siblings by pairing with list/search tools to locate the id, implying this tool is for retrieval of a single known page.

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 explicitly advises pairing with imagine_list_world_pages or imagine_search_world_pages to locate the id, and explains the raw:true option for round-tripping bodies back to imagine_update_world_page. This gives clear workflow context, though it does not describe when not to use the tool relative to other getters.

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 convey readOnly=false, idempotent=false, destructive=false. The description goes far beyond: it explains the side effect (mutating playCampaignIds[]), the derived effect on the campaign's imagineAdventures[] and session Adventure tag, and details error codes (403, 404, 400) with conditions. This fully discloses behavioral impact without contradicting 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 a single dense paragraph, but every sentence contributes: core action, side effects, access control, error codes, preconditions, and a pointer to a helper tool. It is front-loaded with the primary verb and object, and no sentence is redundant.

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 mutating link operation, the description covers all essential context: what, where, side effects, permissions, error handling, and input sourcing. With an output schema present (though not shown) and annotations covering safety, nothing an agent needs to invoke 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. The description adds value by explicitly stating where to get campaignId (from play_list_my_campaigns or play_list_participated_campaigns) and that id is a Mongo _id of the adventure. This enriches the schema's minimal descriptions, so a 4 is warranted.

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 clearly states the action: 'Add a play campaign to an adventure's playCampaignIds[]'. It names the specific resource, the exact array field being modified, and distinguishes itself from the sibling tools imagine_unlink_adventure_from_campaign and imagine_link_world_to_campaign by specifying the exact data model.

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 tells when to call it ('call this only when you've confirmed the link isn't already present'), provides error-handling guidance ('or be ready to handle the 400'), and directs the agent to use play_list_my_campaigns to find the campaign ID. It also states required permissions (owner/gamemaster + edit access on adventure).

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 discloses side effects beyond annotations: the link is stored in the world's playCampaignIds[], house rules are shared both ways, characters are imported by default, and the tool returns 400 if the link already exists. It also specifies the required 'edit' access. This far exceeds the annotations' minimal hints and accurately describes the operation's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph but front-loads the core purpose in the first sentence. Each subsequent sentence adds crucial operational detail (storage, house rules, permissions, error handling). It is not verbose or redundant, though it could be split into bullet points for easier parsing. Still, it is appropriately sized for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity—linking two entities, sharing house rules, importing characters, and requiring specific permissions—the description covers all key aspects: storage mechanism, side effects, default behavior, error cases, and access requirements. It also includes the output schema, so return values need not be explained. The description is fully sufficient for an agent to call this correctly.

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

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

Schema description coverage is 100%, with each parameter already explained in detail (e.g., id and campaignId are Mongo _ids, importCharacters has a description of its effect and default). The tool description adds no new parameter-specific meaning beyond what the schema provides, so the baseline score 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?

The description states the exact action 'Link a play campaign to a world' with clear verb and resource, and the detailed explanation of storage and effects distinguishes it from the sibling imagine_link_adventure_to_campaign. It leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to call it ('call this only when you've confirmed the link isn't already present'), notes the required caller permissions (owner/gamemaster), and mentions the alternative of setting importCharacters to false to skip character import. It provides clear conditions for use and implies when not to use 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?

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description only needs to add behavioral context. It adds that the result is tree-friendly, that parent filtering returns only direct children, and that both filters are combinable. These details go beyond the schema without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences with no filler. The core action and return type are front-loaded, followed by filter semantics and sibling guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema covers the return shape, annotations cover the safety profile, and all three parameters are fully described in both schema and description. Nothing an agent needs to call this tool 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?

The schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying direct-children semantics, showing realistic workflows for each filter, and stating that the filters are combinable.

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: 'List pages belonging to one adventure,' and immediately clarifies it returns summaries rather than full page bodies. It also distinguishes itself from sibling tools like imagine_get_adventure_page and imagine_get_adventure_pages by naming them and describing the split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete when-to-use context for each optional filter: parent for an 'open this act' workflow, documentType for 'list every scene.' It also explicitly tells the agent to pair with imagine_get_adventure_page or imagine_get_adventure_pages when full bodies are needed, making alternatives and exclusions clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description adds valuable behavioral context: only active parts are listed, ordering by menuOrder then name, one-level grouping, silent omission of unviewable parts, and empty-list behavior for non-parents. No contradiction 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 front-loaded with the core action and ordering, then adds behavioral edge cases and return fields without waste. Every sentence earns its place, and the field list is useful because it tells the agent exactly what shape to expect.

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 read-only, single-parameter list tool with an output schema, the description covers all necessary behavior: ordering, active filter, permission-related omission, non-parent result, and how to create parts. Nothing material is missing 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?

The schema already documents the single id parameter with 100% coverage, so the baseline is 3. The description adds meaning by clarifying that the id must be a series parent, which is needed to interpret the empty-list case. This contextual enrichment goes slightly beyond 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?

Description states a precise verb and resource: list active child adventures (parts) of a series parent, with explicit ordering. This distinguishes it from sibling list tools like imagine_list_adventure_pages and imagine_list_my_adventures, so an agent can select it without guessing.

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 clearly implies the tool is for series-parent adventures and explicitly covers the non-parent case (empty list), plus how to make an adventure a part. It does not name alternative tools, but the context is unambiguous enough for correct selection.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context beyond annotations by explaining the slim catalog-card scope, the series semantics of `parent`, and the relationship to detail-fetching tools.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first states the core action and scope, the second lists the return fields, and the third handles related-tool routing. It is front-loaded and contains 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?

With an existing output schema, comprehensive annotations, and no parameters, the description covers everything an agent needs to decide to call this tool and interpret the series-parent concept. Pagination and ordering are not mentioned, but nothing in the context signals they are essential for this simple list operation.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter documentation gap for the description to fill. The baseline of 4 applies because no semantic burden is placed on the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List the adventures the calling user owns or has access to.' It clearly differentiates this tool from the related imagine_list_adventure_parts and imagine_get_adventure by stating what this tool returns versus what those tools are for.

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 guidance is provided for related operations: when an adventure has a non-null `parent`, the reader is directed to imagine_list_adventure_parts, and when full body/config is needed, imagine_get_adventure is named. This gives an agent actionable routing without ambiguity.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the return fields ('id, name, summary, image, link, createdAt, updatedAt') and the slim catalog-card nature, giving the agent a concrete expectation of output shape beyond what annotations provide. It doesn't contradict 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?

Two sentences, each earning its place. The first sentence states purpose and scope; the second lists return fields and points to the sibling tool. Fully front-loaded, no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter list operation with an output schema already present, the description covers the essential context: scope of access, return field summary, and the escape hatch to get full details. An agent can call it correctly without further info. The description is thorough given the tool's simplicity.

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

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

The tool has zero parameters, so the description has no parameter details to add. Per baseline, a 0-param tool gets a 4. The description correctly avoids inventing parameter notes and focuses on behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('worlds'), and clearly scopes it to 'owns or has access to via membership.' It also distinguishes itself from imagine_get_world, which reads a specific world's full body, so an agent knows this is a catalog listing 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?

The description explicitly tells the agent when to use this over an alternative: 'To read a specific world's full body and configuration, call imagine_get_world with the id.' This is a clear routing statement. It also implicitly communicates the use case of listing all accessible worlds without needing parameters.

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 non-destructive behavior. The description adds value beyond them by disclosing the return payload shape (id, name, link, parentId, tags) and that the result is a hierarchy-friendly summary rather than full content.

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 sentences deliver purpose, return shape, and a companion-tool pointer with no filler. The core scope is front-loaded, making the definition easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list operation with one well-documented parameter, an output schema, and rich safety annotations, the description covers what an agent needs: scope, return type, and how to fetch full content. Nothing critical 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 for the single required parameter is 100%, with worldId described as a Mongo _id. The description only reinforces 'one world' without adding new parameter syntax, format, or edge-case details, 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?

The description states a specific verb ('List') and resource ('all pages belonging to one world'), and identifies the return format as a tree-friendly summary, which distinguishes it from content-fetching siblings like imagine_get_world_page and tag-filtered variants. This is unambiguous and immediately actionable.

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 provides clear workflow guidance by pairing this tool with imagine_get_world_page for full content, implying this tool is for summaries and navigation. It does not explicitly contrast with imagine_list_world_pages_by_tags or imagine_search_world_pages, so it misses full exclusionary guidance.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive, and the description adds valuable hidden behavior: documentType is folded into the same keyword set, so a tag like 'character' also matches documentType=character. It also discloses the default mode ('or'), which is genuinely useful and not obvious from the schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core action, then adds only high-value details about documentType, mode behavior, and common patterns. Every sentence earns its place without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, annotations cover safety, and all parameters are documented in the schema, the description provides the remaining behavioral context an agent needs: how tags interact with documentType, the default/mode choices, and typical use cases. Nothing critical is missing 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 the baseline is 3, but the description goes beyond the schema by explaining the unexpected documentType matching behavior and giving concrete tag examples. It clarifies the tags parameter more deeply than the schema's 'comma-separated list' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Filter pages within a world by one or more tags.' It also clarifies what makes this tool distinct from plain listing/searching by explaining tag matching semantics, so an agent can identify it among siblings like imagine_list_world_pages and imagine_search_world_pages.

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 concrete usage patterns ('all NPCs', 'all locations', 'every character-type page') and explains when to use mode 'and' vs 'or'. It does not explicitly name the sibling alternatives or say when not to use them, but the examples make the intended use 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses key behaviors: byte-level preservation outside matches, single-pass replacement of all occurrences, the staleness guard returning 409 without saving on count mismatch, and the literal match semantics. This adds substantial behavioral context the annotations do not 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?

Two sentences with no fluff. The first sentence front-loads the core purpose and key differentiator, the second covers matching, guard, and return. Every phrase earns its place, and the structure is easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential operational context: the safe usage, the alternative to avoid, the literal matching, the option for a staleness guard with its 409 behavior, and the return format. It even tells the agent to pre-count occurrences if protection is desired. With an output schema available, nothing material 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 schema already fully documents each parameter, including the literal match behavior and the staleness guard. The description adds context like 'single pass' and return value, but these are already implied by schema descriptions and output schema. It provides no new parameter-specific semantics beyond reinforcing 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: 'Replace text inside one adventure page's content'. It distinguishes itself from the sibling imagine_update_adventure_page by emphasizing 'surgical find-and-replace' that preserves every byte outside matched ranges, making its unique intent explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage context: it is the 'safe primitive for terminology passes' and directly contrasts with imagine_update_adventure_page, which 'would risk dropping formatting whitespace the LLM can't see in JSON.' This clearly tells an agent when to pick this tool over the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the search scope (titles + raw markdown), the ranked-summary return shape, and critically the shortcode limitation where literal-text matching can miss rendered content. It stops short of pagination or result-limit behavior, but the output schema covers return structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: purpose, return shape, the key gotcha, and the routing alternative. Information is front-loaded (purpose first) with the caveat and sibling guidance after. No filler, no repetition of schema or annotation content.

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 read-only search tool, the definition is complete: annotations cover safety, the output schema covers return values, the description covers scope, the known failure mode, and the correct sibling alternative. An agent has everything needed to decide when to call this tool and what to expect from 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%: query and worldId each have meaningful descriptions in the schema. The description only marginally augments this by clarifying that the query runs against titles and raw markdown 'within one world,' reinforcing worldId's scoping role. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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: 'Text search over page titles and raw markdown bodies within one world.' It also explicitly distinguishes itself from the sibling tool imagine_list_world_pages_by_tags by scoping this tool to raw text search and the sibling to category/tag lookups. The title and description align cleanly with no 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?

Provides explicit routing guidance: 'For category lookups (NPCs, locations, monsters), prefer imagine_list_world_pages_by_tags with the tag or documentType value.' It also flags when results may be incomplete (shortcodes matching literally), so an agent can warn the user or switch strategies. This is rare, explicit when-not-to-use guidance naming the exact 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?

The description adds substantial behavioral context beyond the annotations: session tags remain inert while unlinked and re-lit on re-link, dangling links to non-existent campaigns are still removed, and exact caller permissions are specified. This goes well beyond the idempotentHint and destructiveHint annotations and gives an agent a realistic picture of side effects.

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 earns its place: the core action, the inverse relationship, the inert-tag side effect, the dangling-link edge case, and the auth requirement. The most important information is front-loaded, and there is no filler or repetition of schema content.

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 an output schema and strong annotations, the description covers all essential operational concerns: side effects, edge cases, permissions, and relationship semantics. Nothing an agent needs to invoke it correctly appears to be 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 schema already documents both `id` and `campaignId` adequately. The description adds a little semantic color around the link relationship and the dangling-campaign edge case, but does not materially extend parameter meaning beyond what the schema provides. 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 description opens with a specific verb and resource: 'Remove a play campaign from an adventure's `playCampaignIds[]`.' It clearly differentiates this from the inverse link tool and from `imagine_unlink_world_from_campaign` by scoping the operation to adventures. The title and description consistently identify exactly what is being unlinked.

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 its inverse (`imagine_link_adventure_to_campaign`) and gives clear context for when this operation applies. It also states the caller prerequisites. It stops short of explicitly listing sibling alternatives or when-not-to-use conditions, but the purpose is unambiguous enough for an agent to select the correct tool.

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 meaningful behavioral context beyond the annotations: it identifies the exact data structure modified (`playCampaignIds[]`), describes the optional house-rule removal side effect, and states permission requirements. This goes well beyond the readOnly/destructive/idempotent hints while not contradicting them.

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, each earning its place: purpose and core effect, optional flag behavior, and access prerequisites. No filler or redundancy.

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 an output schema, the description covers the operation, optional side effect, and authorization requirements. It is missing only minor contextual details such as behavior when the link does not exist, but the idempotentHint annotation partially covers that.

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 all three parameters. The description adds a bit of shared context around `removeSyncedHouseRules`, but does not substantially extend the parameter-level meaning beyond what the schema provides.

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 begins with a specific verb and object: 'Unlink a play campaign from a world,' and then states the exact mechanism: 'removes the campaign from the world's `playCampaignIds[]`.' This clearly distinguishes it from sibling unlink tools for adventures and makes the tool's function unambiguous.

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 provides concrete usage context: when to add `removeSyncedHouseRules: true` and explicit caller requirements ('The caller must be the campaign's owner or gamemaster. Caller must have 'edit' access on the world.'). It does not explicitly name alternatives, but the intended use case is clear and the guidance is actionable.

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=false, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond them: partial-update semantics, the 'edit' permission requirement, optimistic-concurrency via baseUpdatedAt with OUT_OF_SYNC and 'nothing is written' on failure, and rename propagation to linked campaigns. This is exactly the context an agent cannot get from 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 core verb+resource, then permission, then the two highest-risk behaviors (series grouping, baseUpdatedAt). Dense but every sentence carries operational weight; only the parent clause is slightly redundant with the field description it points to.

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 24-param mutation tool with an output schema and rich annotations, the description covers the contract-completing details an agent needs: partial update, auth, concurrency guard, and side effects on linked campaigns. Return values are covered by the output schema, so nothing essential 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?

With 24 parameters and only 63% schema description coverage, the schema does most of the heavy lifting. The description adds real value for the tricky parameters (baseUpdatedAt workflow, parent grouping/ungrouping, menuOrder append default) but explicitly defers to the field description for parent validation and does not address the remaining undocumented fields. 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 and resource ('PUT updates to one adventure by id') and is clearly distinguishable from siblings like imagine_update_adventure_page and imagine_create_adventure. The scope of a partial update ('Only supplied fields are sent') is stated up front, so an agent knows exactly what this tool mutates.

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 prerequisites and routing: caller needs 'edit', and it explicitly directs the agent to a fresh imagine_get_adventure read before calling, with the OUT_OF_SYNC failure described. It does not spell out when to prefer a sibling like imagine_update_adventure_page, but for the common case the when-to-use 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 signal this is a write operation, but the description adds substantial behavioral detail: only supplied fields are sent, content is replaced wholesale, stale baseUpdatedAt values are rejected with OUT_OF_SYNC and nothing is written, and successful updates return a new updatedAt. It also discloses that read-aloud/moving-on/tactics are not fields but must be authored inline as callout blocks, which is valuable beyond the schema and 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 long but information-dense, with the core verb, resource, and warnings front-loaded before alternatives and prerequisites. Every major sentence earns its place, though the long field enumeration and repeated warning about content could arguably be tightened without losing value.

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 25-parameter write tool with concurrency requirements and several nearby siblings, this description is unusually complete: it covers update semantics, the wholesale-content hazard, the required optimistic-locking workflow, the permission requirement, and the correct alternative for surgical edits. An output schema exists, so the absence of return-value detail is acceptable.

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 68%, so the description does not need to fully re-document parameters, but it adds important meaning beyond the schema: the warning that content is replaced wholesale, the detailed required meaning of baseUpdatedAt, and the clarification that read-aloud/moving-on/tactics are not fields. It does not deeply explain the handful of parameters lacking schema descriptions, but it compensates reasonably for the main risk areas in an update tool.

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 ('PUT updates to one adventure page by id') and goes on to enumerate the full set of updateable fields, which clearly differentiates it from sibling get/create/replace tools. It also names the sibling surgical alternative, so an agent can distinguish this tool from imagine_replace_in_adventure_page without inspecting 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 explicitly states when to use this tool versus alternatives: prefer imagine_replace_in_adventure_page for surgical content edits, and fetch via imagine_get_adventure_page with raw=true when appending. It also states the required permission ('Caller must have edit') and the mandatory fresh-read workflow for baseUpdatedAt, giving unambiguous selection and invocation guidance.

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

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

Beyond the annotations, the description discloses optimistic concurrency (stale baseUpdatedAt causes OUT_OF_SYNC and no write), the partial-merge behavior, the permission requirement, and the need to reuse the returned updatedAt for follow-up writes. This adds substantial behavioral context and does not contradict any annotation.

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 tight sentences front-load the method and resource, then state the access requirement, the merge behavior, and the mandatory concurrency field. Every sentence earns its place, and the uppercase REQUIRES makes the critical constraint unmissable.

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 17-parameter update with nested objects, the description covers the essential call protocol: fresh read, merge semantics, permission, stale rejection, and post-write updatedAt handling. The remaining field-level details live in the schema and output schema, 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?

The description adds critical parameter-level meaning by explaining that only supplied fields are sent and merged onto the existing document, preventing an agent from assuming omitted fields get reset. It also reinforces the baseUpdatedAt freshness rule, though the schema itself already documents baseUpdatedAt in detail.

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 'PUT updates to one world by id,' naming the HTTP method, action, and exact resource scope in one phrase. This clearly distinguishes it from sibling update tools like imagine_update_adventure and imagine_update_world_page, which target 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?

The description explicitly states the edit-access prerequisite, the required fresh imagine_get_world read, and the merge semantics for partial updates, giving an agent clear call-flow context. It does not explicitly name alternatives or state when not to use this tool, but for an update-by-id operation the guidance is strong enough.

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

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

Goes beyond annotations by disclosing that content is replaced wholesale, that only supplied fields are sent, that OUT_OF_SYNC aborts the write, and how visibility levels behave (404 for GM-only, maskName for masked). These are behavioral traits annotations do not convey (idempotentHint true doesn't capture replacement semantics). No contradiction.

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?

Packed with warnings but front-loaded with the core action. Some redundancy with schema descriptions (visibility, baseUpdatedAt) makes it slightly longer than necessary, but every sentence serves a purpose.

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?

Handles the high-stakes behaviors: replacement, optimistic concurrency, and visibility. The existence of an output schema covers return-value details. However, with 29 parameters and nested structures, it doesn't clarify formats for many fields (e.g., how outboundLinks or playCampaignCharacters are structured) – though the schema's types partially cover that.

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 covers the essential traps (baseUpdatedAt, visibility, content replacement) in its own descriptions, and the tool description largely repeats those rather than adding new per-field meaning. It adds the cross-cutting 'Only supplied fields are sent' note commonsensically but does not compensate for the 52% of parameters that lack schema descriptions (e.g., relationships, outboundLinks, menuOrder).

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 'PUT updates to one world page by id' – a specific verb, resource, and scope that clearly distinguishes it from sibling update tools (imagine_update_world, imagine_update_adventure_page) and the create/delete world-page 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?

Explicitly says to fetch first with imagine_get_world_page before append, lists the edit permission prerequisite, and warns that stale baseUpdatedAt is rejected with OUT_OF_SYNC. This gives the agent clear when-to and when-not-to guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explaining the meaning of the 'clarification' status (Embers is waiting on the user) and the 'closed' status read-only behavior, which goes beyond the schema. It does not mention ordering, pagination, or rate limits, but these are not critical for a simple read-only list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the primary action and scope, then efficiently packs the status list with useful clarifications. Every element earns its place, and there is no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (no parameters, simple listing operation) and the presence of an output schema (which the description need not explain), the description is complete. It specifies exactly what is returned (submissions with statuses) and adds value by explaining the meaning of two important statuses. An agent can invoke this tool correctly with no additional information.

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, and the schema coverage is 100% (empty object). With no parameters to document, the description naturally does not add parameter-level detail. The baseline score of 4 for 0-parameter tools applies here.

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 clearly states the action ('List') and scope ('the calling user's own submissions'), specifies the resource type ('bug reports and feature requests'), and enumerates all possible statuses. This distinguishes it from sibling tools like get_submission (retrieves one submission) and create_submission (creates one).

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 clearly indicates this is for listing the caller's own submissions, which distinguishes it from any hypothetical tool that lists all submissions. However, it does not explicitly reference sibling tools like get_submission for single-item retrieval or mention when not to use it, leaving some inference to the agent.

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 read-only, idempotent, and non-destructive behavior. The description adds value by explaining that it returns user-specific permitted codes and includes both public and restricted entries, which goes beyond the annotations. No contradiction 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?

Two sentences with no wasted words. The action and scope are front-loaded, and the usage guidance is brief and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no parameters, output schema exists), and the description fully covers what it returns and when to use it. Nothing missing 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?

There are zero parameters, so the schema coverage is trivially 100%, and the baseline is 4. The description correctly omits parameter details because none exist.

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 clearly states the specific verb 'Return' and the resource 'ruleset codes the calling user is permitted to use'. It distinguishes itself by mentioning the inclusion of always-public and restricted rulesets, and its unique role among siblings (no other tool lists permitted rulesets).

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 'Use this before populating any ruleset selector or before filtering vault/play/imagine results by ruleset', giving clear guidance on when to invoke it. It does not mention when not to use it or alternatives, but given the unique purpose, this is sufficient.

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 makes clear this is an action on a pending friend request, which is consistent with the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It does not add much behavioral context beyond what the annotations and verb already convey, such as what state changes occur or what happens on success.

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 tightly written sentences with no filler. The action is stated first, and the parameter warning is front-loaded with the most important clarification about what friendId is not.

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 tool with 100% schema coverage, a clear description, an output schema, and annotations covering idempotency and destructiveness, nothing essential is missing. The description gives the agent enough 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?

Schema description coverage is 100%, so the schema already fully documents friendId. The description reinforces the critical distinction that friendId is the friend record's _id, not the requester's user id, but it does not add meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: accept a pending friend request directed at the calling user. It distinguishes itself from related friend-request siblings by emphasizing that the request must be pending and targeted at the caller, so an agent can tell it apart from send, decline, cancel, or 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?

The description gives clear context for when to use this tool: there is a pending friend request directed at the calling user. It also routes the agent to play_list_pending_friends as the source for the required ID. It does not explicitly name alternatives like play_decline_friend_request, but the usage context is clear enough.

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 discloses a non-obvious behavior: the attachment is placed on the campaign leg matching the vault character's ruleset, not chosen by the caller. It also adds a permission requirement ('contribute') that annotations do not capture. Since the annotations are all false flags, this behavioral detail is especially valuable, though duplicate-attachment behavior is not addressed.

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 tight, purposeful sentences: action, behavioral constraint, then permission and workflow. Every sentence carries new information and the most important content is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema and a simple 3-parameter input, the description covers the prerequisite active leg, the ruleset-matching behavior, the permission requirement, and the pre-step for locating the character id. An agent has everything needed to invoke this 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?

Schema description coverage is 100%, so the baseline is 3; campaignId, characterId, and npc are already documented in the schema. The description adds workflow context for characterId by referring to a 'vault character' and its ruleset, but it doesn't need to restate 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 opens with a specific verb-resource pair ('Attach a vault character to a play campaign') and states the purpose ('so the character participates in play'). It clearly differentiates this from read/list tools like play_list_campaign_characters and from vault_attach_companion by focusing on play campaign participation.

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 context: the campaign must have an active leg matching the character's ruleset, and the caller needs 'contribute' permission. It also instructs the agent to use vault_search_characters first to locate the character id. It doesn't explicitly state when-not-to-use, but no natural alternative tool exists for this exact 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 the annotations (readOnly=false, destructive=false, idempotent=false) by disclosing two distinct 400 failure modes, the placement rule that the item lands on the leg matching its own ruleset, and the required 'contribute' permission. These are exactly the traits an agent cannot infer from the flags or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action, then the leg rule, then the permission. No filler, no restating of the title, and the 400 conditions are attached to the behaviour that causes them.

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 an output schema present, return values need no explanation. Preconditions, permission requirement and the two error paths are all covered, which is everything needed to invoke this mutation 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 the baseline is 3; the description still earns a bump by hammering the counter-intuitive point that `ruleset` never retargets and only acts as a confirmation that errors on mismatch. It clarifies intent rather than adding 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?

Specific verb + resource ('Add a vault item to a campaign's allowlist') that cleanly separates it from the many play_add_campaign_* siblings (spell, rule, character, leg). An agent knows exactly what is being added and to what container.

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 the operative preconditions: the campaign must already have a leg for the item's ruleset, and the caller must hold 'contribute'. It does not, however, name when to prefer this over sibling allowlist tools or what to do instead when the leg is missing (e.g. call play_add_campaign_leg).

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 that the new leg starts empty (no rules/items/spells/characters), that duplicate ruleset legs yield a 409, and that the caller must be the owner or an accepted gamemaster or receive a 403. These are exactly the preconditions and side effects an agent needs for a non-idempotent mutation.

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 action, then the empty-leg behavior, then the constraint and auth in a compact, well-ordered three-sentence block with no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation; the description covers authorization, emptiness, and the duplicate-ruleset error path, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the 400/403/409 error conditions for the ruleset code. The description only restates 'for the given ruleset' and the 409, adding little beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a new active leg to a campaign for the given ruleset') and explains the concept of a 'leg' as the same campaign running under another ruleset. This clearly distinguishes it from the sibling add tools (play_add_campaign_rule/item/spell/character) which fill the leg rather than create it.

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 scenario for the call and routes the agent onward ('fill it with the add tools'), and gives the selection constraint 'one leg per ruleset'. It does not name an explicit alternative tool, but there is no direct competing tool, so the context 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 the write/safety profile (readOnly=false, destructive=false, idempotent=false), so the description only needs to add context — and it does: the leg-matching rule, the 400 failure mode, and the required 'contribute' permission. Non-obvious behavior around the ruleset param is disclosed well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the action, then leg behavior, param semantics, and permission. Every sentence carries distinct information 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?

With an output schema present, return values needn't be described. The description covers placement behavior, error conditions, and authorization, 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 the baseline is 3. The description restates the ruleset confirmation semantics that the schema already documents in full; it adds emphasis but little new meaning beyond the structured field.

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 ('Add a vault rule to a campaign's allowlist'), which is unmistakably distinct from siblings like play_remove_campaign_rule or play_add_campaign_item. An agent can identify the operation 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 clear preconditions: the campaign must have a leg matching the rule's own ruleset, and the caller needs 'contribute'. It stops short of naming an explicit alternative or exclusion, but the situational context is strong.

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 (which only declare readOnly=false, destructive=false, idempotent=false, openWorld=true), the description adds the leg-placement rule, the two 400 failure conditions, and the required 'contribute' permission. It does not address what happens on a duplicate add (relevant given idempotentHint=false), leaving a modest gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place, with the core action front-loaded and the constraints on ruleset and permissions following in priority order. 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?

With 100% schema coverage, an output schema present, and annotations covering the safety profile, the description supplies the remaining behavioral essentials (placement rule, error triggers, permission). Only the duplicate-add / non-idempotent behavior is left unstated.

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

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

Schema description coverage is 100%, so all three params are already documented. The description's explanation of the optional `ruleset` param as confirm-only largely restates the schema text rather than adding new syntax or format detail. 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 and resource ('Add a vault spell to a campaign's allowlist'), which is clearly distinct from the sibling play_remove_campaign_spell and play_list_campaign_spells. An agent can identify the operation without consulting 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 operational conditions: the spell lands on the leg matching its own ruleset, the campaign must have that leg or play answers 400, and the caller needs 'contribute'. It does not explicitly contrast with siblings like play_add_campaign_item or state when-not to use it, so it falls short of a 5.

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

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

Annotations already mark the operation as destructive and idempotent. The description adds meaningful behavioral context beyond those hints: it can only cancel requests the calling user initiated, and it targets the friend record on the user's own friends list, not the other user's id. This helps the agent avoid common misuse.

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 focused sentences with no filler. The action and the key disambiguation are front-loaded, and the parameter guidance is placed exactly where it is relevant.

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, output-schema-bearing mutation tool with annotations covering destructiveness and idempotency, the description is complete. It identifies the target, the required parameter, how to source that parameter, and the boundary of what it can cancel.

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 value by emphasizing that friendId is the friend record on the caller's own friends list and specifically the one the caller initiated, and by directing the agent to the sibling list tools that produce this value. This goes slightly beyond the schema's own wording.

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 ('Cancel') and resource ('a friend request the calling user previously sent'), and clarifies scope by noting it must be a request the calling user initiated. This clearly distinguishes it from siblings like play_accept_friend_request, play_decline_friend_request, and play_remove_friend.

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 indicates when the tool applies (only to requests the calling user previously sent) and the parameter description points to play_list_pending_friends and play_list_my_friends as sources for the required friendId. It does not explicitly state when NOT to use this tool versus decline or remove, but the caller-initiated qualifier largely disambiguates.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description is not burdened with those. It adds value by stating it's a 'cheap boolean check' and scoping to the 'calling user' and 'active player-recap page,' which are behavioral details beyond the schema. It does not mention error conditions, but given the simplicity and annotation coverage, this is acceptable.

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 sentences with zero waste. The core purpose and return shape are front-loaded in the first sentence, and the usage guidance in the second. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple existence check with one well-documented parameter, annotations covering safety, and an output schema hinted in the description, nothing essential is missing. The description covers the return value, scope, and intended usage context.

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% for sessionId, so the schema fully documents the parameter. The description does not add any extra semantics beyond what the schema provides, thus the baseline score of 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 description clearly states a specific verb (check) and resource (recap existence) with a precise return contract ({ exists: boolean }). It differentiates itself from siblings like play_create_page by focusing on the read-only existence check, leaving no ambiguity about its function.

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 when to use it: 'Use this to gate play_create_page so you don't write a duplicate recap.' This names the alternative tool and the condition that selects this check, providing direct and unambiguous guidance.

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

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

Annotations already establish this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context beyond annotations: it marks emails as consumed, links them to a move, restricts effects to 'new' items, and notes GM-only access. 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?

Three sentences with zero fluff: action, usage timing, and scope condition. The core function is front-loaded, and every sentence earns its place. The GM-only note is concise and 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?

For a simple 2-parameter tool with an output schema and annotations, the description covers when to use, what it does, and its scope. It could clarify what 'consumed' means for the inbox (e.g., removal vs. archiving) or define 'new', but these are minor given the output schema likely conveys return state.

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 fully documented. The description adds a behavioral constraint ('Only new items... affected') that indirectly relates to itemIds, but it does not add parameter-specific meaning beyond schema. 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 description states a specific action ('Mark inbox emails consumed and link them to the move'), a clear resource and target, and the use context ('after play_create_move / play_update_move'). It distinguishes from sibling PBEM tools by specifying 'consumed' and 'collated into', which implies a state change tied to a move rather than simple dismissal or resolution.

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 tells the agent when to use the tool: after play_create_move/play_update_move when building a move from emails. It also gives a scoping condition ('Only new items... affected'). It does not list alternatives or explicit when-not-to-use scenarios, but the context is clear enough for correct routing.

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, non-idempotent, non-destructive, open-world write. The description adds meaningful specifics beyond that: ownership semantics, that 'ruleset' is materialized as a leg, and that Play validates the payload (400 for missing/unknown ruleset, 403 for unentitled ruleset). It does not cover reversibility or rate limits, so it stops short of the top score.

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 tight sentences, front-loaded with the operation and the required field, then the leg/validation detail. Slightly dense in the middle clause about legs, but 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 10-parameter creation tool, it covers purpose, required field, the non-obvious leg mechanic, and backend failure modes, while an output schema exists so return values need no prose. Annotations carry the safety profile. Only unusual params like hideSections/xCardEnabled are left to the schema.

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

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

Schema description coverage is 60%, so the schema documents about half the parameters. The description compensates by explaining the pass-through contract for summary/description/settings and the leg behavior plus backend error codes for ruleset, adding real meaning beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new campaign') plus scope ('owned by the calling user'), which cleanly separates it from play_update_campaign, play_delete_campaign, and the imagine_create_* siblings. An agent can identify the operation 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?

Explains the setup context: required 'name', and that 'ruleset' becomes the campaign's first leg with more legs added via play_add_campaign_leg. It names the follow-up tool but does not state exclusions or when a different creation path (e.g. imagine_create_adventure) would be preferred.

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 annotations provide only false hints, so the description carries most of the behavioral disclosure burden. It does so well by revealing the GM-only requirement, defaulting behavior for name/number/date, and visibility restrictions via playerIds. It does not describe the response shape, but an output schema exists, and the description does not contradict any annotation.

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 compact and well organized: a one-line purpose, then required vs. optional parameters, then the GM-only constraint. Every sentence earns its place, and the core action is front-loaded. There is no filler or redundancy.

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 creation tool, the description together with the fully covered schema and output schema gives an agent everything needed to call it correctly: required campaignId, default behaviors, key constraints, and authorization. Nothing essential 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%, with detailed parameter explanations already present, so the baseline is 3. The description condenses important information such as 'parentId (child scene; excludes sessionId)' and 'playerIds (visibility restriction)', but it mostly mirrors the schema rather than adding new semantic meaning. It is useful for quick scanning but does not materially extend 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: 'Record a new play-by-email move on a campaign.' This clearly distinguishes it from sibling tools like play_create_session or play_create_page, and the PBEM qualifier makes the domain explicit. Even without reading the schema, an agent knows exactly what artifact this tool creates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: creating a new move, with campaignId required. It also gives an important exclusion (parentId excludes sessionId) and a caller restriction (GM-only: campaign owner or accepted gamemaster). However, it does not explicitly name alternatives such as play_update_move for editing existing moves, so it falls just short of the top bar.

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