trmnl_render_markup

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that: it doesn't say what rendering produces (HTML? markup string?), whether variables are required for meaningful output, or what errors look like. The bare "POST" mention even sits in slight tension with readOnlyHint=true, though rendering is genuinely a read operation.

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?

It is short and front-loads the verb, but the second line is a bare endpoint fragment of little use to an agent, and the overall terseness reads as under-specification rather than efficient communication.

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 a nested required body object, 50% schema coverage, no output schema, and three similarly named markup siblings, the description should explain the render input semantics and likely output. Instead it supplies roughly two lines, leaving the agent to infer the entire contract from the schema alone.

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% and the undescribed halves are the important ones: body.markup (string or array of strings) and body.variables (free-form object) have no schema descriptions and no explanation in the tool description. Only the optional profile parameter is documented by the schema itself, so the description does not compensate for the coverage gap on the nested body.

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?

"Render Liquid template" names a specific verb and resource, but gives no hint of what rendering means here (server-side preview, output format, or scope of variables). It also fails to distinguish itself from close siblings like trmnl_read_markup, trmnl_write_markup, and trmnl_markup_validate, leaving the agent to guess which of the four markup tools to call.

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, no prerequisites, and no mention of alternatives. The only context is an API endpoint reference ("TRMNL POST /api/markup"), which tells an agent nothing about when rendering is preferred over validating or reading markup.

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