trmnl_unhide_author_plugin_error

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false. The description adds value the annotations can't: it discloses the underlying HTTP verb (TRMNL DELETE /api/analytics/hidden_errors), which explains why an 'unhide/restore' action is flagged destructive, and it restates the remote-state mutation and the authorization boundary. It does not describe the response or the effect of no matching row.

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?

Four short lines, front-loaded with the action, followed by the parameter precondition and the endpoint note. No filler, though the trailing 'Changes remote state or starts work' is generic boilerplate that only marginally earns its place next to the DELETE disclosure.

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 nested-object mutation with no output schema, the description covers what the tool does, what identifies the row, and the endpoint. It leaves gaps an agent would want: whether ownership/permission is required, what happens if the row is not currently hidden, and whether the call fails silently.

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 description names the four required nested fields (kind, subject_id, owner, message). The genuinely additive semantic is that these must be the same identity values that performed the hide, not just field names. It does not clarify the `kind` enum values (recipe / third_party) or mention the `profile` parameter.

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: 'Show a hidden error row again' identifies the operation and its inverse of hiding. It does not explicitly name the sibling trmnl_hide_author_plugin_error, but the wording 'again' clearly signals the counterpart operation, making the tool distinguishable from the rest of the plugin-error family.

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?

'Takes the same kind, subject_id, owner and message that hid the row' gives a concrete precondition for invocation — the caller must reuse the tuple that previously hid the row. It also states 'Run only within the user-authorized scope', a usage boundary. No explicit when-not guidance or sibling name, so not a 5.

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