Fill a page from a file

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

Annotations already signal destructiveness, and the description goes beyond that by specifying exactly what happens: an existing page is overwritten when pageId is provided, an unknown pageId errors, and otherwise a new page is appended. It also discloses the fetch-local-from-server mechanism and the 'nothing crosses the bridge' detail, which is useful behavioral context.

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

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

Three sentences with no filler: the main purpose comes first, the distinctive server-side fetch behavior is second, and the pageId-dependent behavior is third. Every sentence contributes essential information and the structure is logical and easy to scan.

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

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

The description covers the tool's core behavior, preconditions (file already in data directory), destructive overwrite case, and the new-page fallback. With full schema coverage and the required parameters documented, this is sufficiently complete for correct invocation, though it does not describe return values or all possible error modes beyond unknown pageId.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaning by clarifying that pageId selects an overwrite targetament, that omitting it appends a new page, and that the path is relative to the data directory. This goes beyond the raw schema descriptions without restating them.

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

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

The description opens with a concrete action: 'Write an HTML file that is already in Foundry's data directory into a page.' It clearly distinguishes this tool from generic journal page tools by explaining the file-based mechanism, the overwrite-vs-add behavior, and the 'any size works' guarantee. This is specific enough to tell it apart from siblings like journal-add-page or journal-set-page.

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

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

The description explains the core usage context: use this tool when you want to put an existing HTML file from Foundry's data directory into a journal page. It also clarifies the branch behavior for with/without pageId. It does not explicitly name alternatives or state when not to use it, 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.