velog_format_markdown

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

With no annotations, the description carries the full burden. 'Audit' implies a read-only check, but it never states whether the body is modified, whether findings block a save, what severity levels exist, or what the response looks like. For a validation tool invoked before a write, the absence of any statement about mutability or output is a real 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?

A single front-loaded sentence with no filler, and the three audit dimensions are enumerated compactly. It is efficient, though the brevity is part of why other dimensions are underspecified.

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 annotations, no output schema, and 0% parameter documentation. The description should therefore explain what an audit returns and whether it alters input, and it does neither. An agent cannot tell what to do with the result or how it relates to the create/publish siblings.

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 three parameters, and the description mentions none of them. 'Velog Markdown' loosely implies the body is the audited content, but title, tags, and their constraints (max lengths, tag limits) get no semantic treatment anywhere. The description 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?

The description gives a specific verb ('Audit') and resource ('Velog Markdown') plus the three check categories (structure, accessibility, secret-like content). However, it conflicts with the tool name 'velog_format_markdown', which suggests reformatting rather than auditing — an agent reading the name may expect the content to be rewritten. That tension leaves the core purpose only partially resolved.

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?

'before saving' hints at a workflow position but names no alternative. Siblings like velog_create_draft and velog_publish_post are obvious candidates for a 'run this first, then call X' instruction, and none are referenced. No when-not conditions are given either.

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