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

Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) already cover safety, but the description adds valuable context: it states it scrapes all posts and may take several seconds due to multiple requests. This proactively sets expectations about performance and data-gathering behavior, which annotations do not convey.

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 three concise sentences: it states the core function, the deliverables, and the performance caveat. Every sentence adds value, with no redundancy or filler. It is well-structured and front-loaded with the primary purpose.

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?

Given the complexity of the tool (aggregation over all posts), the description sufficiently covers what it computes and what it returns (distributions, rankings). It also notes latency behavior. With no output schema, the description gives enough detail for an agent to understand the expected result, though it could mention edge cases like empty user accounts, but that is minor given other structured fields.

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 100%, with clear descriptions for top, username, and max_pages. The description adds context about the tool's overall function but does not provide additional parameter-specific meaning beyond what the schema already documents. Baseline of 3 applies since the schema carries the parameter documentation burden.

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 clearly states it aggregates views, likes, and comments for a user's posts, and provides year/tag distributions and top post rankings. This specific verb+resource combination distinguishes it from sibling tools like velog_list_posts or velog_trending_posts, which list or rank posts differently.

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 that this tool is needed because the stats screen does not exist on Velog, implying it should be used when such aggregated stats are required. It doesn't explicitly name alternative tools, but it gives clear context for when this tool is appropriate, such as when users need computed statistics rather than raw lists.

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

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

Annotations already carry readOnlyHint=false, destructiveHint=true, idempotentHint=false. The description adds meaningful context beyond annotations: the draft is never published under any setting, only the author can see it, and publishing requires a separate explicit call. This clarifies what the destructive hint implies for this create operation without contradicting it.

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 short sentences with zero waste. Core purpose is front-loaded, scoping constraint (no publication) comes second, and the alternative tool is named third. Every sentence earns its place.

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 7-parameter tool with 100% schema coverage and a rich schema, the description plus schema together cover purpose, safety profile, and param semantics well. The only gap is no return-value description, but there is no output schema, and this is a create operation whose main side effect is well disclosed.

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 100% and the schema is exceptionally rich — body has detailed style rules, title has formatting constraints, series_id/thumbnail/series_name all carry behavioral notes. The description only adds 'body is Markdown', which the schema already states, so it adds little beyond the schema. Baseline 3 is appropriate.

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?

Description states a specific verb (creates a draft) and resource (Velog draft), and clarifies it is not published and only visible to the author. It explicitly distinguishes itself from sibling publish/update tools, so an agent can tell it apart immediately.

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?

Explicitly states when NOT to use it ('does not publish under any settings') and names the exact alternative tool (velog_publish_draft) to call for publishing. Also states body must be Markdown. This is clear routing guidance with an explicit exclusion.

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

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

Annotations already signal read-only, non-destructive, and open-world behavior. The description adds that authentication is not required and that the underlying API is unofficial and volatile, which is useful beyond the annotations. It does not contradict the 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 primary action is front-loaded, and the supporting context is compact. The final sentence partly restates annotation-provided read-only/no-auth facts, but the description as a whole is efficient and not padded.

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 zero-parameter diagnostic tool with strong annotations, the description provides enough information to select and invoke it correctly: what it compares, when to use it, that it requires no auth, and why it may fail due to the unofficial API. No critical guidance is missing.

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?

The tool has zero parameters, so there is no parameter burden to explain. The baseline for a no-parameter tool is 4, and the description correctly focuses on purpose rather than inputs.

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 states a specific verb and resource: comparing the current Velog GraphQL schema against the baseline schema from server creation. It clearly distinguishes this diagnostic tool from the sibling content/post tools by focusing on schema drift rather than data operations.

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?

It explicitly says this is the primary diagnosis tool when tools fail for no apparent reason or responses look malformed. It also explains that Velog is an unofficial API and can change without warning, giving an agent enough context to know when to run this check.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=true, and the description adds substantial context beyond them: the deterministic file naming explains why re-downloading overwrites only that post's file, it discloses one-by-one fetching and the time cost for many posts, and it explains the skip_existing resume heuristic. This is consistent with destructiveHint=true and enriches the safety profile meaningfully. It stops short of describing the return value or failure behavior, so not a 5.

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 front-loaded sentences where the purpose leads, followed by the rationale and behavior notes (overwrite, performance). Every sentence carries distinct information and there is no filler; only the 'official export missing' rationale is arguably non-essential, keeping it from a 5.

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 4-parameter tool with no output schema, the description covers the operation, naming, overwrite, and performance well, and the schema covers parameters. However, it never hints at what the tool returns on success or failure for a local-file-writing operation, which an agent needs to confirm completion — especially given destructiveHint=true and the absence of an output schema.

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 100%, so the schema already documents all four parameters (limit, out_dir, username, skip_existing). With full coverage, the baseline is 3. The description adds only marginal value beyond the schema — chiefly the file-naming convention that underlies skip_existing and overwrite semantics, but it does not clarify per-parameter syntax or formats beyond what the schema already states.

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 states a specific verb (export/save), a specific resource (one user's VeloLog posts), and a precise output format (markdown files with frontmatter saved locally). It also frames the file naming convention (slug--postid.md). None of the 21 sibling tools perform export, so it is clearly distinguishable by operation alone.

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 motivation ('no official export exists, so this was built') but never explicitly tells an agent when to use it vs. an alternative, nor names a substitute tool or exclusion condition. There is no sibling that overlaps with export, so usage is implied rather than stated; no explicit routing guidance is provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing that it fetches the full post body and explaining the two valid identifier combinations, which is useful behavioral context beyond the 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 two sentences long, front-loaded with the core function, and includes a practical example with zero filler. Every sentence contributes to understanding what the tool does and how to use it.

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 simple parameter set, full schema descriptions, and safety annotations, the description is complete. It explains the identification methods and states the tool returns the post content, making it sufficient for an agent to invoke correctly without an output schema.

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%, with each parameter described in Korean. The description's example ('https://velog.io/@velopert/react-context-tutorial → username="velopert", url_slug="react-context-tutorial"') adds meaningful context by showing how parameters map to a real URL, and it reinforces the id-optional relationship already present in the schema.

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 clearly states the tool reads a single Velog post including its full body, using a specific verb ('읽어온다') and resource ('벨로그 글'). It distinguishes itself from sibling tools like list/search/trending by targeting one post, and provides a concrete URL example for identification.

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 implies when to use this tool—when you need the full content of a specific post—and how to specify it (by id or username+url_slug). It doesn't explicitly mention alternatives or when not to use it, but the purpose is clear enough for an agent to differentiate from list/search operations.

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

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

Annotations already declare this as a safe read operation (readOnlyHint=true, destructiveHint=false), and the description adds the specific data returned (profile and follower count). It does not contradict the annotations, but also provides no additional behavioral context like response format or authentication requirements.

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 a single, focused sentence that states exactly what the tool does with no filler or unnecessary detail.

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 simple read-only tool with one parameter and strong annotations, the description is sufficient. It specifies the key return values (profile and follower count), and the schema handles parameter documentation. No output schema exists, but the description names the main outputs.

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?

The schema covers the only parameter 'username' with a description '@ 없이', giving 100% schema coverage. The description itself adds no new parameter semantics beyond what the schema already documents.

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 uses the specific verb '조회한다' (retrieves) and names the resource as the user's profile and follower count. It clearly conveys the tool's primary function, though it does not explicitly contrast it with sibling tools like velog_user_tags or velog_whoami.

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 no guidance on when to use this tool versus alternatives. It only states what the tool does, with no mention of specific use cases, exclusions, or references to sibling tools.

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

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

Annotations already declare readOnly and non-destructive. The description adds that this tool returns draft IDs for later editing and implicitly that it shows only the user's own drafts (reinforced by the username schema description). No contradiction.

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?

Two short sentences deliver purpose and usage, no redundant content.

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 annotations covering safety and schema covering parameters, the description provides a solid, complete context for a simple listing tool. It could mention the return format but the purpose implies it.

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 covers username semantically; limit is constrained but lacks description. The tool description does not explain parameters directly, but the schema's structural constraints and the username description provide adequate meaning for this simple tool.

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 explicitly states '내 임시저장 글 목록' (my temporary saved posts list) and explains that IDs are checked here before editing, clearly distinguishing it from sibling tools like list_posts.

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?

It provides a clear when-to-use: '초안을 이어 쓰거나 수정하기 전에 id를 여기서 확인한다' - before continuing or editing a draft. No explicit alternatives are named, 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.

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral details: posts are returned in latest order, can be filtered by tag, and pagination is driven by providing the last post id as cursor. This gives the agent a clear model of how the tool behaves without repeating annotation info.

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 concise sentences cover the core operation, filtering, and pagination, with no redundant or filler content. Information is front-loaded with the main action first, making it easy to parse.

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?

Given the tool has 4 parameters, no output schema, and provides annotations for safety, the description covers the essential behavior: list, order, filter, and pagination. It does not mention error cases (e.g., user not found) or response format, but for a read-only list tool with good annotations, these omissions are acceptable.

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?

The schema already covers 75% of parameters descriptively, and the description reinforces their roles: tag narrows the list, cursor enables pagination, and username targets the author. It adds the 'latest order' context which is not in the schema, and the limit parameter is adequately handled by schema constraints. The description adds enough extra meaning to compensate for the 75% coverage.

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 clearly states the tool's action: fetching a specific user's post list in latest order. It differentiates from siblings like velog_get_post (single post) and velog_search_posts (global search) by focusing on a per-user listing with optional tag filtering and pagination.

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 clear context for when to use this tool: when you need a specific user's posts sorted latest-first, optionally narrowed by tag, and when you need pagination. It does not explicitly exclude alternative tools, but the purpose is well-scoped enough for an agent to select it over the generic search or trending tools.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds that the tool returns post counts per series, which is useful behavioral context beyond the annotations. It does not describe pagination or ordering, but these are not critical for a simple list tool.

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 two sentences long, front-loaded with the core purpose, and every sentence adds value: the first states what it does, the second explains how to use the returned id. No filler or redundancy.

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 simple single-parameter list tool with good annotations and no output schema, the description sufficiently covers what the tool returns (series list with post counts) and how the returned id is used in another tool. It is complete for the agent to select and invoke 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?

The input schema describes the only parameter (username) with '@ 없이', providing 100% coverage. The description does not add anything about the parameter beyond what the schema already states, so the baseline score of 3 is appropriate.

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 clearly states it lists a user's series and includes the number of posts in each series. This specific verb+resource combination distinguishes it from sibling tools like velog_list_posts, and there is no other series-listing tool among the siblings.

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 explicitly tells when to use this tool: to get the series id needed for assigning a draft to a series, referencing velog_create_draft's series_id parameter. It provides a clear workflow but does not mention exclusions or alternatives, though no direct alternative exists for listing series.

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

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

The description discloses that the body is not passed again (saved content is used) and that publication is private-only unless VELOG_ALLOW_PUBLIC=1 is set. This adds valuable behavioral context beyond the annotations, which already signal destructive and non-idempotent behavior. It stops short of explaining side effects on the draft itself, but it is still informative.

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 two concise sentences, front-loaded with the core action and followed by a key limitation. Every sentence earns its place with no redundant information.

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 single-parameter publish action, the description covers the essential behavior and a major constraint. It could mention what happens to the draft after publishing or the return value, but given the tool's simplicity and existing annotations, the description is sufficiently complete.

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?

The schema already describes the id parameter and how to find it via velog_list_drafts. The tool description adds that no body needs to be passed, reinforcing that the only required input is the draft ID. This is a useful semantic addition beyond the schema's parameter description.

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 clearly states the specific action: 'Publishes an existing temporary draft' with a distinct verb and resource. It also clarifies that the body uses saved content, which differentiates it from tools like velog_publish_post that would create a new post.

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 gives clear context for when to use this tool: with an existing draft ID, and it notes the private-only default and the condition for public publishing. However, it does not explicitly name alternative tools or state when not to use it, such as when publishing a new post from scratch.

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

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

Annotations already declare readOnlyHint:false and destructiveHint:true, but the description adds critical behavioral nuance: the private-only publishing constraint and the required environment variable, plus the fact that the action can be reversed via unpublish. This goes beyond the annotations and informs the agent of important side effects and preconditions. No contradiction with annotations; destructiveHint:true is consistent with the act of making a post live, though the description clarifies it is reversible.

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 two sentences, front-loaded with the primary action ('새 글을 바로 발행한다'), followed by the crucial constraint and the undo alternative. Every sentence adds value, and it avoids fluff. It is optimally concise for the information density.

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 publishing tool with 7 parameters (2 required) and no output schema, the description adequately covers the action's semantics, constraints, and reversal path. The only gap is that it doesn't mention the return value (e.g., the published post object) or error handling, but given the tool's simplicity and the schema's param details, this is a minor omission. The description is otherwise complete for correct invocation.

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?

The schema covers 71% of parameters with descriptions (body, title, thumbnail, series_name), and the tool description adds no parameter-specific semantics beyond what the schema provides. The description does mention the private-only behavior but not tied to any parameter. Since coverage is moderate (not below 50%), the baseline of 3 is appropriate; the description does not compensate for the uncovered parameters (tags, url_slug, series_id) but those are self-explanatory given their names and defaults.

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 clearly states the action: '새 글을 바로 발행한다' (publishes a new post immediately). It explicitly distinguishes from draft-based workflows ('초안을 거치지 않는다') and from the sibling velog_publish_draft (which publishes an existing draft). The resource (new post) and verb (publish) are specific, and the immediate/direct nature sets it apart from related tools.

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 gives explicit usage context: it publishes directly without a draft, and it notes the current configuration restricts to private-only unless VELOG_ALLOW_PUBLIC=1 is set. It also names the alternative for undoing the action (velog_unpublish_post). This provides clear when-to-use and when-not-to-use guidance, including a specific sibling.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds the global scope ('전체') and a browsing-oriented behavior, but does not disclose details like pagination behavior, time window, or result shape. This is acceptable given the strong annotation coverage.

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?

Two short, front-loaded sentences. The first states the resource, the second gives the use case. No filler or redundancy.

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 simple read-only list tool with good annotations and a clear schema for its two parameters, the description is complete enough. It does not describe return values, but no output schema exists and the purpose is straightforward. Pagination is implied by the cursor param and documented in the schema.

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?

The description does not discuss parameters, and schema coverage is 50%. However, both parameters are simple: 'limit' is self-explanatory with type/min/max/default in the schema, and 'cursor' already has a clear schema description ('이전 페이지 마지막 글의 id'). No additional meaning is needed beyond what the schema provides.

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?

Description clearly states it returns '벨로그 전체 최신 글' (all latest posts on Velog), and the phrase '지금 무슨 글이 올라오는지 훑을 때' provides a specific browsing purpose. It is distinguishable from siblings like velog_trending_posts and velog_search_posts, though it does not explicitly name alternatives.

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 gives a clear usage context: use when skimming what posts are currently being published globally ('지금 무슨 글이 올라오는지 훑을 때'). It does not explicitly state when not to use it or mention alternative tools, but the context is strong enough to guide selection.

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

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

Beyond the annotations (which are all false and provide no behavioral hints), the description discloses adaptive text fitting: line wrapping and font-size reduction based on actual measurements. It also implies the output is a URL ('returned address'). This adds meaningful context about how the tool behaves. It does not mention the upload default behavior, but no contradiction exists.

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 two sentences, front-loaded with the primary purpose, followed by behavior and integration instructions. Every clause provides value, with no redundancy or filler. It is concise and well-structured for agent consumption.

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 core purpose, adaptive behavior, and integration with velog_update_post, which is essential for basic use. However, with eight parameters, no output schema, and sparse annotations, it omits details on several parameters (e.g., tone, subtitle, upload, post_id) and the exact return format. It is sufficient for a simple call but not fully complete for all scenarios.

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 only 25% (footer and kicker have descriptions). The description adds no semantic meaning for the remaining six parameters (title, subtitle, tone, tags, upload, post_id). It references title only in the context of wrapping behavior, not its semantics. Given the low schema coverage, the description fails to compensate, leaving agents without guidance for most parameters.

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 clearly states the tool's function: creates a cover image (1200×630) for post lists and SNS previews. It uses a specific verb (makes) and identifies the resource (cover image), effectively distinguishing it from sibling tools like velog_render_diagram and velog_upload_image.

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?

Provides clear context for when to use: to generate cover images for post lists/SNS previews. It also explicitly instructs to pass the returned URL to velog_update_post's thumbnail, demonstrating a concrete workflow. It doesn't state exclusions but offers sufficient guidance for correct usage.

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

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

With annotations only declaring readOnlyHint=false/idempotentHint=false/destructiveHint=false, the description carries the full burden of behavioral disclosure and delivers richly. It reveals that the tool uploads to Velog (mutation), that a self-check can refuse to upload and explain the problem, that this gate cannot be disabled, and that rejected outputs are also barred from velog_upload_image. It also discloses auto-layout mechanics (browser-measured node width, canvas, line bends, label positions). This is exactly the kind of value annotations don't provide. No 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 longer than average but every block earns its place: purpose first, then mechanics, then the rejection gate, then style tips, then the two value enumerations. The icon/tone lists are verbose but essential since they're the sole source of valid values. The '밋밋하게 나오면 입력이 밋밋한 것이다' (dull input yields dull output) line is a memorable editorial touch that conveys a real constraint.

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?

There is no output schema, so the description correctly states the return contract: 'returns markdown to attach to the post body.' For a complex tool with 10 parameters and nested structures, the description covers the key decision-critical behaviors: auto-layout, rejection gate, and upload semantics. The post_id and subtitle parameters are documented in the schema, so their omission from the description is acceptable.

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 only 50%, so the description must compensate, and it does. It enumerates the valid icon values (alert arrow bell bolt ... terminal user) and tone values (slate gray blue ... rose indigo), which appear nowhere in the schema. It explains the coordinate philosophy ('origin can be anywhere — canvas auto-fits'), how w is measured when omitted, and how to use groups/planes for visual grouping. It adds real semantic value beyond the schema fields.

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-resource pair: 'Draws a configuration/flow diagram, creates a PNG, uploads to Velog, returns markdown.' This clearly distinguishes a diagram-generation tool from the write/read/post siblings. However, it does not explicitly differentiate from the render_* siblings (velog_render_sequence, velog_render_cover); the distinction is only implicit via '구성도·흐름도' (architecture/flow diagram). It does reference velog_upload_image explicitly, which helps.

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 strong how-to-use guidance: give coordinates and let the renderer auto-layout, use icons/tags/groups/planes for a hand-drawn look, align y for straight lines, and expect rejection if the self-check fails. What's missing is explicit when-to-use vs alternative routing — it never says 'for sequence diagrams use velog_render_sequence' or 'for covers use velog_render_cover.' The velog_upload_image mention is only negative (rejected outputs aren't accepted there).

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

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

The description discloses several behavioral traits beyond the minimal annotations: it uploads to Velog (side effect), it runs an automatic geometric audit that can reject output and prevent upload, the audit cannot be disabled, and rejected images cannot be uploaded via velog_upload_image. It also explains layout behaviors like auto-widening, folding, and how vertical size is dominated by input structure. These are valuable and non-obvious details that guide agent behavior.

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 long but well-structured: it leads with the core purpose, then a bold note about coordinates, then a warning about audit behavior, then a list of kinds, icons, and tones. Every sentence adds information, and formatting (bullets, bold) improves scannability. It is appropriately sized for the tool's complexity and avoids redundancy.

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 11 parameters, no output schema, and rich behavioral rules, the description covers the essential context: when to use it, how to structure input for good results, what the audit does, and what happens on failure. It does not describe the return value explicitly, but given that the tool uploads and likely returns a reference, this is a minor gap. Overall, it is complete enough for an agent to call it correctly and anticipate outcomes.

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?

The schema already documents parameters well (82% coverage). The description adds some semantic context: message array order equals time order (also in schema), call needs matching return (also in schema), note is for description boxes (in schema). However, it adds new meaning about auto line-breaking on separators and the rule that only long Korean tokens without separators need manual breaking. This is helpful but not critical for parameter understanding since schema covers most, so a 4 is warranted.

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 clearly states the tool draws sequence diagrams from participants and ordered messages, renders them as PNG, and uploads to Velog. It explicitly distinguishes itself from velog_render_diagram by specifying that for non-temporal diagrams (구성도/흐름도), the sibling tool should be used. This leaves no ambiguity about what this tool does and how it differs.

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 guidance on when to use this tool vs velog_render_diagram ('구성도나 흐름도(시간 축이 없는 그림)는 velog_render_diagram 을 쓸 것'). It also gives concrete input-shaping rules to achieve good output: matching calls with returns, keeping notes to one line, and handling long labels with separators. This is actionable usage instruction, not just a generic statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scoping behavior (entire Velog vs. user-specific), which is useful context, but it does not disclose return format, rate limits, or authentication needs. With annotations in place, this is adequate but not deeply transparent.

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 two sentences long, front-loaded with the main purpose, and includes a memorable use-case example. Every word earns its place, with no repetition or filler.

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 search tool with 4 parameters, annotations, and no output schema, the description covers purpose, scoping, and a practical use case. It does not explain the return structure, but the schema documents offset for pagination. Overall, it is reasonably complete, though a bit more detail about result contents would push it higher.

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 75%, with keyword, username, and offset already documented. The description's phrase 'username 을 주면 그 사람 글 안에서만 찾는다' reinforces the username meaning but is largely redundant with the schema's '이 사용자의 글로 한정'. No additional detail is provided for limit or offset beyond what the schema already states.

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 uses the specific verb '검색한다' (search) with the resource '벨로그 전체' (entire Velog), clearly distinguishing it from sibling tools like velog_list_posts, velog_trending_posts, and velog_recent_posts. The optional username scoping adds further precision, making the tool's purpose immediately clear.

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 explicitly provides a concrete use case: '내가 예전에 쓴 그 글' 을 찾을 때 이 조합을 쓴다 (use this combination when looking for a post I wrote). This gives clear context for when to pair keyword with username, though it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, and the description adds beyond them: no auth required, the year-period limit>20 empty-result quirk, the offset cap of 1000, and that adjusted values are reported in the response. This discloses important edge-case behavior not available from annotations alone.

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?

Front-loaded with the core concept, then scope clarification, use cases, sibling routing, and edge cases in a logical order. Every sentence earns its place and there is no filler or redundant restatement of the title.

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 3-parameter read-only tool with no output schema, the description plus annotations and rich schema fully cover selection, invocation, authentication, edge cases, and response adjustment notes. Nothing an agent needs to call it correctly is missing.

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 100%, and the schema already documents limit/offset/timeframe in detail, including the year edge cases. The description repeats those constraints rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.

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?

Description states a specific verb+resource: '벨로그 전체에서 지금 많이 읽히는 글' (Velog-wide currently popular posts), and explicitly clarifies it is a global ranking, not the user's own posts. It also contrasts with velog_list_posts and velog_search_posts, making the purpose unmistakable.

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?

Explicitly tells when to use the tool ('무엇이 반응을 얻는지, 어떤 주제가 도는지 볼 때') and names alternatives for related cases: specific user's posts → velog_list_posts, search → velog_search_posts. Also states it is not for one's own posts, giving clear exclusions.

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

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

The description adds meaningful context beyond annotations: it clarifies that the post is not deleted (countering destructiveHint), and discloses that RSS/subscription emails are not recalled and search engine caches persist. This addresses potential consequences of the 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?

Two concise sentences, the first states the primary action clearly, the second adds necessary caveats. The use of a star highlights the important side-effect. No wasted words.

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 simple mutation tool with one parameter and no output schema, the description is comprehensive. It explains the outcome (draft list), the non-deletion, and external side effects. This fully covers the user's likely concerns.

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% for the single parameter 'id', which is described as the ID of the published post. The description adds no additional parameter semantics beyond what the schema already provides, so baseline 3 applies.

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 clearly states the verb and resource: reverts a published post to draft. It distinguishes from siblings like publish_post and publish_draft by explicitly targeting the unpublish action. The title also reinforces the purpose.

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 doesn't explicitly name alternatives, but the action is unambiguous: use this when you need to revert a published post to draft. The context of not deleting the post helps set expectations. No exclusions are stated, but the purpose is sufficient for selection.

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

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

Beyond the destructiveHint annotation, the description details exactly what destruction occurs: omitted fields are reset, missing tags are deleted, missing url_slug is regenerated from the title changing the URL, and missing series_id breaks the series link. It also discloses the safety guard that published post IDs are rejected. This is rich behavioral context that the annotations alone would not provide.

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 front-loads the most critical fact (wholesale replacement), then lists concrete consequences, then gives a preventive workflow, then mentions a safety constraint. Every sentence carries load-bearing information; nothing is filler. Despite covering several behavioral nuances, it remains compact and scannable.

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 destructive 8-parameter tool with no output schema, the description thoroughly covers behavioral risks and pre-conditions. It explains omitted-field semantics across multiple parameters and the published-post guard. The only notable gap is the absence of any mention of the return value or success/failure response, which is mildly important when no output schema exists.

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?

With only 63% schema coverage, the description compensates by explaining the behavioral consequences of omitting key optional parameters: tags, url_slug, and series_id. It adds meaning beyond the schema by stating that omission resets these fields. It does not discuss thumbnail or series_name, but the schema already covers those reasonably, so the total compensation is solid though not exhaustive.

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?

Description opens with a specific verb and resource: '기존 초안을 통째로 교체한다' (replace an existing draft wholesale), making the core action unambiguous. It further distinguishes itself from sibling update tools by rejecting published post IDs, which separates it from velog_update_post.

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 gives clear when-not guidance: published post IDs are rejected, meaning this tool is only for drafts. It also recommends reading current values with velog_get_post before updating and passing unchanged fields, which is actionable usage context. However, it does not explicitly name velog_update_post as the alternative for published posts, so the routing is slightly less direct than ideal.

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

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

Beyond the destructiveHint annotation, the description adds valuable behavioral context: published status is preserved, omitted fields retain existing values, draft IDs are rejected, and visibility scope cannot be changed under the current configuration. No contradiction with annotations exists.

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 front-loaded with the main purpose and each sentence carries substantive information. It is slightly dense with multiple clauses and configuration details, but nothing feels wasted given the complexity of the behavior being described.

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 mutation tool with 8 parameters and unusual partial-update semantics, the description plus schema provides enough context to call it correctly: required id, behavior for omitted fields, draft exclusion, visibility constraints, and the alternative tool for drafts. No output schema is present, but return values are not essential for correct invocation.

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?

The description adds important tool-level parameter semantics: omitted fields keep existing values rather than resetting, which is central to correctly using the optional parameters. The schema already covers most parameters well, though id and series_id still lack direct explanation in either the schema or description.

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: '이미 발행된 글을 수정한다' (edits an already-published post). It also distinguishes itself from sibling velog_update_draft by explicitly stating that draft IDs are rejected and draft editing belongs to a different tool.

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 gives clear when-to-use guidance: use this for published posts, not drafts, and explicitly names velog_update_draft as the alternative. It also contrasts the partial-update behavior with the draft tool's full-replacement behavior, further guiding correct tool selection.

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

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

The description discloses critical behavioral traits beyond the minimal annotations: it specifies valid formats (PNG/JPEG/GIF/WebP) and that detection is by content, not extension. It also warns that uploaded URLs are public, there is no deletion API, and encourages pre-upload verification. This adds significant and non-obvious context, giving the agent both safety and operational awareness. The annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) are not contradicted; rather, the description enriches them.

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 three sentences: the first states purpose, the second provides format constraints, the third conveys a critical warning. It is front-loaded, and every sentence adds distinct value. The use of a warning symbol and bold for '파일 내용' draws attention without unnecessary verbiage.

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?

Given no output schema, the description provides a clear output expectation ('markdown for the body') and covers key behavioral constraints (file types, public URLs, no deletion). It also benefits from schema descriptions that explain the 'type' and 'post_id' parameters. Minor gaps remain, such as exact markdown format or error handling for invalid files, but overall the definition is well-rounded for an agent.

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 75% (descriptions for path, type, post_id; alt lacks one). The description adds meaning to the path parameter by constraining accepted file types and specifying content-based validation, which is not present in the schema. It also clarifies the tool's output (markdown) relevant to the overall parameters. While not detailing each parameter syntax, it compensates for the alt gap partially and enhances the path semantics above the baseline.

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 clearly states a specific action: 'Uploads a local image file to Velog and returns markdown for the body.' It names the resource (local image), the destination (Velog), and the output (markdown), distinguishing it from sibling tools like velog_render_cover or velog_update_profile_image (the latter explicitly referenced in the type parameter).

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 implies the primary use case (uploading images for post body markdown) through the phrase '본문용 마크다운' and warns about appropriate file types. An explicit alternative is provided in the type parameter description: 'profile 은 프로필 사진용 분류일 뿐 — 사진 교체는 velog_update_profile_image' (profile is just a classification; replacement goes to velog_update_profile_image). However, this alternative is not in the main description, only in the schema, so it lacks the explicitness of a fully self-contained usage guideline.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds minimal behavioral context beyond that (only that it's 'cheapest'). No mention of pagination, ordering, or rate limits, but given the annotations, the bar is lower and the description does not contradict them.

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 extremely concise, using one sentence to state the output and another to provide a use case. It front-loads the purpose with no filler, making it easy to parse.

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 simple two-parameter read-only tool, the description covers the core purpose and return content, but it omits details about ordering, limit semantics, and edge cases (e.g., empty result). Since there is no output schema, the description could be more explicit about the return structure.

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%: 'username' has a description ('@ 없이'), but 'top' has none. The tool description does not explain what 'top' controls (e.g., number of tags to return). Since the description does not compensate for the undocumented parameter, it fails to add semantic value beyond the schema.

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 clearly identifies the tool's function: it returns a user's tags with post counts. It also provides a concrete use case ('이 사람이 뭘 주로 쓰나'를 가장 싸게 파악하는 방법), which distinguishes it from sibling tools like user info or post lists by focusing on aggregated tag statistics.

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 gives a clear context: use it to quickly understand a user's main writing topics. It implies this is a cheap, high-level alternative to reading individual posts, but it doesn't explicitly mention when not to use it or name alternative sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is known. The description adds useful behavioral context: the tool's output is reused as a fallback username in other operations, and it can serve as a token liveness check. This goes beyond the annotations without contradicting them.

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 two sentences, each carrying distinct value: the primary function and the integration use case. It is front-loaded with the core purpose and avoids redundancy or filler.

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 simple, zero-parameter, read-only tool with good annotations, the description is complete. It covers purpose, usage, and integration. The only minor gap is the lack of explicit return format, but the phrase '여기서 얻는 계정' (the account obtained here) implies the returned user object, which is sufficient.

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?

The tool has no parameters, so the baseline is 4. The description does not need to explain parameter details, but it implicitly explains the output's role (the authenticated account) which is the meaningful semantic content for a no-parameter tool.

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 clearly states the tool's function: '현재 토큰으로 인증된 계정을 확인한다' (checks the account authenticated with the current token). It specifies the resource (authenticated account) and adds a secondary purpose of checking token liveness. This differentiates it from sibling tools like velog_get_user, which fetches arbitrary users.

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 gives clear usage context: it is used to verify the token and serves as the source for the default username when omitted in other tools. While it doesn't explicitly name alternatives or exclusions, the guidance about its integration with other tools is practical and distinguishes when to use it.

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