List posts (글 목록)

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.