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?

The description adds crucial behavioral context beyond the annotations: the draft is never published, only the author can see it, and body must be Markdown. These facts are not present in the annotations and are essential for the agent to set expectations correctly.

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 short sentences with zero redundancy. The most important fact (creates a draft, does not publish) is front-loaded, and the pointer to the publishing sibling is direct. 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?

The description is complete for the core purpose and usage, but it does not hint at the more complex optional parameters like series_id, series_name, or thumbnail behavior. However, the schema descriptions cover these thoroughly, so the agent can access that detail when needed. For a create-draft tool, the global behavior is well covered.

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 all parameters are documented in the schema. The description only reiterates that body is Markdown, which adds no new information. The tool's tricky series_id behavior and thumbnail auto-setting are covered in the schema, so the description does not need to compensate for gaps.

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 (만든다 - create), the resource (벨로그 초안 - Velog draft), and the key distinction that it does not publish. It explicitly differentiates from the publishing siblings by stating it never publishes under any settings, making its purpose unambiguous.

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 create a draft) and when not to (when publishing is needed), directing the agent to velog_publish_draft as the alternative. This direct routing eliminates ambiguity about the tool's role in the workflow.

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 destructiveHint true, but the description adds concrete details beyond that: overwriting existing files, per-post sequential fetching causing slowness, and the presence of front matter. This goes beyond the mere annotation flags and provides operational expectations.

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 packs purpose, rationale, overwrite warning, usage recommendation, and performance note into two tight sentences. There is zero fluff, and 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?

Given the tool's moderate complexity and no output schema, the description covers the key behavioral aspects: purpose, overwriting, speed, and directory guidance. It doesn't describe return values or error handling, but those are less critical for an export tool with schema-covered parameters.

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 description doesn't need to re-explain parameters. It only alludes to the local directory concept, but doesn't add meaning beyond the schema's own descriptions for out_dir, limit, and username. 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?

The description clearly states it saves a user's VELOG posts as markdown files with front matter to local storage, and explains it was created because VELOG lacks an official export. This specific verb-resource pairing (saving posts to local markdown) distinguishes it from all sibling tools like get_post or 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?

The description provides context (no official export) and gives practical usage warnings: it overwrites files and recommends a dedicated directory. It doesn't explicitly name alternative tools to use instead, but the unique export purpose makes the when-to-use reasonably 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?

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 destructiveHint=true and readOnlyHint=false. The description adds important behavioral context: it publishes as private-only unless VELOG_ALLOW_PUBLIC=1 is set, and that it can be reverted to draft via velog_unpublish_post. This goes beyond the annotations and 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 two sentences, front-loads the primary action, and every clause adds value. There is no 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 mutation tool with no output schema, the description covers the core behavior, the private default, and the revert path. It does not mention prerequisites or response format, but those are not essential for calling the tool correctly given the annotations and schema coverage.

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 57% schema description coverage, the schema covers some parameters (thumbnail, series_name, url_slug). The description does not add any parameter details, so it relies on the schema. It meets the baseline for moderate coverage but does not go beyond it.

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 publishes a new post immediately without going through a draft ('새 글을 바로 발행한다. 초안을 거치지 않는다.'), which distinguishes it from sibling tools like velog_create_draft and velog_publish_draft. The resource and action are unambiguous.

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 mentions that a draft is skipped and provides a revert path via velog_unpublish_post, giving clear context on when to use it and how to undo. It doesn't explicitly list when to prefer alternatives like velog_create_draft, but the implication is strong enough for an agent to infer.

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?

The description discloses key behaviors: automatic layout via browser measurement, self-audit for overflow/overlap/line intersection, audit failure prevents upload and reports issues, the audit cannot be disabled, and failed outputs are rejected even by velog_upload_image. This goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) and adds critical operational 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?

The description is front-loaded with the core action, followed by behavioral details and reference lists. Each sentence contributes meaningful information, and the icon/tone lists are compact. No 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 complex tool with no output schema, the description covers the complete workflow (draw → audit → upload → return markdown), the audit enforcement, and the relationship with velog_upload_image. The schema covers individual parameters, so the description does not need to repeat them. It leaves little doubt about what the tool does and its key failure mode.

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%, so the description should compensate for undocumented parameters. It adds contextual meaning (coordinates drive layout, node width auto-measured) and lists icon/tone options. However, it does not explain groups, legend, planes, or upload/post_id behavior beyond what the schema already provides. The schema's own field descriptions are quite detailed, so the description adds moderate value.

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 the tool draws composition/flow diagrams, renders to PNG, uploads to Velog, and returns markdown for the body. This clearly distinguishes it from sibling tools like velog_render_cover 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?

The description implies usage for diagram generation but does not explicitly mention when to use it over alternatives. The note that audited outputs are not accepted by velog_upload_image is an indirect exclusion, but there is no clear when-not or alternative selection guidance.

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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral details—such as pagination behavior, sorting logic, or return format—beyond the parameter hint, providing minimal value 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 extremely concise, with no filler content, and front-loads the main purpose. However, it lacks a structured explanation and is so terse that it sacrifices informative content, so it does not earn a perfect score.

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 there is no output schema, the description should explain what the tool returns and how trending is determined. It only says 'popular posts' and mentions choosing a period, leaving ambiguity about the response structure, pagination, and distinctions from recent or list tools. The description is incomplete for a tool with three optional parameters and no 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 0%, so the description must compensate. It only hints at the timeframe parameter ('기간을 골라 본다') but says nothing about limit or offset, which are important for pagination. This is insufficient compensation for the lack of schema-level descriptions.

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 resource (popular posts) and the action (view with a period filter). It is specific enough to convey core functionality, but it does not explicitly differentiate from siblings like velog_recent_posts or velog_list_posts, so it misses the top score.

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 does not mention any exclusions, prerequisites, or competing tools such as velog_search_posts or velog_recent_posts, leaving the agent to infer usage context.

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?

Annotations already provide destructiveHint and idempotentHint, but the description adds crucial specifics: omitted fields reset, tags cleared, url_slug regenerated, and series connection broken. This fully discloses the destructive nature beyond the annotations and is consistent with idempotentHint (full replacement).

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 dense paragraph that leads with the key fact (full replacement), then lists specific reset behaviors, then gives a recommendation and a warning. Every sentence carries essential information with no 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?

Given 8 parameters, 3 required, and no output schema, the description covers the critical pitfalls: full replacement semantics, reset behavior, the need to read current values, and rejection of published post ids. It is sufficiently complete for safe and 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?

Schema coverage is 50%, so the description must compensate. It adds meaning for tags, url_slug, and series_id by explaining the consequences of omission, which is not in the schema. However, it doesn't extend semantics to all parameters (e.g., series_name), though the schema already covers those. The critical omitted-field behavior is well addressed.

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 the tool '기존 초안을 통째로 교체한다' (replaces the entire existing draft), naming the action and resource. It differentiates from partial updates and explicitly rejects published post ids, clearly distinguishing 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?

It gives explicit when-to-use guidance: recommends reading current values with velog_get_post before modifying and passing all fields, and states published post ids are rejected, which implies using a different tool. This provides clear context and 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?

Annotations only indicate destructive and not-read-only, but the description adds substantial behavioral context: omitted fields retain existing values (partial update), draft IDs are rejected, and visibility cannot be changed unless an environment variable is set. This goes far beyond the annotations and prepares the agent for real-world behavior 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?

Three dense sentences, each delivering crucial information: main action, update semantics, draft exclusion, and visibility restriction. No filler; the most important distinction (partial update) is front-loaded. Efficient and well-structured.

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 and 8 parameters, the description covers key operational aspects: published-only, partial update, draft rejection, and visibility constraints. It does not describe the return value or error handling, which would be useful but are not critical for a moderate-complexity update tool. Overall, it provides sufficient context 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?

Schema coverage is 63% and the description compensates by explaining the general partial-update rule that applies to all optional parameters. It also details thumbnail auto-set vs null behavior and series_name lookup semantics. However, title and series_id lack explicit descriptions, though they fall under the generic omitted-field retention rule. The description adds meaningful context 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 states '이미 발행된 글을 수정한다' (modifies an already published post) with a specific verb and resource. It further distinguishes itself from the draft tool by stating draft IDs are rejected and points to velog_update_draft, leaving no ambiguity about its 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?

Explicitly notes draft IDs are rejected and directs to velog_update_draft for drafts, providing a clear when-not-to-use and alternative. It also explains the partial-update semantics vs the draft tool's full replacement, and clarifies visibility constraints with VELOG_ALLOW_PUBLIC requirement, giving precise usage conditions.

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.