Embers: Tabletop RPG Toolkit

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the schema carries the parameter details. The description still adds value by naming the required parameters in order and clarifying that attachments must be IDs from upload_submission_screenshot, a relationship not fully expressed in the schema.

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

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

The description leads with a specific verb and resource: 'File a bug report or a feature request with Embers...' and explicitly distinguishes the two type values. This makes the tool's purpose unmistakable and sets it apart from tracking tools like get_submission and list_my_submissions.

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

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

The description gives clear context for when to use it: to file a bug or request on the user's behalf. It also points to upload_submission_screenshot for attachments and to get_submission/list_my_submissions for tracking, but it does not explicitly state when not to use it or mention reply_to_submission as the follow-up alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing the safety profile. The description adds meaningful behavioral context by specifying the exact contents returned (original report, screenshots, current status, activity feed with replies and status changes) and the access restriction. This goes beyond what annotations provide.

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

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

The description is a single, information-dense sentence that leads with the core purpose, then details the return contents, the source of the parameter, and the restriction. Every clause earns its place, and there is no filler or redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Two sentences, no wasted words, and the most important information is front-loaded. The ownership, required fields, and ruleset caveat are all stated efficiently.

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

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

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

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

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

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

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

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

The first sentence states a specific verb ('Create'), a unique resource ('adventure'), and scoping ('owned by the calling user'), making it easy to distinguish from sibling tools like imagine_create_world and imagine_create_adventure_page. The required-field note reinforces the core action without blurring the purpose.

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

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

The description clearly establishes the context: use this when creating a new adventure for the calling user, and it calls out the ruleset requirement and the lack of a default. It does not explicitly name alternatives for when not to use this tool, so it falls just short of a 5.

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

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

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

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

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

The description is front-loaded with the core action and required fields, and most sentences earn their place by adding use cases or exclusions. The only mild redundancy is restating the documentType enum that already exists in the input schema, but it remains compact and scannable.

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

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

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

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

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

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

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

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

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

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

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

The description explicitly says when to use the tool and gives an exclusion with routing guidance: 'Items and rules are NOT page types; author them in vault and reference them, not as adventure pages.' This tells an agent both what this tool is for and when to choose an alternative.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds genuine context beyond them: the created object is owned by the caller, the extra fields are passed through to imagine for validation and default assignment, and worlds deliberately carry no ruleset.

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 that are front-loaded with the core action and requirement. Nothing is redundant, though the ruleset remark is architecturally useful rather than strictly invocation-critical.

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 exists, so return values need not be explained, and the schema carries rich per-field docs. However, for a 15-parameter mutation the description omits practical behavior an agent would want — duplicate/link-collision handling, and confirmation that no confirmation step is needed given idempotentHint=false.

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 60%, a mid-range baseline. The description only calls out name (required), summary, description, and link, and says the rest 'pass through' — it adds little syntax or constraint detail beyond what the schema's per-field descriptions (public, showInvite, summary cap) already provide.

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

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

States a specific verb+resource ('Create a new world owned by the calling user') and clarifies the world's place in the hierarchy versus adventures. It stops short of naming a sibling tool (e.g. imagine_create_adventure) as an explicit alternative, so it is clear but not fully disambiguated.

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

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

Usage is only implied: 'Required: name' plus the note that a world hosts adventures underneath it hints at when to reach for this tool, but there is no explicit when-to-use or when-not-to-use guidance relative to imagine_create_adventure, imagine_create_world_page, or imagine_update_world.

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 declare a non-read-only, non-idempotent, non-destructive open-world mutation. The description goes well beyond that: it explains visibility='gm' yields 404s and absence from lists/search/backlinks, describes masked-page mechanics (maskName default 'Redacted', hidden real name/link/content), and notes that setting a custom page link is gated behind Premium/VIP/admin and otherwise silently ignored. This is rich, non-obvious 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?

Front-loaded with purpose and required fields, then layered detail on documentTypes, tags, and visibility. The dense final sentences on visibility are long but each carries decision-relevant information (404 behavior, mask semantics). Appropriately sized for a 28-parameter tool, though slightly run-on.

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 exists, so return values need not be explained. Given the tool's high complexity and partial schema coverage, the description covers the highest-risk semantics (visibility, permissions, documentType constraints). Some lesser parameters lack explanation, but an agent can call the tool correctly on the critical paths.

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 mid-range (46%) across 28 params, so the description must add meaning. It does add real value on documentType valid values and prohibitions, the tags→searchable-keyword behavior, and visibility/maskName semantics. However, many parameters (image, active, aliases, details, ruleset, template, menu controls, relationships, outboundLinks, vaultCharacterId, playCampaignCharacters) remain unexplained in both schema and description, so it only partially compensates.

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

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

States a specific verb+resource ('Create a new page inside a world'), lists required fields, and enumerates the intended use cases (NPCs, locations, organizations, events). It actively distinguishes itself from sibling authoring tools by stating items and rules are NOT page types and belong in vault, so an agent can route correctly without opening sibling schemas.

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

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

Gives clear context for when to use it (pages for NPCs/locations/orgs/events), an explicit exclusion (items and rules go to vault), and guidance that tags enable filtering via imagine_list_world_pages_by_tags. It does not address create-vs-update routing or how it differs from imagine_create_adventure_page, but the alternatives it does name are the important ones.

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 carry the safety profile (destructive=true, idempotent=true, readOnly=false), and the description adds genuinely new behavior: the delete is reversible via a deleted-adventures list restorable from the UI, contained pages are tombstoned alongside it, and authorization is enforced by role with a 404 for contributors.

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, front-loaded with the operation and its soft-delete nature, followed by routing effects, authorization, and the confirmation instruction. No sentence is filler.

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

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

An output schema exists so return values need not be described. The description still covers the mutation's scope (pages tombstoned), recoverability, auth requirements, and the confirmation step — everything an agent needs to call this safely.

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

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

Only one parameter (id) and schema coverage is 100%, with the schema itself explaining it is the Mongo `_id`. The description adds nothing beyond 'by id', so this is the expected baseline when the schema does all the work.

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

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

States a specific verb (soft-delete), resource (adventure), and lookup key (by id), and the word 'soft' immediately separates it from the hard-delete siblings like imagine_delete_adventure_page. An agent can identify the operation without opening the schema.

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

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

Gives clear preconditions: caller must be owner or admin with Admin Mode on, contributors get 404, and it instructs the agent to confirm with the user first. It does not, however, name a competing sibling or state when to choose deletion over e.g. imagine_update_adventure, so it falls short of full when/when-not/alternatives 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?

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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses that the delete is soft and restorable from the UI, that nested pages and adventures are tombstoned with it, and that unauthorized contributors receive a 404 rather than a permission error. That is exactly the behavioral context an agent needs before invoking a destructive cascade.

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

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

Front-loads the operation and its soft-delete nature, then layers restoration, cascade, authorization, and the confirmation requirement in five tight sentences with no filler. Every sentence carries distinct, actionable 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 one-parameter destructive tool with an output schema, the description covers everything an agent needs: reversibility, cascade scope, authorization rules, and the confirmation requirement. Nothing material is left to inference.

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

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

Schema description coverage is 100% and the single id parameter is documented as the Mongo `_id`. The description only echoes 'by id' and adds no format or lookup guidance, so the schema carries the full burden. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Soft-delete a world by id') and immediately qualifies the operation as a soft-delete rather than a hard purge. An agent can distinguish it from siblings like imagine_delete_adventure and imagine_delete_world_page without opening any schema.

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

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

Gives concrete preconditions: caller must be the world's owner or an admin with Admin Mode on, and contributors get 404. It also instructs 'Confirm with the user first.' It stops short of naming an alternative tool or the exact condition under which a caller should pick this over another delete, so it is clear context rather than a full when/when-not matrix.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that it returns an array of names and that gender/surname only apply to people, but never discloses the non-determinism implied by idempotentHint=false (repeated calls yield new names) or any rate/size behavior.

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

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

Two tight sentences, front-loaded with the cultural scope then the parameter applicability and return shape. The flavor phrase ('guttural men, flowing women') is arguably decorative but does help an agent judge whether this generator matches the desired naming style.

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?

All four optional params are documented in the schema, annotations carry the safety profile, and an output schema exists so return values need not be enumerated. Only minor gaps remain: no statement of randomness/non-determinism and no cross-reference to the sibling generators.

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 enums documented for kind and gender, so the baseline is 3. The description's only added meaning is the conditional applicability rule ('for people, gender and surname apply'), which the schema only partly conveys for surname.

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

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

States a specific verb+resource ('Generate ... names') scoped to the Braxyl culture of Veylantia, which is the real discriminator among the many sibling culture-name generators (draconic, lorean, shoren, etc.). It never explicitly says it differs from those siblings, but the cultural identifier effectively lets an agent pick it over the rest.

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

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

Usage is only implied: the culture flavor hints at when this generator fits, but there is no when-to-use/when-not statement and no sibling routing among the seven other generate_*_name tools. The clause about which parameters apply for people is parameter scoping, not 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 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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the non-idempotent hint is consistent with random name generation. The description adds the conditional behavior that gender/surname apply only to people and that the return is an array, but does not add rich operational context 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 compact sentences, front-loaded with the purpose before the parameter notes. Slight redundancy in "Returns an array of names," which the output schema already covers, but overall tight.

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 exists, so return values need no explanation, and the description adequately covers the discriminators (culture, kind, conditional gender/surname). The only meaningful gap is the absence of cross-tool routing guidance among the sibling name generators.

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 four parameters; baseline is 3. The description adds a modest linking semantic (gender and surname apply only when kind=person), but mostly restates what the enum descriptions already convey.

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

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

States a specific verb+resource ("Generate ... names") and adds a distinguishing flavor ("melodious, French-flavored noble names from the Gallance culture of the world Veylantia"), which meaningfully separates it from the eight other imagine_generate_*_name siblings. It stops short of explicitly naming those alternatives, but the cultural qualifier is enough to identify the 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?

Usage is implied by the culture qualifier (use it when you want Gallance names), and the `kind` clause scopes when gender/surname matter. However, there is no explicit when-to-use framing and no guidance on choosing this over the sibling name generators (Braxylian, Lorean, etc.), leaving the routing decision 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 establish the read-only, non-destructive safety profile, so the description need not restate it. What it does add is flavor scope and a return-type note. However, idempotentHint=false means repeated identical calls produce different results, and the description never mentions that the output is randomly generated and non-repeatable — a materially useful fact for an agent.

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

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

Two tight sentences, front-loaded with the purpose before the parameter notes. The setting-flavor clause ("the refugee holdfasts of the world Korinth") is slightly decorative but contributes useful scoping context for choosing among the cultural generators.

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 exists, so the description is not obliged to document the return structure, and it still gives a one-line summary. For a zero-required-parameter generator with fully covered schema, everything needed to invoke it correctly is present; only the non-determinism caveat 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 schema already documents all four parameters including defaults and enums. The description reinforces the conditional linkage (kind chooses person/place; gender and surname only apply to people) but adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Generate plain, weathered names") and identifies the culture scope ("Lorean Freeholds... Korinth"), which is the axis that separates it from the eight sibling name generators. It never explicitly names a sibling or says 'unlike X', so differentiation relies on the agent noticing the cultural flavor word.

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

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

There is no statement of when to reach for this tool versus any of the other imagine_generate_*_name siblings, nor any prerequisites or exclusions. Usage is only implied by the flavor text about the setting.

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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that the output is an array of names and hints at the generative behavior, but says nothing about determinism or rate/count constraints beyond the schema.

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

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

Three compact sentences, front-loaded with the cultural flavor before the parameter mechanics. Every sentence contributes, though the return-value sentence is partially redundant with the output schema.

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

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

An output schema exists, so return values need not be detailed, and annotations carry the safety profile. The description supplies the flavor and the person/place parameter interplay, which is enough for an agent to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description notes that kind selects person or place and that gender/surname apply to people, but this largely restates the per-field schema descriptions rather than adding new 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?

States a specific verb+resource (generate names) scoped to a named culture/region (Pelegor, Veylantia) and the flavor it targets. This distinguishes it in spirit from the many sibling culture generators, though it never explicitly names or contrasts 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?

Usage is implied: pick this when you want Pelegorian names. There is no explicit when-to-use or when-not guidance and no routing to the other imagine_generate_*_name siblings, so an agent choosing between cultures gets no help.

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

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

Annotations already declare this is a read-only, non-destructive, non-open-world call, so the safety profile is covered. The description adds stylistic context ("clipped, consonant-struck") but glosses over other useful behavior implied by idempotentHint=false, namely that repeat calls yield different names. Adequate but not 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?

Three short sentences, front-loaded with the generation verb and resource, with a clear return statement at the end. Slight redundancy with the schema's enum descriptions keeps it out of the top band.

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?

All three parameters are optional with full schema coverage, an output schema exists so return shape needn't be spelled out, and annotations cover the safety profile. The description is sufficient to call the tool correctly, missing only alternative-tool routing.

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 kind, gender, and count are fully documented in the schema; the description only restates the kind and gender enums. No extra meaning (format, constraints, interaction between kind and gender defaults) is added beyond the structured fields.

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

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

States a specific verb+resource ("Generate ... names from Shoren") and pins the flavor to a named culture in a named world, which separates it from the nine other imagine_generate_*_name siblings. It stops short of explicitly saying it is the Shoren-specific generator among them, but the differentiation is clear from the text itself.

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

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

There is no when-to-use/when-not guidance and no mention of alternatives such as the sibling culture-name generators or imagine_translate_shoren. The kind/gender semantics are parameter documentation, not invocation guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the aesthetic character of the output but omits the one non-obvious behavioral trait declared by annotations — idempotentHint=false, i.e. that repeated calls yield different names rather than the same set. A 3 reflects modest added context against an already-covered safety surface.

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 packed sentences: the cultural identity and flavor come first, then the parameter applicability. No filler, no repetition, and the most decision-relevant information (which culture) 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?

An output schema exists, so explaining return values is unnecessary and the brief 'returns an array of names' is harmless redundancy. The definition covers what an agent needs to invoke it correctly; the only unaddressed element is the non-idempotent regeneration behavior implied by annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine conditional semantics beyond the schema: gender and surname apply only when kind='person', a dependency the schema does not state for surname. It adds little for count or the enum values themselves, which the schema already enumerates.

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 (generate names) and pinpoints the exact culture/world it serves ('Strykaran people of the world Veylantia — soft and Slavic-flavored'). That flavor note meaningfully separates it from the many sibling culture generators (braxylian, draconic, gallance, etc.), though it never names an alternative explicitly.

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

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

Gives clear context for selection: the ethnic/aesthetic flavor tells the agent which of the sister name generators fits, and it explains that `kind` selects person vs place with gender/surname applying only to people. There are no explicit exclusions or when-not conditions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description usefully states the return shape (an array of names), but it omits the notable behavioral fact behind idempotentHint=false — that repeated identical calls yield different names. It also says nothing about the count cap or default behavior beyond what the schema says.

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 that front-load what the tool produces and the realm it draws from before getting to parameters. No filler, though the trailing parameter recap is partly redundant with the schema.

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

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

An output schema exists, so the return format needn't be spelled out, and the description still gives the gist (array of names). For a zero-required-parameter generator the description is sufficient to invoke it correctly; only the sibling-disambiguation context 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 all four parameters including `count` are already fully documented with defaults and ranges. The description restates `kind`, `gender`, and `surname` but adds no format, constraint, or interaction detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource (generate names) and pins the domain to Tarithan within Veylantia, which is exactly what separates it from the nine sibling imagine_generate_*_name tools. The `kind` clause further clarifies that it covers both persons and places.

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

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

Usage is only implied: an agent can infer this is the generator to pick when the target culture is Tarithan, but the description never states that explicitly nor contrasts it with imagine_generate_braxylian_name or the other realm generators. No when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and non-idempotent behavior, so the safety and repeatability profile is covered. The description adds the return shape (an array of names) but nothing about rate limits, determinism, or why idempotentHint is false.

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

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

Two compact sentences that lead with the cultural flavor defining the output style and then cover parameter behavior. Front-loaded and largely waste-free, with only slight overlap against the schema's own parameter descriptions.

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

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

For a simple generator with an output schema present, the description is complete enough: it conveys the flavor, the selectable kinds, the gender option, and the array return. It doesn't need to restate return details, and the minor gap (count range) is fully covered in the schema.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with defaults and enums; this is the baseline. The description repeats the meaning of `kind` and `gender` but adds no syntax, format, or constraint detail beyond the schema and omits `count` entirely.

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 (Generate) and resource (names) scoped to Thalassa, the sea culture of Veylantia, which implicitly distinguishes it from the many sibling generators (braxylian, draconic, lorean, etc.). The culture/world naming gives an agent a clear identity, though it never explicitly contrasts itself with the other name 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?

Usage is only implied: an agent infers this is the right tool when it needs a Thalassan-culture name. There is no explicit when-to-use, when-not-to-use, or named alternative among the eight sibling name generators.

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

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

Annotations already cover the safe-read profile (readOnly/idempotent/non-destructive), and the description goes well beyond them: the 'view' access requirement, the 403 exception for members of linked play campaigns and the exact minimal recaps-only shape returned, and the substituted `hasLinkedCampaigns` boolean for non-owner viewers. This is unusually rich disclosure of authorization and response variance.

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

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

Purpose and the campaign-link caveat are front-loaded, and every sentence carries substantive information rather than filler. It is long, and spelling out exact response shapes overlaps with the existing output schema, but nothing is wasted.

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

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

For a single-id read tool this covers permissions, the alternate response shapes, the informational nature of campaign links, and pointers to the follow-up tools. With an output schema present, it need not describe return values further, so the description is 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 description coverage is 100% for the single `id` parameter, which the schema already documents as the Mongo `_id`. The description's 'by id' adds no syntax or format detail beyond that, 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?

Opens with a specific verb and resource ('Fetch one adventure by id') and enumerates the payload contents (settings, ruleset, recommended level, linked play campaigns). This distinguishes it from siblings like imagine_list_my_adventures and imagine_get_adventure_page without needing to open either schema.

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

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

Gives clear conditions: caller needs at least 'view' access, and it routes to imagine_list_adventure_parts for sibling parts and imagine_get_adventure_recaps for the recaps-only shape. It also warns the campaign link is informational and not auto-synced. It stops short of an explicit 'prefer X over Y' rule against adjacent getters, so it is strong but not exhaustive.

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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial extra context: per-caller visibility rules (public + own private vs admin-sees-all), omission of campaigns with no tagged sessions, and the exact empty-result shape ({ campaigns: [] }). This is behavior beyond what structured fields provide.

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

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

Front-loads the core action and grouping semantics, then layers permission and edge-case detail. Dense but every sentence carries information; the permission enumeration is somewhat long but not 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?

Output schema exists so return values needn't be spelled out, yet the description still gives the grouping shape and empty case. Permission model, visibility scoping, and omission behavior are all covered — nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the single `id` param is fully documented there as the Mongo `_id` of the adventure, so baseline 3 applies. The description clarifies the entity relationship (sessions tagged via imagineAdventureId) that determines the result set but adds no format or syntax detail about the parameter itself.

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

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

States a specific verb+resource ('Fetch the play-session recaps ... grouped by linked play campaign') and explicitly distinguishes itself from the manual alternative (play_list_campaign_sessions + play_list_pages). An agent can tell what this returns and how it differs from the sibling list tools 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?

Names the read-through-to-play condition (caller must be a member of a linked campaign or an admin with Admin Mode on), notes the recaps-only path for PRIVATE adventures, and states it replaces the two-step manual walk of the sibling tools. When-to-use and the alternative are both explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond that: the campaign link is informational only and not auto-synced, and the caller must have view access. These details help the agent understand the tool's side effects and authorization requirements, which annotations do not provide.

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

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

The description is three sentences with no waste. The first sentence states the primary purpose and return content, the second clarifies a critical caveat, and the third states a permission prerequisite. It is front-loaded and every sentence earns its place.

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

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

Given the tool has an output schema (indicated) and only one parameter, the description is complete for correct invocation. It covers what the tool returns, the caveat about campaign links, and the required access level. No essential behavioral or usage information is missing.

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

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

Schema coverage is 100% for the single parameter 'id', which is described as 'Mongo _id of the world'. The description does not add additional semantics beyond restating that it fetches by id; it does not provide format examples or extra constraints. Since the schema fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Fetch', the resource 'world', the identifier 'by id', and enumerates the specific data returned (settings, membership, user-linked play campaigns). It differentiates from sibling tools like imagine_get_world_page or imagine_list_my_worlds by specifying the exact scope and fields, so an agent can distinguish it without opening other schemas.

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

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

The description provides a clear context: it is for fetching a single world by id with specific details, and it explicitly states the permission requirement ('Caller must have at least view access'). However, it does not explicitly mention when not to use it or name alternatives (e.g., imagine_list_my_worlds for listing), so it lacks explicit exclusions but still gives clear usage context.

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

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

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

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

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

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

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

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

Given the output schema exists, the description appropriately omits return format details, but it adds valuable cross-reference resolution hints (parent and vaultCharacterId) and workflow guidance on locating the id. The tool is fully contextualized for an agent to call it correctly.

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

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

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

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

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

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

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

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

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

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

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

Annotations only convey readOnly=false, idempotent=false, destructive=false. The description goes far beyond: it explains the side effect (mutating playCampaignIds[]), the derived effect on the campaign's imagineAdventures[] and session Adventure tag, and details error codes (403, 404, 400) with conditions. This fully discloses behavioral impact without contradicting annotations.

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

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

The description is a single dense paragraph, but every sentence contributes: core action, side effects, access control, error codes, preconditions, and a pointer to a helper tool. It is front-loaded with the primary verb and object, and no sentence is redundant.

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

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

For a mutating link operation, the description covers all essential context: what, where, side effects, permissions, error handling, and input sourcing. With an output schema present (though not shown) and annotations covering safety, nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly stating where to get campaignId (from play_list_my_campaigns or play_list_participated_campaigns) and that id is a Mongo _id of the adventure. This enriches the schema's minimal descriptions, so a 4 is warranted.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

An output schema covers the return shape, annotations cover the safety profile, and all three parameters are fully described in both schema and description. Nothing an agent needs to call this tool correctly is missing.

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

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

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

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

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

The description opens with a specific verb and resource: 'List pages belonging to one adventure,' and immediately clarifies it returns summaries rather than full page bodies. It also distinguishes itself from sibling tools like imagine_get_adventure_page and imagine_get_adventure_pages by naming them and describing the split.

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

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

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

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description adds valuable behavioral context: only active parts are listed, ordering by menuOrder then name, one-level grouping, silent omission of unviewable parts, and empty-list behavior for non-parents. No contradiction with annotations.

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

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

The description is front-loaded with the core action and ordering, then adds behavioral edge cases and return fields without waste. Every sentence earns its place, and the field list is useful because it tells the agent exactly what shape to expect.

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

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

For a read-only, single-parameter list tool with an output schema, the description covers all necessary behavior: ordering, active filter, permission-related omission, non-parent result, and how to create parts. Nothing material is missing for correct invocation.

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

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

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

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

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

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

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

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

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

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context beyond annotations by explaining the slim catalog-card scope, the series semantics of `parent`, and the relationship to detail-fetching tools.

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

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

Three sentences, each earning its place: the first states the core action and scope, the second lists the return fields, and the third handles related-tool routing. It is front-loaded and contains no filler.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond them by disclosing the return payload shape (id, name, link, parentId, tags) and that the result is a hierarchy-friendly summary rather than full content.

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

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

Two sentences deliver purpose, return shape, and a companion-tool pointer with no filler. The core scope is front-loaded, making the definition easy to parse quickly.

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

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

For a simple read-only list operation with one well-documented parameter, an output schema, and rich safety annotations, the description covers what an agent needs: scope, return type, and how to fetch full content. Nothing critical is missing.

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

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

Schema coverage for the single required parameter is 100%, with worldId described as a Mongo _id. The description only reinforces 'one world' without adding new parameter syntax, format, or edge-case details, so baseline 3 applies.

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

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

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

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

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

The description provides clear workflow guidance by pairing this tool with imagine_get_world_page for full content, implying this tool is for summaries and navigation. It does not explicitly contrast with imagine_list_world_pages_by_tags or imagine_search_world_pages, so it misses full exclusionary guidance.

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

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

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

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

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

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

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

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

Given the output schema exists, annotations cover safety, and all parameters are documented in the schema, the description provides the remaining behavioral context an agent needs: how tags interact with documentType, the default/mode choices, and typical use cases. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the unexpected documentType matching behavior and giving concrete tag examples. It clarifies the tags parameter more deeply than the schema's 'comma-separated list' description.

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

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

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

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

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

The description gives concrete usage patterns ('all NPCs', 'all locations', 'every character-type page') and explains when to use mode 'and' vs 'or'. It does not explicitly name the sibling alternatives or say when not to use them, but the examples make the intended use clear.

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

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

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

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

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

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

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

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

The description covers the essential operational context: the safe usage, the alternative to avoid, the literal matching, the option for a staleness guard with its 409 behavior, and the return format. It even tells the agent to pre-count occurrences if protection is desired. With an output schema available, nothing material is missing.

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

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

Schema coverage is 100%, so the schema already fully documents each parameter, including the literal match behavior and the staleness guard. The description adds context like 'single pass' and return value, but these are already implied by schema descriptions and output schema. It provides no new parameter-specific semantics beyond reinforcing the schema.

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

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

The description states a specific verb and resource: 'Replace text inside one adventure page's content'. It distinguishes itself from the sibling imagine_update_adventure_page by emphasizing 'surgical find-and-replace' that preserves every byte outside matched ranges, making its unique intent explicit.

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

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

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

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

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

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

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

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

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

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

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

For a two-parameter read-only search tool, the definition is complete: annotations cover safety, the output schema covers return values, the description covers scope, the known failure mode, and the correct sibling alternative. An agent has everything needed to decide when to call this tool and what to expect from it.

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

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

Schema description coverage is 100%: query and worldId each have meaningful descriptions in the schema. The description only marginally augments this by clarifying that the query runs against titles and raw markdown 'within one world,' reinforcing worldId's scoping role. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

States a specific verb and resource: 'Text search over page titles and raw markdown bodies within one world.' It also explicitly distinguishes itself from the sibling tool imagine_list_world_pages_by_tags by scoping this tool to raw text search and the sibling to category/tag lookups. The title and description align cleanly with no ambiguity.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety and determinism are covered. The description's 'Deterministic: the same input always yields the same Shoren' largely restates idempotentHint, and the return shape restates the existing output schema, so it adds little beyond the structured data; the verb-marking rule is behavioral but is also present in the 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?

Front-loaded with the purpose, followed by behavioral notes and the return shape; every sentence is short and the verb-marking example is concretely useful. Slight redundancy with annotations/schema keeps it from a 5.

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

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

With one fully documented parameter, an output schema that already defines { translation }, and annotations covering the safety profile, the description supplies the remaining flavor context and an example. Nothing critical is missing for correct invocation, though it could have named its nearest sibling.

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 the single 'text' parameter, including the asterisk verb-marking convention and length limit. The description restates that same asterisk convention with an example but adds no new format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource — translating English text into the Shoren tongue of Veylantia — with a flavor descriptor ('clipped and consonant-struck'). It is distinguishable from most siblings, but it never mentions the closest sibling, imagine_generate_shoren_name, so an agent must infer on its own that this tool translates arbitrary prose rather than generating a name.

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

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

Usage is implied by the purpose ('translate English text'), and the asterisk convention hints at how to get verb-last output. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as the Shoren name generator, leaving selection partly to inference.

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

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

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

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

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

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

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

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

For a mutation tool with an output schema and strong annotations, the description covers all essential operational concerns: side effects, edge cases, permissions, and relationship semantics. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the schema already documents both `id` and `campaignId` adequately. The description adds a little semantic color around the link relationship and the dangling-campaign edge case, but does not materially extend parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Remove a play campaign from an adventure's `playCampaignIds[]`.' It clearly differentiates this from the inverse link tool and from `imagine_unlink_world_from_campaign` by scoping the operation to adventures. The title and description consistently identify exactly what is being unlinked.

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

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

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

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

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

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

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

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

Three short sentences, each earning its place: purpose and core effect, optional flag behavior, and access prerequisites. No filler or redundancy.

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

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

For a mutation tool with an output schema, the description covers the operation, optional side effect, and authorization requirements. It is missing only minor contextual details such as behavior when the link does not exist, but the idempotentHint annotation partially covers that.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a bit of shared context around `removeSyncedHouseRules`, but does not substantially extend the parameter-level meaning beyond what the schema provides.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond them: partial-update semantics, the 'edit' permission requirement, optimistic-concurrency via baseUpdatedAt with OUT_OF_SYNC and 'nothing is written' on failure, and rename propagation to linked campaigns. This is exactly the context an agent cannot get from the annotations.

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

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

Front-loaded with the core verb+resource, then permission, then the two highest-risk behaviors (series grouping, baseUpdatedAt). Dense but every sentence carries operational weight; only the parent clause is slightly redundant with the field description it points to.

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

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

For a 24-param mutation tool with an output schema and rich annotations, the description covers the contract-completing details an agent needs: partial update, auth, concurrency guard, and side effects on linked campaigns. Return values are covered by the output schema, so nothing essential is missing.

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

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

With 24 parameters and only 63% schema description coverage, the schema does most of the heavy lifting. The description adds real value for the tricky parameters (baseUpdatedAt workflow, parent grouping/ungrouping, menuOrder append default) but explicitly defers to the field description for parent validation and does not address the remaining undocumented fields. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('PUT updates to one adventure by id') and is clearly distinguishable from siblings like imagine_update_adventure_page and imagine_create_adventure. The scope of a partial update ('Only supplied fields are sent') is stated up front, so an agent knows exactly what this tool mutates.

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

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

Gives clear prerequisites and routing: caller needs 'edit', and it explicitly directs the agent to a fresh imagine_get_adventure read before calling, with the OUT_OF_SYNC failure described. It does not spell out when to prefer a sibling like imagine_update_adventure_page, but for the common case the when-to-use is unambiguous.

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

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

Annotations already signal this is a write operation, but the description adds substantial behavioral detail: only supplied fields are sent, content is replaced wholesale, stale baseUpdatedAt values are rejected with OUT_OF_SYNC and nothing is written, and successful updates return a new updatedAt. It also discloses that read-aloud/moving-on/tactics are not fields but must be authored inline as callout blocks, which is valuable beyond the schema and annotations.

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

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

The description is long but information-dense, with the core verb, resource, and warnings front-loaded before alternatives and prerequisites. Every major sentence earns its place, though the long field enumeration and repeated warning about content could arguably be tightened without losing value.

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

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

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

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

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

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

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

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

The description opens with a specific verb and resource ('PUT updates to one adventure page by id') and goes on to enumerate the full set of updateable fields, which clearly differentiates it from sibling get/create/replace tools. It also names the sibling surgical alternative, so an agent can distinguish this tool from imagine_replace_in_adventure_page without inspecting schemas.

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

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

The description explicitly states when to use this tool versus alternatives: prefer imagine_replace_in_adventure_page for surgical content edits, and fetch via imagine_get_adventure_page with raw=true when appending. It also states the required permission ('Caller must have edit') and the mandatory fresh-read workflow for baseUpdatedAt, giving unambiguous selection and invocation guidance.

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

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

Goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing merge semantics ('only supplied fields are sent; imagine merges them'), optimistic-concurrency behavior (stale/fabricated baseUpdatedAt → OUT_OF_SYNC with nothing written), and field-level permission nuance (showInvite ignored for contributors). This is exactly the extra context annotations cannot carry.

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

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

Front-loads the operation, then permissions, then merge behavior, then the critical baseUpdatedAt requirement. Four tight sentences with no filler; each clause carries actionable 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 17-parameter, nested-object mutation tool with an output schema, the description covers the highest-risk aspects (access control, merge semantics, concurrency guard) and defers return values to the output schema. Nothing essential to a correct invocation is missing.

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

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

Schema coverage is 65%, but the description compensates by explaining the two most consequential parameters: baseUpdatedAt (how to obtain it, why it is required, the rejection behavior) and showInvite (who may change it). It does not add syntax detail for the remaining nested/optional fields, which the schema partially covers.

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

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

States a specific verb and resource with explicit scope: 'PUT updates to one world by id.' It also names the sibling read tool (imagine_get_world) it depends on, so an agent can distinguish this world-level update from the world-page and adventure update siblings without opening a schema.

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

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

Gives clear prerequisites (must have 'edit' access as owner, contributor, or admin with Admin Mode) and the mandatory workflow (copy updatedAt from a fresh imagine_get_world read first). It does not explicitly name when to choose this over imagine_update_world_page, but the context is strong.

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description goes well beyond them: it discloses the wholesale content replacement, the OUT_OF_SYNC rejection of stale/memorized tokens with 'nothing is written', the visibility side effects (404s, list/backlink participation, menu stripping), and that follow-up writes must use the updatedAt returned by this call. That is dense, actionable behavioral context for a mutation tool.

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

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

The four paragraphs are front-loaded with the highest-risk facts first (id, replace semantics, permission, sync token) and every sentence is functional. The one cost is redundancy: the baseUpdatedAt and visibility passages restate, nearly verbatim, what the schema's own property descriptions already say, which inflates length without adding new 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 29-parameter, nested-object mutation on a permissioned resource with an output schema present, the description covers the workflow (read-then-write), authorization, failure mode with error code, destructive side effect, and visibility semantics. Nothing an agent needs to call this safely is missing, and return values are correctly left to the output schema.

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

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

Schema coverage is only 48% across 29 parameters, so the description is expected to carry weight; it does so for the three riskiest fields (content replacement, baseUpdatedAt freshness/OUT_OF_SYNC, and the three visibility modes), but leaves the majority of parameters (image, active, aliases, ruleset, template, menu ordering, etc.) to the schema alone. Strong on the fields that cause damage, silent on the rest.

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+scope: 'PUT updates to one world page by id', and immediately clarifies partial-update semantics ('Only supplied fields are sent'). This cleanly separates it from imagine_create_world_page, imagine_get_world_page, and imagine_update_adventure_page without the agent needing to open a schema.

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

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

It states the permission prerequisite ('edit' on the world page), the mandatory baseUpdatedAt precondition, and gives an explicit alternative path when a different intent is present ('To append, fetch the page first with imagine_get_world_page, concatenate, and send the combined body back'). The replace-vs-append distinction is exactly the when/when-not guidance an agent needs before writing.

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.