tistory-mcp

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely useful context beyond them: the permanence ('Cannot be undone') and a mandatory human-confirmation gate, which is the key behavioral constraint for this tool. It stops short of covering permission or error 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?

Two short sentences, zero filler, with the irreversibility warning and the confirmation instruction front-loaded. 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?

Output schema exists and annotations are rich, so return values and safety are covered elsewhere. The description supplies the two things an agent most needs for a destructive tool – permanence and the confirmation requirement – though it says nothing about failure modes or required permissions.

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 post_id, blog_url, and confirm are all documented in the schema already. The description reinforces the confirm=true requirement but adds no syntax or format detail beyond what the schema states, so the 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 states a specific verb and resource ('Permanently delete a post') and immediately adds the irreversible consequence. It is clearly distinguishable from siblings like tistory_update_post and tistory_publish_post without opening any schema.

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 an explicit precondition workflow: ask the user to confirm in chat first, then call with confirm=true. It does not name alternative tools (e.g., why not update_post) but for a destructive terminal operation the when-to-use guidance 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds two genuinely new facts beyond annotations: the data source is an RSS feed (implying recency-ordered, feed-limited results) and that no authentication is required. It does not warn that RSS typically exposes only recent items, which is the main residual gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the resource and source front-loaded and the auth constraint appended. Nothing needs trimming and nothing is buried.

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 an output schema present and full parameter documentation, the description only needed to establish source, scope and auth — which it does. The one omission is that RSS feeds return a bounded recent window of posts, which affects how an agent interprets an empty or short result.

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 three parameters (blog_url, limit, include_content) are already documented with examples and defaults. The description adds nothing about parameter behavior — e.g. that limit caps against a feed-imposed maximum or that include_content returns raw body HTML — so the baseline of 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?

States a specific verb and resource ('Fetch the latest public posts ... from its RSS feed') and names the scope ('any Tistory blog'), which implicitly separates it from session-based siblings like tistory_list_posts. It stops short of explicitly naming the alternative tool, but the RSS/public framing is distinctive enough to select on.

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?

'No login needed' implies the condition that selects this tool (unauthenticated / public-only access), but the description never names tistory_list_posts or tistory_get_post as the alternative, nor does it state when NOT to use this tool. Usage is inferable rather than explicit.

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, idempotentHint and destructiveHint=false, so the description does not need to argue safety. What it adds is the response shape (a flattened tree, not nested) and a hard constraint on the returned ids that affects downstream calls – genuine context beyond the annotations. It stops short of noting any auth or session requirement despite a tistory_session_init sibling.

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, zero filler, with the output shape front-loaded and the cross-tool id contract second. Nothing could be removed without losing information an agent needs.

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 an output schema present, the description needn't detail return values, and annotations cover the safety profile; the two sentences supply exactly the missing piece – the contract between this tool's output ids and the publish/update tools. The only gap is that it doesn't mention a session/auth precondition, which the presence of tistory_session_init siblings makes relevant.

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 single blog_url parameter is already documented with a format example, so the schema carries the parameter burden. The description adds semantics about the returned id, but nothing about the parameter itself, 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?

States the specific operation (return the category tree) and its exact output shape (id / name / parent id), which unambiguously distinguishes it from every sibling, none of which deal with categories. A verb-plus-resource plus return-shape statement leaves no ambiguity about what the tool does.

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?

Gives clear downstream usage: use the returned integer id as `category` in the publish/update siblings, and names the invalid alternative (names are not accepted). It does not explicitly say when to call this first (e.g., before tistory_publish_post or tistory_update_post), but the implied workflow is clear enough for an agent to act on.

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 readOnly/idempotent annotations, it discloses that the body is skin-rendered HTML rather than original markdown and that private posts require the saved session. The warning not to echo content_html back for edits is important behavioral guidance that annotations cannot 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?

Four short sentences, front-loaded with the core return behavior and followed by essential caveats. Every sentence carries useful information with no repetition.

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?

An output schema exists, so return values need not be explained, but the description still covers the important shape of the body and the private-session condition. For a two-parameter read tool, it supplies enough context to call 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?

Schema coverage is 100%, so blog_url and post_id are already fully documented in the schema. The description adds no parameter-specific syntax or constraints beyond the schema 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 states a specific verb and resource: return one post's metadata and body HTML, with the admin-list and post-page sources. It distinguishes private-post retrieval via the saved session and points to tistory_update_post for editing, so an agent can separate it from write 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?

It gives clear context for private posts and an explicit when-not: to edit, write the new body yourself and send it with tistory_update_post rather than echoing content_html back. It does not name tistory_list_posts or tistory_fetch_public_posts as retrieval alternatives, so routing is helpful but not fully exhaustive.

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, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that by disclosing the result scope (private/protected posts included) and the significant omission (no bodies), both of which affect how an agent interprets results.

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, zero filler, with the most decision-relevant information (admin-side scope, bodies excluded) front-loaded. Nothing repeats the schema or annotations.

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?

An output schema exists and the input schema is fully documented, so the description only needs to add scope and caveats, which it does. The one remaining gap is guidance on iterating pages or knowing when the last page is reached, which would help an agent use the paging parameter 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?

Schema description coverage is 100%, with every one of the six parameters documented including defaults and the -3 'all categories' sentinel, so the schema carries the semantics. The description adds only the implicit notion of paging via 'one page at a time' and no detail on keyword/visibility/category behavior 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?

States a specific verb and resource ('List posts from the admin side') and scopes it precisely by noting that private and protected posts are included, which implicitly separates it from the public-listing sibling. It also names tistory_get_post as the tool for bodies, so the agent can tell what this tool does not return.

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 'use tistory_get_post for the body' line is a genuine routing instruction, and 'one page at a time' hints at pagination. However, it never explicitly contrasts with tistory_fetch_public_posts (the obvious alternative when private posts are not needed) or states when the admin-side listing is required versus a public fetch.

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 flag non-idempotent, non-read-only, open-world behavior; the description goes further by spelling out the concrete consequence (duplicate posts on retry) and adding rate limits (60 s apart, 20/day) plus the default-private safety posture, none of which appear in the annotations or schema. It stops short of describing the response or what happens to attachments, keeping it at 4 rather than 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?

Four short sentences, front-loaded with the highest-stakes fact (every call creates a new post), then the duplication hazard, then the safe default, then rate limits. No filler and no repetition of schema 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?

For an 11-parameter, non-idempotent mutation with an output schema already covering return values, the description supplies exactly the missing operational context: duplication risk, retry procedure, visibility default, and throttling. Nothing an agent needs in order to invoke it safely is absent.

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 every one of the 11 parameters is already documented, including enum meanings and defaults. The description restates the private default and markdown default but adds no syntax or format detail beyond the schema, so the 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?

States a specific verb+resource ('Create a NEW post') and immediately disambiguates it from two siblings: 'this is not a draft and not an update,' ruling out tistory_save_draft and tistory_update_post. An agent can classify the tool without opening the schema.

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?

Gives explicit when-to-use and when-not-to: check tistory_list_posts before retrying after an error/timeout, and use tistory_update_post to flip visibility to public after review. It also names the alternative path and the condition that selects it.

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?

Goes beyond the annotations by disclosing the overwrite semantics of the single autosave slot and the editor's restore prompt, which explains why idempotentHint=false matters in practice. It does not cover auth requirements or how the draft interacts with the draft owner's session, keeping it just short of 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 short sentences, front-loaded with the core action and non-creation guarantee, then the restore behavior, then the alternative. Every sentence carries distinct information with zero repetition.

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 the safety profile, an output schema handling return values, and full schema coverage for parameters, the description only needs the semantics an agent could not infer: the single-slot overwrite, the non-creation guarantee, and the restore flow. All are present.

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 seven parameters (title, content, blog_url, tags, category, attachments, content_format) are already documented in the schema. The description adds no parameter-level detail beyond the visibility reference for the alternative tool, which is the expected baseline when the schema does the work.

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?

States a specific verb and resource: 'Write a draft into the editor's single autosave slot', followed immediately by the negative scope 'No post is created.' This cleanly separates it from siblings like tistory_publish_post without requiring the schemas to be opened.

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 names the alternative and the condition that selects it: 'For several reviewable drafts, publish with visibility=\'private\' instead.' The agent knows both when to call this tool and when to route elsewhere.

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?

Goes well beyond the annotations by disclosing that the call blocks until user action or timeout, that KakaoTalk 2FA requires human intervention, and that the resulting session may expire in as little as an hour. This is exactly the operational context an agent needs before invoking a long-running, human-in-the-loop login.

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, front-loaded sentences: what it does, how the agent must behave while it runs, and what to do afterward. No redundant restatement of the title or annotations.

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?

An output schema exists, so return values need not be explained, and the description still covers prerequisites, blocking semantics, and session lifecycle. Nothing material for correct invocation 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%, including the cdp_url fallback for WSL/SSH/containers, so the schema already carries parameter meaning. The description only indirectly reinforces timeout_sec via the blocking behavior and never mentions cdp_url itself, so it adds little beyond the structured 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?

States a concrete verb and resource ('Open a browser for the Kakao login ... and save the cookies'), making the outcome (persisted session/cookies) explicit rather than just 'log in'. It is clearly distinguished from the read-only siblings such as tistory_session_status, which only reports state.

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?

Gives explicit when-to-use guidance: call before other tools, tell the user to watch for the browser window and approve the push first, and call again when a tool reports an expired session. It also names an exclusion implicitly by stating the 2FA approval cannot be automated, so retrying will not help.

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, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: it performs one live admin API call rather than reading local state only, which is a side effect an agent should know about; it does not mention failure modes or rate limits, keeping it short of 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?

Two short sentences, front-loaded with the local state report before the live check. Slightly fragmentary ('Also makes one admin API call...') and the first sentence packs three facts, but nothing is wasted.

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?

One required parameter at full schema coverage plus an output schema means return shape need not be explained. The description covers both the cached metadata and the live validity check, which is what an agent needs to decide whether to proceed; a note on what a missing session means would complete 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 description coverage is 100% for the single blog_url parameter, so the baseline of 3 applies. The description adds nothing about the parameter (e.g. that the session lookup is keyed to blog_url), leaving the schema to do all the work.

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 a specific verb ('Report') against a specific resource (saved session: existence, save time, expiry) and adds a second, distinct check ('live right now (valid/expired)'). It is cleanly separable from the sibling set, none of which query session state, though it never names tistory_session_init as the counterpart it is not.

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?

Usage is only implied: an agent can infer this is the precondition check before publish/update operations, but the description never states when to call it, when not to, or that session_init is the alternative when no session exists. No explicit routing to siblings.

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 declare it is a non-read-only, non-destructive, non-idempotent, open-world write. The description adds the crucial behaviors the annotations do not: the server does not merge so the full body is overwritten, tags are preserved by re-reading the post page, and the call shares a rate limit with publish. It stops short of noting session/auth requirements or what happens to attachments and password fields.

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 overwrite constraint is front-loaded in the first sentence, followed by field-preservation rules and the rate-limit note. Three sentences with almost no waste, though the trailing 'Rate-limited together with publish' fragment could be folded in more smoothly.

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 11 parameters, full schema coverage, an output schema, and annotations covering the safety profile, the description covers the main non-obvious risk (full-body overwrite) and the omit-to-keep contract. Only auth/session prerequisites and attachment handling are left implicit.

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 every parameter is already documented; baseline is 3. The description usefully clarifies the 'slogan' param is the URL slug and restates the omit-to-keep contract for title/category/visibility, but adds no syntax, id-format, or password/visibility interaction detail 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?

A clear verb+resource ('Update an existing post') that is distinguishable from publish/save_draft by the word 'existing'. It does not explicitly name the sibling tools it supersedes for editing, so differentiation is implied rather than stated.

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 explains omission semantics well (fields keep current values, [] clears tags), which is really per-field guidance, but it never says when to choose this over tistory_publish_post or tistory_save_draft, nor what prerequisites (session/auth) must be in place. Usage is inferable rather than directed.

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 declare the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds genuinely non-inferable behavior: uploads are ephemeral and reference-counted via 'attachment_ref', becoming invalid in ~15 days if unreferenced, and the returned URL is not directly usable in post bodies. That is exactly the kind of lifecycle detail structured fields cannot carry.

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 tight sentences, front-loaded with what is returned, then the placement rule, then the retention caveat and the prohibition. Nothing is padded. Minor friction from the code-fenced identifiers and the stray line breaks in the source, but the information density is high.

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?

An output schema exists, yet the description still highlights the two return fields that carry workflow semantics, which is the right call for a tool whose outputs must be threaded into a later call. Combined with the fully documented 5-parameter schema and the retention warning, an agent has everything needed to call it and use the result 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?

Schema description coverage is 100%, so the schema already documents blog_url, file_path, style, width, and height including defaults and size limits. The description adds nothing about input parameters — the identifiers it discusses ('substitution', 'attachment_ref') are return values, not inputs. 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 names a specific verb+resource ('Upload an image') and immediately states the two artifacts it returns ('substitution' and 'attachment_ref'). That distinguishes it unambiguously from every sibling, none of which deal with binary media, and it tells the agent the tool is a prerequisite step for publish/update rather than a terminal action.

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, actionable when-and-how guidance: put 'substitution' verbatim in the body, pass 'attachment_ref' in attachments 'when publishing/updating', and a clear negative instruction — 'Do not put the returned URL into the body directly.' It also supplies the consequence of skipping the step (garbage-collection after ~15 days), which makes the correct usage path obvious.

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