Lunafic

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent creation, so the description's job is additive. It does that by disclosing that default panels are created automatically (default true) and by explaining the live role semantics — a role with a matching character name is that person, one without is a player variant. It does not mention error modes, dedup behavior on repeat names, or permission needs.

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

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

The main action is front-loaded, but the middle is dense nested-parenthetical prose about role/character name identity that takes effort to parse. Every sentence is relevant, yet the phrasing is not economical.

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

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

For a 10-parameter creation tool with no output schema and no annotation coverage of side effects, the description covers the two trickiest behaviors (panel seeding, role semantics) but leaves most field semantics and the returned identity unaddressed. Adequate but with clear gaps.

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 10% across 10 parameters. The description adds meaning only for `type` (mc_template role semantics) and `seedPanels` (default true, interaction with import_brief); `name`, `tags`, `series`, `aliases`, `tagline`, `avatarUrl`, `projectId` and `description` are left entirely to bare schema types. That is far short of compensating for the coverage gap.

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

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

Opens with a specific verb+resource ("Create a world bible entry") and enumerates the kind of entities covered, so an agent can distinguish it from update_entry or delete_entry at a glance. It stops short of explicitly contrasting itself with those siblings, but the action and object are 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?

Gives real conditional guidance: omit seedPanels:false when you intend to import_brief the panels separately, and explains the mc_template path versus normal entry creation. It lacks exclusions like "use update_entry to modify an existing entry," which keeps it from 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?

Goes well beyond the annotations by disclosing that the URL is single-use and expires in 15 minutes, that bytes never pass through the model, that the image is resized server-side like upload_image, and by giving the exact follow-up PUT invocation. The annotations only declare non-read-only/non-idempotent; the description supplies the real operational 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?

Front-loads purpose and the base64 rationale, then layers the return shape and the concrete curl step. The embedded command is long but earns its place for a multi-step tool; a couple of clauses could be tightened.

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

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

No output schema exists, yet the description documents both the returned object ({ uploadUrl, method, contentType, expiresInSeconds, howTo }) and the follow-up PUT response ({ url }). Nothing an agent needs to complete the flow 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 baseline is 3, but the description adds the conditional coupling between slot and its target id (slot "avatar" + entryId, or slot "scene" + scenarioId) and notes filename sets the image type. That pairing guidance is useful beyond the per-field schema text, though it partly echoes it.

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 (get a one-time signed URL to upload a local image file) and explicitly distinguishes itself from the sibling upload_image by framing itself as the base64-overflow alternative. An agent can tell which tool to reach for without opening either schema.

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

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

Gives an explicit when-to-use ('the fix for files too big to inline as base64', local files), names the sibling it parallels (upload_image), and states an exclusion ('the scenario COVER is editor-only and cannot be uploaded here'). Routing conditions are fully spelled out.

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

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

Annotations cover the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's real contribution is disclosing that creation produces a non-published draft that requires a separate publish step. That is useful behavioral context an agent cannot infer from structured fields. It does not say what the call returns or whether repeated calls create duplicates.

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 action and draft state, followed by the parameter hint and the publish route. Nothing is padded or restated from the title.

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 15-parameter creation tool with no output schema, the description never says what comes back (e.g. a world identifier), which fields besides title are needed to publish, or what the maturity/format enums mean. Only the worldKind and publish-path gaps are addressed, leaving most of the call surface undocumented.

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 only 13% across 15 parameters, so the description must carry most of the semantic load, yet it explains only worldKind. Opaque enums such as authoringMode ('mc' vs 'author'), derivation, and dialogueFormat are left unexplained in both schema and 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?

States a specific verb and resource ('Create a new world') plus the resulting state ('as a draft'), which is materially different from sibling update_world. It does not differentiate itself from create_entry, but the resource is unambiguous.

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

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

Explains the choice between the two worldKind values ('private' for your own writing vs 'playable' for players) and names the follow-up tool and action ('Publish it afterwards with update_world'). No when-not guidance or prerequisites, but the routing is clear.

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

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

Annotations already disclose destructiveHint=true and that the operation is not idempotent. The description adds that the deletion includes panels, that it can be undone via Agent activity, and that it is refused for specific entry types. This is useful beyond annotations, but it does not cover permissions, rate limits, or exact reversal mechanics.

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 core action and scope, followed by recovery, refusal, and user-consent instructions. Every sentence adds needed information with no redundancy.

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

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

For a destructive single-parameter tool with no output schema, the description covers deletion scope, recovery, refusal, and consent. However, it omits parameter details and any mention of required permissions or side effects on linked data beyond panels, leaving some gaps.

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 0% for the single entryId parameter, and the description does not explain what an entryId is, where to find it, or its format. The description provides no semantic detail beyond the schema type, leaving a critical parameter undocumented.

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

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

The description states a clear verb+resource: 'Delete one wiki entry and its panels.' This distinguishes it from siblings like update_entry or search_entries. However, it does not explicitly note what makes it different from other delete or write operations beyond the scope statement.

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 implies the action is for entries and provides some conditions (refused for characters/roles, ask user first), but it does not explicitly say when to choose delete_entry versus update_entry or other alternatives. The guidance is present but not fully comparative.

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 openWorldHint=false, establishing the safety profile. The description adds relevant behavioral context — that recaps are Lunafic's story-so-far memory and often obviate full chapter reads — but doesn't cover pagination or output structure. With annotations carrying the safety burden, a 3 reflects moderate added value.

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

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

Three sentences, front-loaded with the core content list, followed by a usage directive and a sibling pointer. Slightly dense in the first sentence but every clause 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 a single well-documented parameter, rich annotations, and no output schema, the description covers the returned fields and routes to get_story_status for stats. The lack of an output schema means the field list is genuinely helpful, though it could be slightly more explicit about the shape of the chapter list.

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 already documents storyId ('from list_stories'). The description adds no parameter syntax or format details beyond what the schema provides. Baseline 3 is appropriate 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?

The description states a specific verb and resource ('One story's overview') and enumerates the returned contents: world, player character, chapters in reading order with word count and recap. It also differentiates from siblings by naming get_story_status for character stats and contrasting with read_chapter.

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

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

Explicitly says 'Start every analysis here' and that recaps answer most questions without reading full chapters — a clear when-to-use directive with an implied alternative (read_chapter) that it steers the agent away from.

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 read-only safety profile, but the description adds genuinely new behavior: ownership requirement, the guarantee that this tool cannot mutate values, and the return scope (character values plus last 20 changes by story or player). No contradictions.

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?

One dense, front-loaded sentence with no filler; scope, return shape, safety and ownership are packed in efficiently. Minor awkwardness from the possessive 'stories' Status' phrasing but nothing wasteful.

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

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

With no output schema, the description correctly carries the return-value burden by specifying current character values and the last 20 changes. Combined with the owner-only and read-only statements, an agent has enough to call it correctly; only an explicit sibling comparison is missing.

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

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

Only one parameter and schema description coverage is 100% ('storyId from list_stories'), so the schema fully documents it. The description adds nothing about the parameter itself, which matches the baseline 3 when the schema does the work.

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

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

States a specific verb (Read) and resource (story Status), and defines what that resource contains: every character's current values plus the last 20 changes. This distinguishes it from get_story and get_world_status implicitly through the 'story' scope, though it never names an alternative it is not.

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

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

Gives a real constraint ('Owner only') and clarifies the mutation model ('values in a story change only inside Lunafic'), which implies this tool is not the way to modify values. However it never tells the agent when to pick this over get_story or set_status_start, so the usage guidance is implied rather than 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 and destructiveHint=false, so the safety profile is covered; the description adds the useful fact that the returned openingWarnings and roleNameTips are actionable diagnostics with prescribed fixes. It does not discuss size or performance of a 'full state' read, which is the one remaining behavioral unknown.

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 scope statement and every subsequent sentence carries operational payload (use-before-update, warning remediation, status exclusion). The warning sentences are dense run-ons that could be split for scanability, but nothing 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?

No output schema exists, yet the description enumerates the returned sections and explains the semantics of openingWarnings and roleNameTips, so an agent knows what it will receive and what to do with it. For a two-param read tool this 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 coverage is 50%: worldId is documented ("World id from list_worlds") but slug is bare, and the description never clarifies the relationship or precedence between the two identifiers. Baseline 3 applies since the schema does part of the work, but the slug/worldId ambiguity is a real gap the description could have closed.

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

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

States a specific verb and resource ("Read one world's full V4 state") and enumerates the contents: settings, rules, playable config, mc_template roles. It also explicitly carves out status data as belonging to get_world_status, which separates it from the closest sibling.

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

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

Gives explicit sequencing ("Use this before update_world") and routes two follow-up remediation paths to specific siblings: fix warning labels via update_entry, and rewrite role names via upsert_panel. It also names alternatives for status (get_world_status / set_world_status), so the agent knows when not to use this 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?

Annotations already declare readOnly/non-destructive, so the description correctly spends its words on what the read returns: full entry/panel coverage and the guarded isProtected flag. It also explains the speechLanguage / languageVariants data shape, which is real behavioral context the agent could not infer from the schema. No pagination or size caveats, though.

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?

Leads with the core read scope and the key usage instruction, then adds the language-variant detail where it belongs. Slightly dense in the parenthetical example, but every sentence carries information.

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

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

With no output schema, the description has to sketch the return shape, and it does: entries, panels, panel content, isProtected, plus the language tabs structure. Only missing piece is any sense of response size or completeness guarantees for large scenarios.

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?

Single parameter with 100% schema description coverage; the schema already tells the agent projectId comes from list_scenarios. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource with scope: reads *every* entry and panel of a scenario, including panel content and the isProtected flag. This implicitly separates it from narrower readers like search_entries or get_world, though it never names a sibling 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?

'Start here before writing' gives a clear sequencing rule that an agent can act on. It stops short of naming alternatives (e.g. use search_entries for lookups) or stating 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds substantive behavioral context the annotations cannot: it discloses the payload shape (stats, play flags, window look, per-character values and starts) and clarifies the world-level vs story-level scope of the data.

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 in the first clause, and the density is justified by the absence of an output schema. The first sentence is long and comma-heavy, but nearly every clause carries new information about the return payload.

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

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

With no output schema, the description correctly takes on the burden of describing return contents in detail and adds a clear scoping rule plus a sequencing hint toward the setter siblings. The remaining gap is parameter documentation, which is left entirely to the schema.

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

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

Only worldId is documented in the schema (50% coverage); slug has no description anywhere. The description does not mention either parameter, so it does nothing to compensate for the uncovered slug field or to explain how slug and worldId relate.

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

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

States a specific verb and resource ('Read a world's Status setup') and then enumerates exactly what the setup contains: the RPG-style stats (max 6), which ones play, why one does not, the window look, and per-character values/start. It also implicitly distinguishes itself from get_story_status by clarifying that 'Status values live per story; this is the setup every story of the world uses.'

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

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

Gives explicit sequencing guidance: 'Use it before set_world_status or set_status_start,' naming the two write-side siblings. It does not explicitly state when to prefer get_story_status instead, but the world-vs-story scoping sentence makes that inference easy.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for explaining the mechanism: matching by type+name and panels by title, and re-running updates rather than duplicating. It does not say what happens to existing entries absent from the brief (removal? leave-in-place?), which matters for a destructive import.

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 idempotency before diving into format rules. Dense with nested parentheticals, but nearly every clause carries operational information (inline panels, {{player}}, languages tabs). Slightly overpacked into one paragraph.

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

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

For a destructive, idempotent, nested-object import with no output schema, the description covers content authoring rules and duplicate handling well. It leaves out error behavior on malformed formats and the fate of entries omitted from a re-import.

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 50% and projectId is undocumented, but the description compensates heavily on the nested 'brief' param: the format string, entries/panels structure, the 'languages' key, and the {{player}} placeholder convention. That is substantive meaning the schema does not 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 and resource ('Bulk-import a Lunafic Brief') and immediately pins down the payload format ('JSON with format "lunafic-brief/1": entries with panels'). This is clearly distinguishable from the single-entry siblings like create_entry or upsert_panel.

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

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

Explicitly says 'Prefer this for whole characters AND player roles', which is real routing guidance against the per-entry siblings. It also gives a non-obvious prerequisite ('supply its panels inline since roles have no default template'). It stops short of naming an explicit when-not-to-use or naming the alternative 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the shape of returned entries (the 'kind' discriminator and the id field), but no behavioral traits such as auth requirements, scoping to the calling user beyond 'the user's projects', or pagination/limits.

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 purpose before the interpretive detail and the downstream id guidance. Every sentence earns its place, though the phrasing is slightly dense with the parenthetical about world tools.

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

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

With no output schema and no parameters, the description must carry the return-value burden, and it does explain the two entry kinds and the id field the agent needs. It stops short of enumerating the remaining entry fields, leaving some gaps for a lookup tool whose output the agent must interpret.

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

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

The tool takes zero parameters, so the baseline is 4; there are no arguments to mis-specify. The description still adds value by telling the agent what to do with the returned id, which is the only 'parameter-like' information relevant to this call chain.

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 ('List the user's projects') and decodes the tool name by explaining that projects come in two kinds, 'world' and 'story'. However, it never differentiates itself from the sibling list_worlds and list_stories tools, so an agent cannot tell from the text alone whether this is the general listing or one of the specialized ones.

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 downstream routing: entries of kind 'world' should be handled with the world tools, and the returned id is to be reused as projectId in the world bible tools. This is clear contextual guidance, but it offers no exclusions or explicit comparison against the sibling listing tools (list_worlds/list_stories).

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 openWorldHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the returned fields (storyId, world, persona, chapter count, word count, last update) and by hinting at the paging model via cursor, which no structured field provides.

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

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

Three tight sentences, front-loaded with the resource and scope, followed by return values and then filtering guidance. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description does the work of describing return values, and it covers filtering and paging adequately against 100% schema coverage and full annotation coverage. Minor gap: no explicit statement of default/max limit behavior in prose, though the schema covers 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 coverage is 100%, so all four parameters are already documented in the schema. The description's filter hints for q and worldId largely restate the schema descriptions rather than adding syntax, format, or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (stories), then disambiguates with synonyms (sessions, saves) and a definitional gloss ('private playthroughs they write inside a world'). This clearly separates it from siblings like list_worlds, list_scenarios, and search_stories.

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 usage guidance ('Filter with q ... or worldId instead of paging through everything'), which tells the agent how to avoid inefficient pagination. It does not, however, explicitly contrast with the sibling search_stories or state when-not to use this 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond them: that the default listing includes both playable and private worlds, that the all=true mode is admin-restricted, and that other users' drafts remain hidden. It does not discuss pagination or result limits, which is the main remaining gap.

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

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

Three tight sentences with no filler: scope and mode first, return payload second, onward routing last. Every sentence carries actionable information and the most important constraint (admin-only) is attached inline to the parameter that triggers it.

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

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

There is no output schema, so the description compensates by enumerating the returned fields (id, slug, title, worldKind, status, genres, counters), which is exactly what an agent needs to consume the result. Combined with the scope and permission details, the definition is complete for a single-optional-parameter read 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 description coverage is 100% and the single optional boolean parameter is already documented in the schema, including the admin restriction and the draft-visibility caveat. The description's '(admin only)' restates the schema rather than adding new meaning, so the baseline 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?

States a specific verb and resource ('List your Lunafic worlds') and even disambiguates the two scopes the tool covers: the caller's own playable/private worlds versus every platform world when all=true. It also names the return fields and the identifiers consumed by sibling tools, so it is distinguishable from get_world, list_scenarios, and list_stories 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 context: default behavior is scoped to the caller's own worlds, and the admin-only platform-wide mode is spelled out with its precondition. It also routes the agent forward by saying to use worldId or slug in the other world tools. It stops short of explicitly excluding siblings (e.g., when to prefer get_world for a single world), so it is clear but not fully comparative.

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=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond that: chunk sizing defaults/limits, the speaker-prefix format of returned lines, and the offset-chaining loop. It stops short of describing error conditions or whether offsets are stable across edits.

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, zero filler, and the core operation plus its paging loop are front-loaded before the alternative-tool guidance. Every clause carries information an agent needs.

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

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

There is no output schema, and the description compensates well by describing the line-prefix format and the presence of nextOffset as the termination signal. It leaves some ambiguity about chapter boundaries and nextOffset placement in the response, but a paging read tool is otherwise fully specified.

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 including the offset source ('nextOffset or a search match offset') and the maxChars default/cap. The description restates the same numbers rather than adding syntax or edge-case meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Read a chapter's text') plus the pagination model ('one page at a time'), which no sibling does. It also implicitly distinguishes itself from get_story and search_stories by routing the agent elsewhere for recaps and search.

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

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

Explicitly names the continuation condition ('Continue with nextOffset until it is null') and names two alternatives with the condition that selects them ('Prefer get_story recaps and search_stories over reading whole chapters'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safe read-only nature is covered. The description adds that search is keyword-based and limited to a scenario's entries, but says nothing about result limits, pagination, or what fields are searched.

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 front-loaded sentence that states the core action efficiently. It is not padded, but it may be too terse to carry necessary usage or parameter context.

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 has 3 parameters at 0% schema coverage and no output schema. The description leaves the agent without critical information about what query matches, how results are shaped, or how it relates to sibling retrieval tools, making it incomplete 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?

With 0% schema description coverage, the description provides no meaning for projectId, query, or limit beyond what their names imply. It does not clarify whether query searches entry titles, body text, or both, nor how limit behaves.

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 (keyword-search) and resource (entries of a scenario), so purpose is clear. However, it does not distinguish this from the sibling search_stories or from retrieval methods like get_world_bible, leaving potential ambiguity about keyword vs semantic lookup.

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?

No guidance on when to use this instead of get_world_bible or search_stories. The agent must infer that this is for keyword search within a scenario's entries, but no conditions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds match behavior the annotations cannot convey (exact substring, case-insensitive) and, importantly, describes the chained workflow: snippets carry a chapterId and an offset to pass to read_chapter. That is genuine behavioral context beyond structured fields.

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

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

Three tight sentences, each earning its place: what it searches, how to scope it, what it returns, and why to prefer it over reading chapters. The routing advice is placed last, after the mechanics, which is the right ordering.

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

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

There is no output schema, and the description compensates by describing the return payload (snippets with chapterId and offset) and the follow-up call to read_chapter. Combined with the schema's full parameter coverage, an agent has everything needed to invoke and use the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema omits: matching is exact and case-insensitive, and storyId narrows the search to a single story rather than just 'Limit the search to one story.' Those details affect how an agent crafts the query.

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 ('Find a word or phrase in the user's own stories') and immediately qualifies the match semantics as exact and case-insensitive. It also scopes the search space (every story, or one story via storyId), which separates it from siblings like search_entries and get_story.

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 routes the agent away from a sibling: 'Use this to find a moment instead of reading chapters one by one,' naming the read_chapter workflow it replaces. It also states the two scoping modes. It stops short of an explicit when-not-to-use (e.g., when to use search_entries instead), so it falls just shy 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 this is non-read-only, idempotent, and destructive. The description adds important behavioral context beyond that: the change affects only future stories, existing stories keep their numbers, and null restores the value's own start. It does not describe permissions or failure 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?

Three tight sentences with no wasted wording. Scope is front-loaded, the null behavior follows, and the copy workflow comes last as a useful operational hint.

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 five-parameter mutation with no output schema, the description covers the critical scope, reset behavior, and copy workflow. It leaves minor gaps like the optional slug's purpose, but annotations cover safety traits and the schema covers most parameters.

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 high at 80%, so most parameter meaning is already documented. The description adds useful semantics for the critical value parameter: null clears back to the value's own start, and a story-reached number can be copied by reading get_story_status. It does not explain slug or all parameter interactions.

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

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

The description states a specific action and scope: setting one character's start for one value, applying only to every NEW story while existing stories keep their numbers. This distinguishes it from status-reading siblings and from set_world_status less explicitly, but the core operation is clear.

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 a concrete usage scenario: to copy a number a story reached, read it with get_story_status and send it here. It also states that null resets to the value's own start. It stops short of explicitly saying when to use this instead of set_world_status.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses the exact blast radius: 'fields replaces the whole list (send every value you keep, with its id)', 'Only the parts you send change', and that every story of the world adopts the new setup on its next reply while keeping its own numbers. That is precisely the kind of mutation semantics an agent needs before overwriting a shared 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?

Purpose is front-loaded in the first clause, and nearly every sentence adds a distinct operational fact (merge semantics, exclusion, cross-story effect). It is a dense, comma-spliced single paragraph that could be broken into bullets for faster scanning, which 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?

For a 6-parameter mutation tool with no output schema, the description covers the consequential behavior: replacement semantics, character coverage and exclusions, removal, and downstream effect on existing stories. It does not say what the call returns or confirm there are no required parameters, a small residual gap.

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

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

With 83% schema coverage the schema carries most of the load, but the description adds real meaning: it explains the patch-vs-replace semantics of fields, the role of id in preserving story numbers, the appliesTo 'others' pattern for relationship bonds, and the exclusion behavior via excludedIds. The numeric range hint (0–10) is the only place it partially duplicates the schema's min/max.

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 — configure a world's Status schema (values, exclusions, window look) — and the scope sentence about all stories reusing the setup makes clear this is world-level, not per-story. It never names the sibling tools it differs from (get_world_status, set_status_start), so it stops short of explicit differentiation.

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 call it (setting up or changing a world's Status, including removal via remove: true) and even tuning advice such as 'one or two bonds track better than many' with a precise changesWhen. It lacks explicit when-not guidance or named alternatives, so it sits below 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description adds the genuinely useful partial-update rule that only supplied fields are overwritten, which qualifies the destructive framing. It does not disclose that existing values are replaced, that missing assets/permissions can fail, or what happens to unset fields (clear vs no-op).

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

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

Two short sentences, zero filler, with the partial-update rule front-loaded right after the affected fields. 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 10-parameter mutation tool with 20% schema coverage and no output schema, the description leaves most parameters and the result (does it return the updated entry?) unexplained. An agent would still need to guess at semantics for entryId, series, avatarUrl, and how to clear a field.

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 only 20% (only 'type' and 'inviteLine' are documented). The description merely re-lists name, tagline, description, tags, aliases and trails off with '...', adding no meaning for entryId, series, avatarUrl, or clearing behavior on the remaining params. With such low coverage, the description should compensate and does not.

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

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

Specific verb + resource ('Update an entry's metadata') with an enumerated field list, which clearly separates it from create_entry, delete_entry, and update_world. It does not name a sibling explicitly, but the update semantics are 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?

'Only provided fields change' communicates partial-update semantics, which is real usage guidance. However, there is nothing on prerequisites (a valid entryId must already exist, likely obtained via search_entries/get_world_bible) and no when-not-to-use or pointer to alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value beyond that by spelling out partial-update semantics and per-sub-list replacement ("each sub-list you send replaces that list while the others are kept"). One-way constraints are also disclosed (worldKind can only promote 'private' to 'playable'), though the destructive hint is never reconciled with what actually gets destroyed.

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

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

Dense and front-loaded: partial-update semantics come first, then the nested playable rules, then exclusions. No filler sentences, though the long run-on parenthetical about endings packs several constraints into one clause and reads tightly.

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 23-parameter mutation with no output schema, the description covers the trickiest nested structure well but leaves the majority of top-level fields unexplained. It also says status accepts "publish/unpublish" while the schema enum is draft/published/unlisted, forcing the agent to reconcile the two.

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 only 22% across 23 parameters. The description adds meaning for a handful—playable sub-lists, their max sizes, minTurns floored at 10, worldKind and status—but says nothing about rules, tags, genres, languages, visibility, derivation, authoringMode, dialogueFormat, targetAudience, or the two entry-id fields. Given the low coverage, the description does not compensate enough.

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 ("Update a world's V4 settings") and immediately clarifies the update semantics with "Only provided fields change." Sibling tools like get_world and create_world are distinguishable by name, though the description never explicitly says what it is not.

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 concrete routing for out-of-scope fields (cover art/wiki go to the Lunafic editor, intro video must be uploaded by the user on lunafic.ai), which is genuinely useful guidance. However, it gives no directive on when to use this vs. the sibling set_world_status, and in fact claims status changes belong here, leaving the agent to guess between two tools.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes far beyond: resize caps (512px/1280px), no-re-encode guarantee for in-cap PNG/JPEG, EXIF and appended-data stripping, GIF/format-to-PNG conversion, and a rate limit of 50 uploads/account/24h. It also names the return fields and the follow-up setters.

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 routing, then input paths, then format rules, then behavior. Dense but each clause carries real information. Slightly overstuffed with parentheticals, which slows scanning, but nothing is filler.

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

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

For a non-idempotent, open-world mutation tool with no output schema and no destructive annotation, every gap is covered: accepted/rejected formats, transformations, rate limit, return shape, and the required follow-up write tools. No output schema exists, yet the description still states the return object.

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

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

Schema coverage is already 100%, but the description adds meaning the schema lacks: sourceUrl is restricted to Google Drive and the share link is converted to a download link; dataBase64 tolerates a data: URI prefix; filename drives type detection; scenarioId accepts world id or projectId. These are non-obvious semantics beyond the schema text.

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

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

States a specific verb+resource ('Store an image and get a Lunafic-hosted URL back') and distinguishes its two slots (avatar vs scene) with required companions (entryId vs scenarioId). It also names the sibling it is not: 'For a LOCAL file an agent cannot inline as base64, call create_upload_url instead.'

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

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

Explicit when-to-use for each slot, explicit dual input paths (sourceUrl vs dataBase64), and an explicit routing rule to the alternative create_upload_url for local files. It even carves out an exclusion: the scenario COVER cannot be uploaded here.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context: isProtected hides the panel from forkers, language writes only that tab without touching main content, and empty content deletes the tab. That is exactly the kind of mutation-detail annotations cannot 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?

Everything is front-loaded in the first clause (create-or-update by title), then the special cases follow in decreasing order of importance. Every sentence earns its place; nothing is padding.

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

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

For an 8-parameter destructive upsert with no output schema and half the schema descriptions missing, the description covers the essential behavior: the key, the deletion path, the protection flag, and the language-tab workflow. The unelaborated 'summary' parameter and the required entryId's relationship to get_world_bible are the only residual gaps.

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 50%, and the description compensates for the undocumented parameters: it explains title as the lookup key, content's meaning and {{player}} convention, isProtected's protective effect, and the language tab rules. Only summary and the entryId relationship remain unaddressed.

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 ('Create or update one panel by title') and immediately clarifies the upsert key, which distinguishes it from update_entry and create_entry. The example ('set the Speech Style panel') pins the semantics further.

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 spells out the special case ('For Speech Style and Speech Examples only, pass language...') and the removal condition ('Empty content with language removes that tab'), plus points to get_world_bible for reading. It never explicitly routes between this tool and update_entry/update_world, so it stops short of full when-vs-alternative guidance.

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