Update a quest journal

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

The description goes far beyond the sparse annotations, disclosing how HTML vs. plain text is stored, that Markdown is not converted, the side effects of completion/failure on status, the heading behavior, the mutual exclusivity of pageId/newPageName, and the read-back verification with the response format. This gives a complete behavioral model without any contradiction with annotations.

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

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

The description is well-structured with a clear intro, three bullet-pointed modes, and a final note on constraints and behavior. Every sentence adds unique information, and the list format makes it easily scannable. Despite its length, it is concise relative to the complexity it covers.

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 five parameters, three modes, and multiple side effects, the description covers all critical aspects: parameter usage, status updates, formatting rules, constraint violations, and response contents. There are no significant gaps that would prevent an agent from calling 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?

Although the input schema already describes all parameters, the description adds significant meaning: how newContent is interpreted, the conditional effects of pageId and newPageName, the semantic distinction between update types (e.g., completion sets status), and the relationship between parameters. This enriches the bare schema definitions and helps the agent use each parameter correctly.

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

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

The description opens with a specific verb and resource ('Write progress into a quest journal') and then details three distinct modes of operation, clearly distinguishing this tool from siblings like journal-append-page or journal-set-page. The purpose is unambiguous and immediately conveys what the tool does.

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

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

The description provides explicit usage context by detailing when to use each of the three modes (without pageId/newPageName, with pageId, with newPageName) and the constraint 'Pass pageId or newPageName, not both.' However, it does not explicitly compare this tool against alternatives (e.g., journal-append-page), so an agent might not know when to prefer this over others, though the specific behaviors make its primary use clear.

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