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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds valuable context: ownership by the calling user, the lack of a default ruleset, and pass-through behavior for other fields. 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?

Three sentences, front-loaded with the core operation, then required fields, then a short pass-through note. Every sentence earns its place; there is no filler or repetition of schema/annotations.

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 empty input schema, the description covers ownership, required fields, and the no-default ruleset rule; output schema exists so return values do not need explanation. The phrase 'other fields pass through to imagine' is somewhat vague, leaving some ambiguity about accepted input structure.

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 has zero documented properties, so the description carries the full burden of parameter education. It names the required parameters (name and ruleset) and notes that other fields pass through, but it does not specify types, formats, or how pass-through fields are represented.

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 and resource: 'Create a new adventure,' and adds ownership context ('owned by the calling user'). It clearly distinguishes this from sibling tools like imagine_create_adventure_page or imagine_create_world by naming the resource and its required fields.

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 conditions for invocation: name and ruleset are required because there is no app-wide ruleset default for adventures. It does not explicitly name alternatives or state when not to use this tool, so exclusion guidance is missing.

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

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

Annotations already establish that this is a non-read, non-destructive, open-world operation. The description adds useful behavioral details beyond that: required fields (adventureId, name), the tags array for filterability, and the automatic addition of documentType to the searchable keyword set. It does not address auth or side effects, but it goes well beyond what annotations alone 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 efficiently structured and front-loaded with the action and required fields. The list of valid documentType values is lengthy but necessary, and every sentence adds operational value. A slight tightening could combine the use-case and negative-guidance sentences, but there is no wasted 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?

Given the empty schema, the description covers all core invocation concerns: required parameters, valid enum values, intended use cases, excluded page types, and the tagging/keyword behavior. With an output schema presentatoire, the absence of return-value detail is not a gap. The agent can select and call this tool correctly based solely on the description.

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 is empty, so the description is the only source of parameter knowledge. It compensates fully by naming the required parameters (adventureId, name), enumerating valid documentType values, explaining the tags array use, and explicitly excluding items/rules as page types. This gives the agent everything it needs to construct a valid call despite the empty schema.

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

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

The description states a specific verb and resource: 'Create a new page inside an adventure.' It also lists concrete use cases (scene descriptions, encounter rooms, NPC profiles, plot beats) that distinguish it from related tools like world-page creation. The negative guidance about items and rules further disambiguates the tool's scope.

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 this tool ('Use this for scene descriptions, encounter rooms, NPC profiles, plot beats') and when not to ('Items and rules are NOT page types'). It names the alternative approach: author those in the vault and reference them, not as adventure pages. This gives the agent clear routing guidance without needing to inspect other tools.

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

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

Annotations already indicate this is a non-read-only, non-idempotent mutation, and the description adds that the world is owned by the calling user and that fields pass through to imagine for validation/defaulting. It also discloses a non-obvious data-model behavior: worlds do not carry a ruleset, rulesets live on adventures. 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?

Three tight sentences front-load the action first, then add required/optional fields and one clarifying domain rule. There is no filler and no unnecessary repetition of annotation 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 description covers ownership, required input, and the world/adventure ruleset relationship, and an output schema exists to explain return values. However, the input schema declares an empty object while the description says `name` is required, leaving an agent with contradictory invocation guidance. It also omits what defaults 'imagine' assigns and any error conditions.

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?

Even though the input schema has zero properties, the description identifies `name` as required and `summary`, `description`, and `link` as additional pass-through fields, which is essential semantic content the schema lacks. It does not provide types or format details, but with 0 schema params this meaningfully exceeds the baseline.

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

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

The first sentence uses a specific verb ('Create') and resource ('new world') and adds ownership ('owned by the calling user'). This distinguishes it from siblings like imagine_create_world_page and imagine_create_adventure by naming the exact resource being created. The final sentence further clarifies the world-vs-adventure 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 states what the tool does and gives a structural hint that adventures live under worlds, which helps sequencing. However, it never explicitly says when to prefer this tool over imagine_create_adventure or imagine_create_world_page, and it gives no exclusions or prerequisites beyond the required name.

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 important side effects: 'gm' pages 404 and disappear from lists for non-contributors, 'masked' pages still appear in lists/backlinks under a maskName, and documentType is auto-added to searchable keywords. These details are not visible in the annotations 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?

Long and information-dense, with each clause carrying distinct value. It could be structured more scannably, but no sentence is wasted and the most critical info (required fields and purpose) appears early.

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 creation tool with an empty input schema, the description is unusually complete: required parameters, optional parameters, enums, cross-tool tag integration, visibility side effects, and exclusion rules are all covered. An output schema is present, so omitting the return shape 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?

The input schema is empty, so the description is the only source of parameter meaning. It defines required worldId and name, enumerates all valid documentType values, explains the tags array behavior, and details visibility and maskName semantics. This fully compensates for the empty schema.

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

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

States a specific verb and resource: 'Create a new page inside a world.' It enumerates intended content types (NPCs, locations, organizations, events) and explicitly excludes items/rules, drawing a clear boundary against sibling tools like imagine_create_world and imagine_create_adventure_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?

Provides explicit when-to-use guidance: valid documentType values are listed, items and rules are routed to vault instead of world pages, and the tag mechanism is tied to a specific sibling tool, imagine_list_world_pages_by_tags. Visibility modes also give conditional usage instructions.

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

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

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 signal non-readOnly, non-idempotent, non-destructive behavior. The description adds substantial context: the two-way write to `imagineAdventures[]`, the backing of the session Adventure tag, caller permission requirements, and the 400 duplicate-link error. This far exceeds what annotations alone 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?

Every sentence earns its place: the core mutation, the mirror side effect, auth constraints, the duplicate error, and the prerequisite lookup. The description is dense but well-ordered, front-loading the primary action and then layering important caveats.

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 operation's side effects, permissions, failure mode, and prerequisite step. Since an output schema exists, return-value documentation is not the description's burden. Nothing critical is missing for an agent to select and 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 coverage is 100%, so the schema already documents both `id` and `campaignId` with meaningful descriptions. The main description adds operational context around the parameters but does not need to compensate for missing schema detail, keeping this at the baseline.

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

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

The description uses a specific verb ('Add') and a precise resource ('a play campaign to an adventure's `playCampaignIds[]`'), making the operation concrete. The two-way mirror behavior further distinguishes it from related sibling tools like `imagine_unlink_adventure_from_campaign` and `imagine_link_world_to_campaign`.

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 preconditions: confirm the link does not already exist, be ready for a 400, and locate the campaign id via `play_list_my_campaigns`. It does not explicitly name alternative tools like the unlink sibling, but the usage context is otherwise strong enough to guide an 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?

The description adds substantial behavior beyond annotations: it explains the two-way call flow, that the controller writes to playCampaignIds[], that characters are imported by default, that duplicates cause a 400, and that edit access on the world is required. This is exactly the kind of side-effect and error-context information an agent needs.

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

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

Every sentence in the description earns its place: the core action, the two-way mechanism, the default import behavior, the duplicate-error condition, and the access requirement. It is dense but well structured and front-loaded with the primary 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?

The description covers what the tool does, how it behaves, when to call it, what could go wrong, and the required permission. The output schema is available, so not describing the success return is acceptable. The combination of annotations, schema, and description is complete for invoking 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 coverage is 100%, so the schema already documents all parameters. The description adds extra value by clarifying that importCharacters defaults to true and controls character ref import, and by tying campaignId to a play campaign. This meaningfully goes beyond the raw schema descriptions.

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

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

The description uses a specific verb and resource, 'Link a play campaign to a world', and adds meaningful detail about the two-way sync and character import behavior. It is clearly distinguished from sibling tools like imagine_unlink_world_from_campaign and imagine_link_adventure_to_campaign by naming the exact objects involved.

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

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

The description gives explicit call conditions: only call after confirming the link doesn't already exist, or be prepared to handle a 400. It also explains when to set importCharacters to false. It does not explicitly compare against the sibling link tool for adventures, but the guidance is otherwise clear and 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 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?

Annotations indicate mutating, idempotent, and non-destructive, but the description adds critical context beyond annotations: the two-way mirror removal and the session tag behavior (left inert, re-lit on re-link). It also discloses the authorization requirement. No contradiction with annotations; this fully informs the agent 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?

Four sentences, each packed with essential information: core action, inverse, two-way mirror behavior, and authorization. No filler, front-loaded with the primary action. Excellent structure.

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-way link removal with mirror effects and session tag nuance, the description is complete. It covers prerequisites, side effects, and the inverse. An output schema exists, so return value explanation is unnecessary. Nothing essential is missing 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?

Schema description coverage is 100% and both parameters are well-described in the schema (adventure _id, campaign _id with source). The description does not add extra parameter-specific semantics beyond the schema, 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?

The description states a specific verb ('Remove'), the resource (adventure's playCampaignIds[]), and the inverse relationship to imagine_link_adventure_to_campaign. It distinguishes itself clearly from the sibling link tool and other unlink tools by naming the exact array and the two-way mirror behavior.

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 states prerequisites: caller must be campaign owner/gamemaster and have edit access on the adventure. It identifies itself as the inverse of the link tool, which implies when to use. However, it does not explicitly contrast with other unlink tools (e.g., imagine_unlink_world_from_campaign) or state when not to use it, so a 4 is appropriate.

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 goes well beyond the annotations, disclosing the ordering of side effects ('clears the link on play's side first, then on imagine's side'), the optional house-rule cleanup behavior controlled by `removeSyncedHouseRules`, and the caller permission requirement. This gives the agent a realistic model of what will happen during invocation.

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 filler. Purpose comes first, followed by side-effect ordering, optional parameter guidance, and the access prerequisite. 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 link-unlink operation, the description covers the action, side-effect order, optional cleanup, and access requirement. An output schema exists, so return-value details are unnecessary, and the operation's idempotent nature is already captured in annotations. 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?

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema; the 'two-way' ordering is behavior rather than parameter semantics, and the `removeSyncedHouseRules` explanation largely echoes 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 opens with a concrete verb and resource: 'Unlink a play campaign from a world.' This clearly distinguishes it from the sibling adventure-unlink tool by specifying 'play campaign' and 'world' as the objects involved, so an agent can identify the correct 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?

The description establishes clear context for use: it unlinks a play campaign from a world, and it notes the two-way nature of the operation and required 'edit' access. It does not explicitly name alternative tools, but the resource nouns make the intended scenario obvious enough that the agent can route correctly.

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

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

The description richly discloses behaviors beyond the annotations: partial update semantics, required 'edit' permission, parent grouping/ungrouping rules, rename propagation with non-blocking push and potential stale mirror state, and OUT_OF_SYNC rejection on stale baseUpdatedAt. No contradiction with annotations 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?

The core action is front-loaded, and every subsequent sentence addresses a distinct critical behavior: permissions, grouping, rename side effects, and concurrency guard. The description is dense but 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?

Given an output schema exists and annotations cover the read/write safety profile, the description supplies everything else needed for correct invocation: authorization, concurrency requirements, side effects, and validation pointers. An agent can call this tool correctly with high confidence.

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 has no properties, so the description carries the full parameter burden. It explains id, parent (including null for ungrouping), baseUpdatedAt/updatedAt usage, and points to validation rules and ordering defaults. This is far more useful than the empty schema alone.

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

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

The description opens with a specific verb and resource: 'PUT updates to one adventure by id.' This clearly distinguishes the tool from imagine_update_adventure_page and imagine_update_world, and the scope ('one adventure') is 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 usage context is clear: this is the tool for updating an adventure, with explicit requirements like caller permission and a fresh baseUpdatedAt from imagine_get_adventure. It does not explicitly name alternatives or state when not to use it, but the resource-specific framing makes selection straightforward.

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 major behavioral traits: only supplied fields are sent, the body is fully replaced, baseUpdatedAt is required, stale/fabricated values cause OUT_OF_SYNC and no write, and special fields like read-aloud/moving-on/tactics are not fields but inline callouts. This greatly exceeds the annotation-provided safety profile.

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 almost every sentence conveys necessary operational or safety-critical information. The field enumeration is a bit exhaustive, and the warning section could be tightened, but the structure is logical: purpose, updatable fields, special syntax, permissions, critical replacement warning, and concurrency requirement.

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 zero schema parameters, this description covers all necessary context: target resource, auth requirement, full field list, special inline syntax, destructive replacement behavior, concurrency control, and explicit alternatives. An agent could correctly invoke this tool with only the description and a fresh read of the page.

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 is empty, so the description carries the entire parameter burden. It lists every updatable AdventurePage field and explains the required baseUpdatedAt parameter, its source, and why it matters. This is far more than the schema alone 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 opens with 'PUT updates to one adventure page by id', which states a specific verb, resource, and mode of operation. It also enumerates exactly which fields are updatableament and explicitly names related sibling tools (imagine_replace_in_adventure_page, imagine_get_adventure_page), so the agent can distinguish it from similar 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?

It gives explicit when-to-use guidance: use the surgical sibling for fixing wording, fetch-then-send for appending, and this tool for full field updates. It also states required permissions ('Caller must have 'edit'') and warns against writing from memory. This leaves little ambiguity about when to select this tool versus alternatives.

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

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

Beyond the annotations, it reveals the merge behavior ('only supplied fields... merges them'), the optimistic concurrency requirement, and the failure mode (OUT_OF_SYNC, nothing written). This is exactly the behavioral context that helps an agent predict consequences and is consistent with the readOnlyHint=false and destructiveHint=false 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?

Every sentence is load-bearing and the core action is front-loaded. The description packs access control, merge semantics, and concurrency behavior into four short sentences 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?

The definition covers access, update mechanics, required optimistic-lock field, stale rejection, and no-write-on-failure. The only minor gap is that the world id itself is not specified as a literal input key, and updatable world fields are left to inference, but these are recoverable from the tool name and the referenced get_world read.

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 an empty input schema, the description is the only source of parameter meaning, and it clearly names the required baseUpdatedAt field and its value source. It does not enumerate other updatable fields or the exact key for the world id, but the merge semantics plus openWorldHint make the rest inferable from the world document returned by get_world.

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

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

The opening clause 'PUT updates to one world by id' names the verb, the resource, and the identifying scope in one compact sentence. This clearly differentiates it from the sibling update tools for adventure, adventure_page, and world_page without needing to compare 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 states the authorization precondition ('must have edit access') and gives a precise usage requirement: copy updatedAt from a fresh imagine_get_world read and supply it as baseUpdatedAt. It does not explicitly list alternatives or when-not-to-use, but the context is clear enough that an agent can decide to call this tool for world updates.

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 critical behavioral traits beyond annotations: it REPLACES the content body, requires baseUpdatedAt to be fresh (stale/fabricated values rejected with OUT_OF_SYNC), and explains the exact behavior of visibility settings (gm, masked, public) including that hidden pages are stripped from the world menu. This is rich behavioral context that annotations alone don't provide. The annotations (readOnlyHint=false, idempotentHint=true) are consistent with the description's PUT semantics.

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-structured: it front-loads the core operation, then explains the replacement behavior, the baseUpdatedAt requirement, and visibility options. Every sentence adds value, though the visibility section is somewhat long. It's appropriately sized for the complexity of the tool.

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

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

The description is complete for a complex update tool. It covers the replacement semantics, the concurrency requirement (baseUpdatedAt), the visibility options, and the append workflow. The output schema exists, so return values don't need explanation. The description gives an agent everything needed to call this tool correctly without guessing.

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 has zero parameters, so the description carries the full burden of explaining what fields the caller must supply. The description explains the key fields: content body, baseUpdatedAt, and visibility. However, it doesn't enumerate all possible fields (e.g., name, maskName) explicitly, though it mentions maskName in the visibility explanation. With 0 params in schema, baseline is 4, and the description adds substantial meaning about the required fields.

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

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

The description clearly states the operation: 'PUT updates to one world page by id.' It specifies the resource (world page), the method (PUT), and the scope (one page by id). It also distinguishes itself from siblings like imagine_update_world and imagine_update_adventure_page by explicitly naming the resource type.

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 explicit when-to-use guidance: it explains that to append content, you must first fetch the page with imagine_get_world_page, concatenate, and send the combined body. It also states the requirement for baseUpdatedAt from a fresh read, and explains the visibility options. This is strong usage guidance that tells the agent exactly how to use this tool correctly.

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

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

Annotations already declare 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?

Annotations indicate a non-read-only, non-idempotent, non-destructive operation (write). The description adds valuable behavioral details: the item always lands on a specific leg per the item's own ruleset, a mismatched ruleset confirms via 400, and the caller must have a specific permission. It also clarifies that the ruleset param never retargets. These go beyond annotations and help the agent predict outcomes and errors.

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 tight and front-loaded. The primary action is in the first sentence, followed by two concise sentences that cover the most critical behaviors (leg matching, ruleset confirmation, permission). No filler, no redundancy beyond the schema's own param descriptions, 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?

The description covers the core behavior, error conditions, and authorization, which is sufficient for an add operation. It does not address possible duplicate handling or idempotency, but the presence of an output schema and annotations reduces the burden. It's reasonably complete, with minor gaps around edge cases like re-adding an existing item.

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 well-documented. The tool description essentially repeats the schema's explanation of the ruleset parameter (confirm-only, mismatch → 400) without adding new meaning. While it reinforces the behavior, it does not elevate parameter understanding beyond what the schema already provides, matching the baseline for high coverage.

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

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

The description states a clear, specific action: 'Add a vault item to a campaign's allowlist.' It identifies the resource (vault item), the destination (campaign's allowlist), and immediately provides a critical behavioral nuance (landing on the leg matching the item's own ruleset). This distinguishes it from sibling tools like play_add_campaign_character or play_add_campaign_rule by resource type, even without 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 description gives important usage context: the campaign must have a leg for the item's ruleset or the call fails with 400, and the optional ruleset param is purely confirmatory. It also states the required permission ('contribute' on the campaign). However, it does not explicitly mention when to prefer this tool over other add_campaign_* tools, nor does it list any exclusions, so it's not a full when/when-not guide.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable behavioral context: the new leg starts empty, one leg per ruleset with 409 on conflict, and permission requirements (403 for ordinary players). It doesn't contradict annotations. It could mention what the response contains, but the output schema 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?

Three sentences, each earning its place: what the tool does, what the new leg starts as, and the key constraints (one leg per ruleset, permissions). Front-loaded with the core action and resource.

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 2-parameter tool with 100% schema coverage, an output schema, and annotations covering safety, the description is complete. It explains the concept of a leg, the empty start state, the uniqueness constraint, and permission requirements. An agent has everything needed to select and 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 schema already documents both parameters. The description adds context about the ruleset parameter's uniqueness constraint (409 if leg exists) and clarifies that campaignId is the target campaign. This goes slightly beyond the schema, but the schema already carries most of the 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?

The description clearly states the verb ('Add'), the resource ('a new active leg to a campaign'), and the specific purpose ('letting the same campaign also run under that ruleset'). It distinguishes itself from sibling tools like play_set_campaign_leg_active and the other play_add_campaign_* tools by explaining what a leg is and that it starts empty.

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 this tool (to add a leg for a ruleset), what the new leg starts as, and the constraint 'One leg per ruleset' with the 409 behavior. It also states who can call it (campaign owner or accepted gamemaster) and that ordinary players get 403, which is clear 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?

Beyond the annotations (which signal a non-read-only mutation but nothing else), the description discloses real behavioral details: automatic leg placement, two specific 400 scenarios, the no-retargeting semantics of ruleset, and the required permission. This is exactly the kind of context that prevents an agent from misusing the tool. It is consistent with annotations, so there is 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?

Three sentences deliver the core action, the critical placement behavior, the error conditions, the optional parameter semantics, and the permission requirement. Information is front-loaded and every clause earns its place. There is no filler or repetition of schema/annotations.

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 add-operation with an output schema and clear annotations, the description covers the prerequisites (leg exists), the caller permission, the exact failure modes, and the optional parameter's effect. Nothing needed to invoke the tool correctly appears to be missing. The success return is already covered by the output schema, so its omission is appropriate.

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

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

Although the schema already covers 100% of parameters, the description adds meaning beyond the raw field docs: it explains that ruleset is only a check and 'never retargets', and that ruleId refers to a vault rule whose own ruleset governs placement. This turns a generic 'optional confirmation' schema field into an actionable behavioral contract. It reinforces campaignId's role as the target allowlist.

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: 'Add a vault rule to a campaign's allowlist,' and immediately clarifies the unique placement rule ('lands on the leg matching the RULE's own ruleset'). This clearly distinguishes it from related campaign/vault tools like play_add_campaign_item or vault_create_rule. It also names the permission and failure mode, pinning down the exact 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 gives strong contextual guidance: the campaign must have a leg for the rule's ruleset, the optional ruleset param is only a confirmation, and the caller needs 'contribute' permission. It does not explicitly name sibling alternatives or state 'use this when ... instead of ...', but its conditions make the intended usage unmistakable. No misleading exclusions are present.

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

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

Beyond the annotations, the description discloses the non-retargeting leg placement rule, two 400 error cases, and a specific auth requirement. This is meaningful behavioral context that the structured 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?

Four short sentences, each carrying load: action, placement rule, ruleset caveat, and auth requirement. The main behavior is front-loaded and there is 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 mutating tool with full schema descriptions and an output schema, the description covers prerequisites, failure conditions, auth, and edge-case behavior. Nothing essential is missing for an agent to use 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% and the ruleset property already explains its confirmation-only role and mismatch behavior. The description restates this caveat rather than adding new parameter semantics, so the baseline 3 applies.

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

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

The description opens with 'Add a vault spell to a campaign's allowlist', clearly naming the verb, resource, and destination. This differentiates it from sibling add-to-campaign tools (item/rule/character) and from the inverse removal tool.

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 preconditions: the campaign must already have a leg for the spell's ruleset or a 400 is returned, and the caller needs 'contribute' permission. It also clarifies when to use the optional ruleset param, though it does not explicitly contrast with sibling add tools.

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

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

Annotations already 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 mark this as a mutating, non-idempotent creation with openWorldHint. The description adds ownership semantics, the rule that ruleset forms the first leg, and that other fields pass through to play for validation—useful behavioral context beyond 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?

The description is three dense sentences with no filler, front-loading the core purpose and required parameter before the leg/validation context. Every sentence contributes essential information.

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

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

For a create operation with an output schema and annotations, the description covers ownership, required input, the ruleset-specific leg model, and validation. The only minor gap is not detailing potential validation errors or how settings should be structured, but these are not essential for invoking the 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?

The input schema exposes no properties, so the description carries full responsibility for parameter information. It identifies name as required, explains the ruleset leg behavior, and lists summary, description, and settings as pass-through fields—substantial semantic value.

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

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

The description uses a specific verb+resource ('Create a new campaign') and adds that it is owned by the calling user. This clearly differentiates it from sibling create tools like play_create_session or play_create_page, and the campaign concept is 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?

It states the required name, explains the special ruleset leg behavior, and explicitly points to play_add_campaign_leg for adding more legs. It does not explicitly enumerate when not to use it (e.g., updating an existing campaign via play_update_campaign), so it misses a small exclusion.

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?

With all annotations false, the description carries the behavioral burden. It discloses defaults (name, number, date), mutual exclusion (parentId excludes sessionId), visibility restriction (playerIds), and authorization (GM-only). This goes beyond the minimal 'create' implication, though it doesn't cover failure modes or idempotency.

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 with no filler. It front-loads the core action, then clearly separates required, optional, and authorization details. Every sentence adds necessary information about how to call the tool correctly.

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, the description covers all needed context: required vs optional parameters, defaults, exclusivity rules, visibility, and caller restrictions. Nothing an agent needs to invoke it correctly is missing, and the output schema handles return-value documentation.

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 is empty, so the description is the only source of parameter information. It lists every parameter with defaults, constraints, and relationships (e.g., parentId excludes sessionId). This fully compensates for the absent schema and earns the highest 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 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_update_move, play_delete_move, and play_get_move, which concern modifying, deleting, or retrieving moves.

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: it is for creating a new move, requires campaignId, and is GM-only. It does not explicitly name alternatives for editing or listing moves, but the 'new' qualifier and required/auth conditions give strong contextual 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?

The description discloses the notification side effect on recap creation, which is beyond what the annotations convey (readOnlyHint false, idempotentHint false). It also mentions the prerequisite check. There is no contradiction with annotations. It could mention other side effects, but the key behavioral trait is well covered.

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 bit lengthy but every sentence contributes: the core action, the required parameter, the recap configuration, the side effect, and the prerequisite. It is front-loaded with the primary purpose and does not waste words. Could be tightened slightly, but it remains effective.

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?

While the description covers the recap use case and prerequisite, the empty input schema leaves the actual parameter contract undefined. An agent cannot reliably know whether to pass `name` or the recap fields, making the tool incomplete for correct invocation. The description also does not mention other document types or general page creation semantics, so it is not fully contextual.

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 explicitly names required parameters (`name`) and optional fields (`documentType`, `ref`) for the recap scenario, which is valuable. However, the input schema is an empty object, creating a direct conflict: the schema implies no parameters are accepted, while the description requires `name`. This inconsistency is misleading and undermines the parameter semantics, as an agent might not pass `name` due to the schema or might pass it and have it ignored. The description does not resolve this contradiction.

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 'create' and the resource 'page', and it distinguishes the tool from siblings by describing the specific 'player-recap' use case and the side effect of notifications. An agent can tell this apart from play_update_page, play_delete_page, and play_get_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 explains when to use the tool (to create a page, especially a session recap) and gives a concrete prerequisite: call play_check_recap_exists first to avoid duplicates. This is clear, actionable guidance that leaves no ambiguity about the correct invocation path.

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

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

With no useful annotations (all false), the description carries the burden. It discloses that caller authorization is via campaign 'contribute' permission and that fields pass through to play. It doesn't mention return values or side effects beyond creation, but the output schema covers that. This adds meaningful context beyond the empty 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, no fluff. Purpose is front-loaded, then required/optional fields, then permission note. 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 empty schema and existing output schema, the description covers all necessary calling details: purpose, required fields with format, optional fields, and authorization. No critical information 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 input schema is empty ({}), so the description is the sole source of parameter information. It lists required parameters (campaignId, date) with date format, and optional ones (name, description, planned battlemaps). This fully compensates for the schema gap and adds precise semantics.

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

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

The description states a specific verb and resource: 'Create a new session for a campaign.' This clearly distinguishes it from siblings like play_create_campaign, play_create_move, or play_delete_session. The purpose is unambiguous and front-loaded.

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 its use case (creating a session for a campaign) and specifies required vs optional fields, but it does not explicitly contrast with alternatives such as play_update_session. The necessity is clear from context, but explicit exclusion of when-not-to-use is absent.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation nature. The description adds the constraint that the request must be pending and directed at the calling user, and specifies the exact source for the ID, giving operational context beyond the safety hints.

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

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

Two sentences with no filler: the first states the purpose, the second tells how to obtain the parameter. Purpose is front-loaded and 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?

This is a simple one-parameter tool with an output schema present. The description covers the operation, the origin of the required ID, and implicitly its scope (pending, calling user). Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, and the parameter description already includes the 'NOT the other user's id' clarification and the list-source guidance. The tool description's mention of friendId from play_list_pending_friends is redundant with the schema, so it adds minimal new 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 states a specific verb ('Decline') and resource ('pending friend request') scoped to the calling user, and the qualifier 'pending' plus the source list clearly differentiates it from accept, cancel, and remove siblings. An agent knows exactly what this tool does and how it differs from peers.

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 instructs to pass friendId from play_list_pending_friends, and the schema description reinforces that play_list_pending_friends is for accept/decline while play_list_my_friends is for remove, effectively routing the agent to the correct list and tool for this 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?

Annotations already flag destructiveHint=true, but the description adds crucial context beyond that: the operation is permanent, cascades to sessions/invites/members, requires specific permissions, and mandates user confirmation. This is exactly the behavioral disclosure an agent needs for a destructive call.

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: core action, cascade consequences, then permission and safety guidance. Front-loaded with the verb-resource pair and no wasted words.

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

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

For a one-parameter destructive operation with an output schema, the description covers what gets destroyed, the permission prerequisite, and the confirmation requirement. Nothing essential is missing 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?

Schema coverage is 100% with the single parameter id already documented as 'Mongo _id of the campaign.' The description adds no new meaning about the parameter itself, and the baseline 3 is appropriate when the schema carries the full weight.

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 'Permanently delete a campaign by id', using a specific verb and resource, and clearly distinguishes this from sibling delete tools for sessions, characters, pages, and moves. The cascade effect ('Removes all of its sessions, invites, and members') further defines the scope unambiguously.

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 actionable when-to-use context: the caller must hold campaign 'delete' permission (typically the owning DM), and the agent is instructed to confirm with the user first. It doesn't explicitly name alternatives, but the resource is unique among siblings, so no exclusion is strictly needed.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description carries a lower burden but still adds genuine value: it scopes the destruction ('removes campaign references but does NOT delete the underlying vault character document') and discloses the permission requirement. This is exactly the contextual enrichment the rubric asks for beyond 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, each earning its place: the core action, the scope boundary, and the permission gate. No filler, no repetition of schema content, no vague boilerplate.

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 full set of annotations, and an output schema present, the description covers everything an agent needs: what is affected, what is spared, and who is allowed to invoke it. 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 description coverage is 100%: the sole parameter `id` is already fully documented as 'Mongo `_id` of the play character record.' The description contributes no additional parameter syntax, format, or constraint details, so the schema carries the heavy lifting and 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 uses a specific verb-plus-resource construction ('Detach a character from play's tracking') and draws an explicit boundary against the destructive sibling 'vault_delete_character' by stating it does NOT delete the underlying vault document. An agent can immediately distinguish this from the many similar play_/vault_ 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?

The description gives clear invocation context: it names exactly what the operation does and doesn't do, which implicitly tells the agent when this tool is appropriate (detach tracking) versus deletion tools. The ownership/admin prerequisite is a concrete when-to-call condition. However, it never names a sibling alternative explicitly to complete the 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds substantial behavioral detail: deletion is permanent, collated round text is lost, child moves are detached back into the feed, and operator authorization is GM-only. This is exactly the context needed to use a destructive tool safely.

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 carrying essential information: the core operation, the side-effect on child moves, and the authorization/destructive warning. Nothing is redundant or padded.

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

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

With one fully documented parameter, a provided output schema, and rich annotations, the description still adds all necessary behavioral context: permanence, child-move behavior, GM restriction, lost text, and user confirmation. No relevant 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%: the only parameter, id, is already described as the Mongo _id of the move. The description confirms deletion happens 'by id' but adds no new parameter-level meaning 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?

The description names a specific verb and resource: permanently delete a move by its id. It also states the key nuance—child moves are detached, not deleted—which distinguishes it from related move/session 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?

The description clearly states when it applies (GM-only) and instructs the agent to confirm with the user first, which is critical usage guidance. It doesn't explicitly mention alternatives or excluded cases, but the GM-only gate and destructive warning provide clear 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?

The description goes far beyond the annotations by explaining that deletion is soft (30-day TTL via deactivated_at), recoverable in the UI, and permission-restricted. This adds significant behavioral context despite destructiveHint and idempotentHint already being present.

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, each carrying distinct information: operation, TTL/recovery, and authorization/confirmation requirements. No filler or redundant phrasing.

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 a full input schema and an output schema present, the description covers the essential decision factors: permission, destructiveness, confirmation, recovery, and soft-delete window. 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?

The schema fully documents the only parameter (Mongo _id of the page, minLength 1, required). The description merely repeats 'by id' without adding parameter-specific details, so it stays at 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?

States a precise action ('soft-delete a page by id'), the resource type, and key semantics (30-day TTL, recoverable). This clearly distinguishes it from hard-delete or other delete tools in the sibling list.

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 clear context on when it is appropriate to call: only for pages, owner/admin only, and with explicit user confirmation. It does not name alternatives like play_update_page or imagine_delete_world_page, but the conditions for use are explicit enough to prevent misuse.

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 destructive and read-only status, but the description adds concrete side effects (notes, session-image/battlemap attachments destroyed) and the permission requirement. This is exactly the extra context the rubric rewards.

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

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

Three short sentences, front-loaded with the main action and scope, then permissions and confirmation. Every clause adds a new piece of information with no 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?

A single parameter, a clear side-effect list, permission requirements, and confirmation guidance make the description self-sufficient. The output schema exists, so return-value details are unnecessary.

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 100% of the single id parameter with a description ('Mongo _id of the session'). The description repeats 'by id' but does not deepen the semantics, 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?

Clearly states the specific action ('delete'), the resource ('session'), and the identifier ('by id'), and enumerates included side effects like notes and attachments. This distinguishes it from sibling delete tools by naming the exact resource type.

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 clear context: the required permission ('contribute') and the instruction to confirm with the user first. It does not explicitly list when-not-to-use or name alternative tools, so it stops short of the 5 threshold.

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 explains what actually happens: mail stops routing, bounces at the webhook, and the address is kept and can be re-enabled unchanged. This aligns with destructiveHint=false and idempotentHint=true while adding meaningful operational detail.

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 deliver the action, the behavioral consequence, the preserved state, and the permission requirement. Every sentence earns its place and the key 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 one-parameter tool with an output schema and supportive annotations, this description is complete: it states who can use it, what happens to incoming mail, and what happens to the address. No critical decision-making 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 description coverage is 100%, so the single campaignId parameter is already fully documented in the schema. The description adds no additional parameter-level meaning beyond tying the action to 'the campaign's address,' which is appropriate given the baseline.

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