Lunafic

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

Annotations already indicate it's not read-only, not destructive, not idempotent, and not open-world. The description adds relevant behavioral context: 'roles are live immediately' and the effect of seedPanels on panel creation, plus the interaction with import_brief. This goes beyond annotations, though it doesn't cover error conditions or permissions.

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 concise and front-loaded with the main action and key details. It uses parentheses for examples efficiently. However, the sentence about seedPanels is somewhat convoluted ('Omit seedPanels:false'), which could be clearer.

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

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

For a tool with 10 parameters, only 3 required, and low schema coverage, the description provides some critical context but leaves gaps. It doesn't explain projectId or type beyond mc_template, and doesn't mention that the entry is created within a world/project. Given no output schema, it should clarify what's returned. Partially 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 very low (10%), with only seedPanels having a description in the schema. The description compensates by explaining seedPanels behavior ('seedPanels:false' and defaults) and mentioning mc_template as a special type. It adds meaning beyond the schema for these key parameters, but doesn't cover other parameters like tags or description. Baseline 4 when zero params? But here 10 params, coverage 10%, description compensates partially, so 4.

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

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

Clearly states the action: 'Create a world bible entry' with examples (character, location, lore). It adds value by mentioning default panels pre-created. However, it doesn't explicitly differentiate from create_world or other creation tools, leaving some ambiguity about the scope of 'entry' vs 'world'.

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

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

It provides some conditional guidance: 'mc_template creates a player role' and 'Omit seedPanels:false if you plan to import_brief the panels separately.' This implies usage of mc_template and when to disable seedPanels, but lacks general when-to-use vs alternatives like update_entry or create_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?

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 already declare the safe-create profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. Beyond that, the description discloses the lifecycle behavior that annotations cannot: the world is created unpublished as a draft and requires update_world to become live, which materially affects how the agent sequences calls.

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, then the worldKind distinction, then the next-step pointer. Every sentence carries distinct information and nothing is repeated from 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?

For a 14-parameter creation tool with almost no schema documentation and no output schema, the description is too thin. It does not cover defaults, which optional fields drive the draft's behavior, constraints (e.g., the max-3 genre limit only exists in the schema for one property), or what the caller receives back, so an agent must guess at most of the payload.

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 7% across 14 parameters, and 7 of them are enums. The description explains the meaning of worldKind values, adding genuine significance beyond the bare enum, but leaves maturity, formality, dialogueFormat, targetAudience, derivation, authoringMode, characterLanguage, narrativeLanguage, hook, rules, and synopsis completely unexplained. It compensates for one parameter out of fourteen, which is well below what the low coverage requires.

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") and adds the important scope qualifier "as a draft," which separates it from the world-mutating siblings like update_world. It does not explicitly contrast itself with import_brief or create_entry, but the resource noun makes the target 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 concrete guidance on choosing between the worldKind values (private for your own writing, playable for players) and routes the agent to the follow-up step via update_world. It stops short of saying when to create a fresh world versus importing an existing brief, so exclusions are absent.

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

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

Annotations already 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 establish the safe read profile (readOnlyHint=true, destructiveHint=false), but the description goes further by disclosing the meaning of openingWarnings, why entries appear there, and the two remediation paths (rename the label or add an alias via update_entry). No mention of size limits or auth requirements, so not a full 5.

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

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

The core purpose is front-loaded in the first clause, followed by the return contents and then the openingWarnings remediation. It is dense but each sentence carries actionable content; the mc_template and playable-config enumeration is slightly list-heavy but 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?

With no output schema, the description does the work of explaining return contents and highlights the one non-obvious returned field (openingWarnings) with remediation steps. It is complete for invocation safety, though the slug/worldId parameter ambiguity leaves a small 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?

Schema coverage is only 50%: worldId is documented ('World id from list_worlds') but slug has no description. The description never mentions either parameter, so it does not compensate for the undocumented slug or explain whether both are required.

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 (read one world's full V4 state) and enumerates the exact contents returned: settings, rules, playable config, and mc_template roles. It is immediately distinguishable from siblings like get_world_bible, list_worlds, and get_world_status.

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 tells the agent to use this before update_world, and routes status-related needs away to get_world_status/set_world_status. It does not, however, clarify when to prefer get_world_bible or how this differs from list_worlds beyond the singular-world framing.

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 and non-destructive, so the safety profile is covered. The description adds real behavioral context: that it returns every entry and panel, that panels carry a guarded flag, and how speech language tabs and languageVariants work, including fallback 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 the core action (read every entry and panel) in the first sentence, then explains the speech-language tab model. Dense but each clause serves correct interpretation of the returned data; 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 carries the burden of explaining the return shape, and it does: entries, panels, content, isProtected, speechLanguage, and languageVariants with an example. An agent knows what it will get and how to interpret 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% and the single projectId parameter is fully documented in the schema ("Scenario id from list_scenarios"). The description 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?

States a specific verb and resource: reading every entry and panel of a scenario, including panel content and the isProtected flag. It is clearly distinguishable from get_world/get_story by its full-scenario scope, 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 an explicit precondition for using the tool relative to the write-oriented siblings (create_entry, update_entry, upsert_panel). It does not name alternatives for narrower reads such as search_entries, but the context is clear.

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

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

Annotations already declare 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 carry idempotentHint and destructiveHint, and the description adds real value on top: the matching keys (entries by type+name, panels by title), the update-instead-of-duplicate behavior, and that roles go live on import. It does not explicitly warn what existing data is overwritten by a re-run, which a destructiveHint=true operation would ideally state.

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 idempotency are front-loaded, and the dense detail about matching, roles, and language tabs all earns its place. Sentences are long but information-dense rather than 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?

For a destructive, idempotent bulk import with no output schema, the description covers format, idempotency semantics, role handling, and language-tab merging. The only notable omission is an explicit statement of what is overwritten on re-run, which matters given destructiveHint=true.

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 thoroughly compensates for the complex brief parameter by describing its format, entry/panel structure, and the special languages field. This adds substantial meaning beyond the schema's terse "parsed lunafic-brief/1 object."

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 (bulk-import) and resource (Lunafic Brief) plus its JSON format, which is far more specific than a tautology. It implies routing by noting when to prefer it, but does not name a sibling tool for the alternative path, so it stops short of full 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?

"Prefer this for whole characters AND player roles" gives clear selection guidance and calls out the mc_template role case with an inline-panels requirement. It lacks an explicit when-not or a named alternative sibling (e.g., upsert_panel/create_entry), leaving the exclusion 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?

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 destructive=true and idempotent=true, so the safety bar is partly covered. The description adds genuinely useful behavior beyond them: the change applies only to new stories, existing stories retain their numbers, and value=null reverts to the value's own start (an undo/reset path that contextualizes the destructive hint). Auth/permission requirements are not mentioned.

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 the scope constraint front-loaded and the null behavior and alternative workflow following in priority order. Slightly dense/idiomatic phrasing ('Give one character a different start') but no wasted text.

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

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

For a mutation tool with no output schema, the description covers scope, side-effect boundaries, and the null/reset path, and points to sibling tools for the IDs it consumes. Missing only permission/auth context; otherwise an agent has enough to call it correctly.

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

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

Schema coverage is 80% and the schema itself documents value as 'a number, one of the options, a few words, or null to clear'. The description only enriches the null case ('goes back to the value's own start'), adding marginal meaning over the schema. Baseline 3 is appropriate given the schema carries most parameter documentation.

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

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

The description names a specific action (set a start value) on specific resources (one character, one value) with a clear scope (every NEW story of the world). It implicitly distinguishes itself from set_world_status by narrowing to a single character/value, though it never names that sibling to sharpen the contrast.

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 operative condition ('every NEW story... stories already going keep their numbers') and routes the agent to a concrete alternative workflow: read the reached number with get_story_status and send it here. It gives clear when-to-use context but no explicit when-not-to-use beyond the new-stories scope.

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 safety profile (destructiveHint=true, idempotentHint=true), and the description adds exactly the context that matters: partial-update vs full-replace semantics of the fields list, the world-wide propagation scope ('every character... plus the player's character, unless excludedIds'), propagation timing ('from its next reply; each story keeps its own numbers'), and that no AI writes. This is rich disclosure well beyond the annotations.

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

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

Front-loaded with the core purpose, then moves through per-field guidance, merge semantics, scope, and propagation. It is a dense single paragraph that is long but nearly every sentence carries distinct information; slight run-on structure 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 nested-setup tool with no output schema, the description covers the merge/replace semantics, exclusion behavior, removal path, propagation to stories, and the no-AI guardrail. Combined with annotations handling safety, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is already 83%, so baseline is 3. The description adds meaning on top: it emphasizes changesWhen must be 'precise', advises 'one or two bonds track better than many', and clarifies the replace-vs-merge behavior of fields that the schema does not state.

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: 'Set up or change a world's Status', then enumerates the three things it controls (values, exclusions, window look). It is clearly distinguishable from read siblings like get_world_status, though it never names an alternative tool, so it stops short of an explicit sibling 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 usable conditions: 'Only the parts you send change', 'fields replaces the whole list (send every value you keep)', 'remove: true takes Status out of the world', and guidance to use one or two bonds. It never explicitly states when to choose this over set_status_start or get_world_status, so usage is well-contextualized but lacks stated exclusions.

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, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds one genuinely useful trait beyond them — patch semantics via 'Only provided fields change' — but says nothing about what destruction an update can cause (e.g. an entry type change, which the schema notes can be refused) or any permissions required.

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, front-loaded with the action and resource, with no filler. The trailing '...' in the field list is the one sloppy element, leaving the scope of updatable fields ambiguous.

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

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

For a 9-parameter mutation tool with no output schema and 11% schema coverage, the description is far too thin — it neither documents the parameters nor explains the destructive nature flagged by annotations, leaving an agent under-informed before a write.

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 11%: of 9 parameters, just 'type' is documented, and that documentation lives in the schema rather than the description. The description names name, tagline, description, tags and aliases but trails off with '...' and omits entryId, series, avatarUrl and type, so it does not compensate 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?

States a specific verb (Update) plus the resource (an entry's metadata) and enumerates several updatable fields. It is distinguishable from sibling mutations like update_world or create_entry, though it never names or distinguishes against those siblings 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?

There is no when-to-use guidance: nothing says when to update an entry versus creating a new one or editing via another tool such as upsert_panel. The only usable inference is the partial-update semantics from 'Only provided fields change'.

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 substance: 'Only provided fields change', per-sub-list replace-or-keep semantics ('each sub-list you send replaces that list while the others are kept'), and the one-way constraint that worldKind can only promote 'private' to 'playable'. It omits permission/auth requirements and what the call returns, so not a 5.

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, then constraints ordered from general semantics to nested sub-lists. Dense but nearly every clause carries a constraint; the playable sentence is a long run-on that could be broken up, but 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 a 22-parameter, deeply nested, no-output-schema mutation, the description covers the hardest surface (playable sub-list replacement) but leaves most scalar fields unexplained and gives no sense of the response. Adequate for the riskiest parameters, incomplete overall.

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 22 parameters and only 18% schema description coverage, the description carries a heavy burden. It does excellent work on the nested playable object (startingChoices max 6, endings max 7 with minTurns floored at 10 and mcRoleTemplateId binding, images max 100) but says nothing about the other ~18 fields (hook, slug, rules, genres, maturity, synopsis, formality, derivation, authoringMode, dialogueFormat, languages, etc.).

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?

Names a specific verb and resource ('Update a world's V4 settings') and the description scopes which parts of the world it touches (status, playable config, worldKind). It does not, however, distinguish itself from the sibling set_world_status, which appears to overlap with the 'Set status to publish/unpublish' capability stated here.

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 rather than framed against alternatives: it tells you partial updates are safe and that cover art and wiki content belong to the Lunafic editor (a soft 'not here' signal). There is no explicit when-to-use versus set_world_status, update_entry, or create_world, leaving the agent to infer routing.

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

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

Annotations 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 cover the key traits (destructiveHint=true, idempotentHint=true, not read-only). The description adds valuable context beyond them – protection semantics and the language-tab removal rule (empty content + language deletes the tab) – but omits permission requirements, overwrite/merge behavior for omitted fields, and error conditions.

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?

Efficient and front-loaded, but the 'Speech Style' language-tab explanation is dense and slightly convoluted, mixing main-content vs. tab semantics in one run-on sentence.

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?

Covers the core create/update-by-title flow and the trickiest parameter (language) well, but with no output schema and only 50% schema coverage, the description doesn't fully address 8-parameter complexity or return/error behavior.

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%, so the schema documents roughly half the 8 parameters (aiSees, content, language). The description reinforces content, isProtected, and language semantics, adding value over the schema for those, but leaves type/summary/entryId undocumented – partial compensation only.

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 (create/update) and resource (panel), with concrete example ('Speech Style') and the title-keyed semantics. It's clear against siblings like update_entry/update_world, though it doesn't explicitly name an alternative 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?

Implies usage (upsert by title, language-tab behavior for Speech Style/Examples) but offers no explicit when-to-use vs. alternative like update_entry, and no prerequisites or exclusions.

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