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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/safety profile is known. The description adds real context: the write is additive, it creates a new revision (recoverable via esa_rollback_post_revision), and wip can be toggled. It doesn't cover auth or failure modes, so not a 5.

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

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

Two sentences total, front-loaded with the core action, then the sibling contrast and use cases. Nothing is redundant and no filler is present.

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 five-parameter mutation with full schema coverage, the description covers purpose, alternative, revision behavior, and the wip toggle. The remaining gap is that no output schema exists and the description never says what the call returns (e.g. the updated post/revision), so an agent cannot predict the response.

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 with detail (indentation, LF normalization, blank-line boundary, default message). The description only echoes the wip option and adds no syntax or constraint information beyond the schema, which is the baseline 3.

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 concrete verb and resource: it appends Markdown to the end of an existing post's body and saves it as a new revision. It explicitly contrasts this with the sibling esa_update_post, so an agent can distinguish it without reading either 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 names the alternative (esa_update_post), explains why this tool is preferable (no need to fetch the current body first), and gives concrete use cases such as log entries and meeting notes. The 'append to end' framing also implicitly separates it from esa_prepend_post.

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, and the description goes beyond them by disclosing the exact post-state after the call: category becomes 'Archived/<old category>' or 'Archived' if uncategorized. It does not say whether the original category is preserved for later restoration, whether missing Archived categories are auto-created, or who can call it.

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

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

Two sentences, with the core effect front-loaded and the conditional category rule immediately after. Nothing is redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter mutation with full schema coverage and no output schema, the description covers the essential 'what happens to the post' question. The remaining gap - reversibility and whether the resulting category is created automatically - is minor but would matter for a destructiveHint=true tool.

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% (postNumber, teamName with a pointer to esa_get_teams, and message), so the schema carries parameter semantics. The description adds no per-parameter detail such as what message is used for or whether teamName is required in practice.

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 (archive) and resource (post) plus the mechanism: moving to the Archived/ category, preserving the existing category path, and falling back to 'Archived' when none exists. No sibling tool archives a post, and the visible outcome distinguishes it cleanly from esa_update_post or esa_delete_comment.

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 case is implied by the name and description (retire a post without deleting it), but there is no explicit 'use this when / use X instead' guidance, and no mention of the alternative of recategorizing via esa_update_post. Prerequisites (teamName) live only in the schema, not the description.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered elsewhere. The description adds the precondition that the post must exist, but says nothing about permission requirements for authoring as another user (only the param schema mentions owner permission) or what gets returned.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity borders on under-specification rather than deliberate economy.

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 four-parameter mutation tool with no output schema, the definition leans entirely on fully documented params and safety annotations. What remains missing is authorization behavior and a hint about the created comment's return shape, which an agent would want before writing.

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 four parameters — user, bodyMd, teamName, postNumber — are already documented with constraints and defaults. The description adds no format, syntax, or validation detail beyond that, 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: creating a comment on an existing post, with the esa-team scope named. This clearly separates it from esa_create_post and esa_update_comment, though it never names those siblings explicitly.

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?

There is no guidance on when to use this versus esa_create_post, esa_update_comment, or esa_get_post_comments. The only implied condition is that the target post must already exist, which is inferred from 'existing post' rather than stated as a rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that the description adds essentially nothing behavioral: it does not say the post is created as WIP/draft by default, whether it is immediately visible to the team, what is returned on success, or how auth/team-membership failures surface.

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

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

A single front-loaded sentence with no filler. It is arguably too terse for a 7-parameter mutation tool, but nothing in it 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?

For a mutation tool with 7 parameters, one required field, and no output schema, the description leaves important gaps: it does not state that teamName is effectively required for a team-scoped post, does not explain the default draft state, and gives no hint about the returned created post so the agent knows whether an id comes back for follow-up calls.

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 7 parameters is already documented, including the non-obvious wip default of true and the teamName prerequisite. The description merely echoes 'tags, category, and WIP status', adding no meaning 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?

Names a specific verb and resource ('Creates a new post in an esa team') and enumerates the notable optional fields (tags, category, WIP). It is clearly distinguishable from read-oriented siblings like esa_get_post or esa_search_posts, though it never distinguishes itself from the near neighbors esa_update_post, esa_duplicate_post, and esa_append_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?

There is no statement of when to choose this over esa_duplicate_post or esa_append_post, and no mention of the prerequisite that teamName must resolve to an existing team (the schema tells the agent to call esa_get_teams first, the description does not). Usage is only inferable from the verb 'Creates'.

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, so the destructive nature is covered. The description merely restates that it deletes a comment and adds no extra behavioral context such as irreversibility, permission requirements, or effects on related data.

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 front-loaded sentence with no wasted words. It is concise, though its brevity contributes to missing context rather than being a model of structured guidance.

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 destructive tool with full schema coverage and annotations, the description is minimally adequate. However, it does not mention the teamName parameter or clarify the permanence of deletion, leaving some context to the schema and annotations.

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 both parameters are already documented in the schema, including teamName's guidance to use esa_get_teams. The description mentions deletion by comment ID but adds no semantic 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?

The description uses a specific verb and resource: 'Deletes a comment' from an esa team by comment ID. It is clear what the tool does and naturally distinguishes it from sibling comment tools like get/update/create, 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?

There is no guidance on when to use this tool versus alternatives such as update_comment or get_comment, nor any stated prerequisites. The schema mentions using esa_get_teams first for teamName, but the description itself gives no 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 is highly transparent by specifying that the duplication process preserves the source post's name and body_md, and crucially, that the resulting post is designated as a WIP post.

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 two direct sentences to cover the 'what', 'how', and 'where' of the duplication process without unnecessary fluff.

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 definition is complete. It covers the input requirements (source post number) and the expected outcome behavior (WIP post creation, team placement), making it unambiguous for a model to invoke 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?

Given that schema coverage is 100%, the description adds significant value by clarifying that targetTeamName defaults to the source team when omitted, which is a critical semantic detail for the optional parameter.

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 function (duplicates a post) and the resulting state (creating a new WIP post), which distinguishes it from general creation or search tools in the sibling list.

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 explicit usage guidance by defining the default behavior (source team) and the conditional usage of the targetTeamName parameter to override that default.

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 is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral value: results are paginated, include post counts, and are sorted lexicographically — facts an agent could not infer from the annotations alone.

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

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

Three sentences, front-loaded with the core purpose and behavior, then filtering. The clause "Perfect for category organization, cleanup, migration planning, or finding similar categories" is mildly promotional but still informative enough to justify its space.

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 no output schema, the description usefully summarizes the return shape (paths with post counts, paginated, lexicographic order). Minor gaps remain: it doesn't clarify that teamName is effectively required (schema-level default is empty string and required-count is 0) or that esa_get_teams should be called first, though the schema does mention the latter.

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% and every parameter already carries a description with concrete examples (e.g., prefix 'dev' finds 'dev/api'). The description only restates that filters exist (prefix/suffix/match/exact_match) without adding syntax or precedence guidance beyond the schema, 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 a specific verb and resource ("Retrieves category paths in a team") plus the scope/purpose of understanding overall category structure. It does not, however, distinguish itself from close siblings like esa_get_categories and esa_get_top_categories, which an agent will have to compare on its own.

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 lists usage scenarios ("organization, cleanup, migration planning, or finding similar categories"), which implies when to reach for it. But it gives no explicit when-not conditions and never names the sibling tools (esa_get_categories, esa_get_top_categories) that an agent should weigh against 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: conditional return behavior based on MIME type, the 30MB threshold, and the forceSignedUrl override. It omits auth requirements and failure modes, which keeps it from 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 sentences, zero waste, with the retrieval action first and the return-format rules front-loaded. Every clause carries 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?

There is no output schema, and the description compensates well by spelling out the two possible response shapes and the threshold that selects them. Minor gap: it doesn't mention that teamName is effectively required despite having an empty-string default, nor any error behavior.

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 baseline is 3; the description earns extra by explicitly linking forceSignedUrl to its effect on the response format, which is more than the schema's terse 'always return signed URLs'. It adds nothing about the url formats or teamName semantics, but those are fully documented 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?

States a specific verb and resource ('Retrieves an attachment file from esa') and immediately describes the two return modes. No sibling tool handles attachments, so an agent can route here unambiguously.

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 conditions for the two behaviors (supported image types under 30MB → base64; other types, larger files, or forceSignedUrl=true → signed URLs). It doesn't discuss prerequisites like team permissions, but usage context is otherwise 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by saying optional posts and parent categories can be attached to the response, which is useful return-shape context given there is no output schema. It stops short of describing pagination behavior or response structure.

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?

One compact sentence with no filler, and the core action plus scope is front-loaded. The trailing 'with optional posts and parent categories included' is slightly dense but still earns its place by previewing the include options.

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 no output schema, the description must carry more of the return-value burden, and 'category information' is vague about the shape (name, id, hierarchy depth). Pagination and the teamName prerequisite are also unaddressed, so a 6-parameter tool is only adequately described.

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 six parameters are documented in the schema, which sets the baseline at 3. The description only echoes the 'include' concept ('optional posts and parent categories') and adds nothing about the 'select' path syntax, the paging interaction, or that teamName is effectively required despite the schema's empty default.

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 (retrieves) and resource (category information and subcategories) scoped to a category path, which separates it from path-less siblings like esa_get_all_category_paths and esa_get_top_categories. It is clear but never names those siblings to disambiguate explicitly.

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 when-to-use or when-not-to-use guidance is given, and none of the closely related siblings (esa_get_all_category_paths, esa_get_top_categories) are referenced. An agent must infer from the phrase 'specific category path' that this is the per-path variant.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds only the optional stargazers inclusion, which is already documented in the schema, and says nothing about errors for missing IDs or the team-scoping requirement.

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

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

A single front-loaded sentence with no filler; the lookup key and the optional expansion are both stated immediately. Nothing is wasted and nothing important 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?

For a simple 3-parameter read with full schema coverage, no output schema, and clear annotations, the description covers the essentials. A note on the required team scoping or the single-comment vs list distinction would make it fully 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?

Schema description coverage is 100%, so all three parameters (commentId, include, teamName) are already documented, including the enum guidance and the teamName prerequisite. The description restates commentId and the stargazers option without adding format or constraint detail, 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 a specific verb and resource ('Retrieves a specific comment') plus the lookup key ('by comment ID'), which distinguishes it from list-style siblings like esa_get_post_comments or esa_get_team_comments. It does not name those siblings explicitly, so it stops short of a 5.

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 phrase 'by comment ID' implies you need a known ID, which is usable context, but there is no explicit statement of when to use this versus the comment-listing siblings or the create/update/delete comment tools. Usage must be inferred.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that the content is esa-specific extensions and formatting options, but says nothing about the shape of the returned documentation or whether it is static reference material versus live content. Modest added value over 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?

Two sentences, no filler, with the purpose front-loaded and the pre-requisite call ordering in the second sentence. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only documentation tool with no output schema, the description covers what it returns (Markdown syntax, esa extensions, formatting options) and when to fetch it. Only a hint about the documentation's scope or format is absent, which is minor at this complexity.

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 takes zero parameters, so there is no parameter semantics to convey; baseline 4 applies. The description correctly implies a parameterless, side-effect-free lookup rather than misleading the agent into expecting filters.

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 (Get) and resource (esa Markdown and formatting documentation) and clearly distinguishes itself from the data-mutating siblings by being a documentation-lookup tool. An agent can tell what it returns 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?

Explicitly prescribes when to call it ('BEFORE using any tools with *_md parameters') and enumerates the exact siblings that consume the syntax knowledge (esa_create_post, esa_update_post, esa_create_comment, esa_update_comment). The conditional trigger ('if you need clarification') is also spelled out, leaving nothing to inference.

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 establish this is a safe, non-destructive read, so the description doesn't need to re-state safety. It adds non-obvious behavioral context the annotations can't carry: the response always contains backlinks_count, which is a guaranteed output field. It says nothing about body truncation behavior, though the schema handles that in detail.

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, then the returned field, then the routing alternatives. No filler and no restating of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A simple read-only getter with full annotation coverage and a rich schema; the description supplies the one output detail (backlinks_count) not captured elsewhere. Without an output schema, one could wish for a brief note on other fields returned, but the essential call-correctness information is 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 coverage is 100% and the schema-driven descriptions for teamName, truncate, and postNumber are already detailed (defaults, truncation fallback, team lookup guidance). The description adds only 'by post number', which the schema already covers; 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 ('Retrieves a specific post ... by post number') and draws an explicit boundary against the nearest siblings, esa_get_post_backlinks and esa_get_post_comments. An agent can pick this tool over any sibling without opening a 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?

Names two alternatives explicitly and states the condition that selects each ('To list the referencing posts themselves...', 'To fetch comments...'). It also implies the natural read path (look up by post number) and defers team discovery to esa_get_teams via the schema.

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/non-destructive, so the description's added value is the filtering rule (archived and WIP posts excluded) and the ordering guarantee (newest reference first) plus pagination — meaningful disclosure an agent cannot get from annotations alone.

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

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

Three short sentences, front-loaded with what is returned, then exclusions, then ordering. No filler and nothing redundant.

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 no output schema, the description still conveys result type (list of referencing posts), filtering, and sort order, which is enough to call and interpret it. The item shape is not described, but that is a minor gap for a read-only list tool.

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% and each parameter is documented there, so baseline 3 applies. The description adds nothing about the pagination parameters or the fact that teamName is effectively required, so it does not exceed 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 ('Retrieves a paginated list of posts that reference...the specified post') and disambiguates the direction of the relation, which matters next to siblings like esa_get_post and esa_get_post_comments.

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?

Use case is implied by the name and description, but there is no explicit statement of when to choose this over related tools (e.g. esa_get_post_comments for discussion vs backlinks for references). The prerequisite of resolving a team name via esa_get_teams appears only in the schema, not the description.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered without description help. The description adds 'pagination support', which is useful beyond annotations, but omits sort order, defaults, and the fact that teamName is required (the schema covers that last point).

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 compact sentence with the resource and scope front-loaded and no wasted words. It is appropriately sized for a simple read tool, though the pagination clause is slightly gratuitous given the schema already documents page/perPage.

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?

Annotations cover the read-only safety profile and the schema fully documents all parameters, so the description needn't carry much. Still, it omits result ordering and the required-teamName workflow nuance that would help an agent call it correctly on the first try.

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 all four parameters are already documented, including the teamName prerequisite pointing to esa_get_teams. The description adds only a generic mention of pagination and no syntax or default details beyond the schema, so 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?

Uses a specific verb ('Retrieves') and resource ('list of comments') scoped to 'a specific post', which distinguishes it from the team-wide esa_get_team_comments and single-comment esa_get_comment. It doesn't name those siblings explicitly, but the scope is 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 phrase 'for a specific post' implies the per-post use case versus team-wide listing, but no explicit when-to-use or when-not-to-use guidance is given. An agent must infer the alternative from sibling names.

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 safety is covered. The description adds genuine context by scoping the documentation content (date ranges, tag filters, category searches, advanced operators), telling the agent what knowledge the call will supply.

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 sentences with zero waste, front-loading the purpose and then the when-to-use rule. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema help tool, the description is sufficient: it says what documentation is returned and when to call it. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies a parameterless, content-returning help call.

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 ("Get esa search syntax documentation") and names the sibling it feeds into (esa_search_posts). It is clear what the tool returns, though it does not explicitly disambiguate from other help-style siblings like esa_search_help or esa_get_markdown_syntax_help.

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 an explicit trigger ("when you need to construct complex search queries") and a sequencing rule ("Use this BEFORE esa_search_posts"), plus the condition "if you're unsure how to translate user's search requirements." Nothing is left to inference about when to reach for this.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's only additional behavioral claim is pagination support, which is already implied by the page/perPage parameters. It says nothing about ordering, result size, or whether all team comments or only some subset are returned.

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

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

A single front-loaded sentence with no filler. It is appropriately sized, though very short for the amount of ambiguity left unresolved.

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?

Three optional-looking parameters and no output schema mean the description should at least sketch the return shape (a list of comment objects) or ordering. Annotations cover safety, so the description is not grossly inadequate, but it stops short of fully briefing the 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 description coverage is 100% and each parameter is documented in the schema, including the hint to call esa_get_teams first. The description adds no parameter meaning beyond that, 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 and resource ('Retrieves a list of comments in a team') plus the scope (team-level) and pagination support. It doesn't explicitly contrast itself with the adjacent esa_get_post_comments or esa_get_comment, so an agent must infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is given. With siblings like esa_get_post_comments and esa_get_comment in the same list, the description should say which one to pick for post-scoped versus team-wide comment retrieval, but it leaves that entirely to inference.

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, destructiveHint=false and openWorldHint=false, so safety is settled. The description's only extra disclosure is that results include roles and profile information, which is useful but thin; it says nothing about pagination behavior or what happens with a non-existent teamName.

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 well-formed sentence with zero filler and the resource front-loaded. It is efficient, though the terseness borders on under-specification rather than genuine conciseness.

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?

Five parameters (two pagination, two sort, one identifying) with no output schema and no required-parameter enforcement make the missing pagination/sort guidance a real gap. The description never explains how paging behaves or that teamName is effectively mandatory, leaving the agent to infer it from the schema's default empty string.

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% and each parameter is self-documented, including enums for sort and order, so the schema carries the burden. The description adds no extra semantics such as default page size or whether sort/order are meaningful for team members specifically.

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 (retrieves team members) and adds the payload shape (roles and profile information). It is distinguishable from post-oriented siblings, but never names the adjacent team tools (esa_get_teams, esa_get_team_stats) that an agent would need to disambiguate 'team' scope.

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 no when-to-use or when-not-to-use guidance. The only routing hint ('Use esa_get_teams first to see available teams') lives in the teamName schema field, not in the description, so the description itself contributes nothing about prerequisites or alternatives.

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, destructiveHint=false and openWorldHint=false, so safety is fully covered structurally. The description adds only the 'user has access to' scoping qualifier and says nothing about result ordering, whether pagination aggregates totals, or the shape of a returned team; with annotations carrying the safety profile, that is an acceptable but thin addition.

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

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

A single front-loaded sentence with zero filler; the resource and scope come before any qualifier. Nothing is repeated and 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?

For a simple read-only list tool with full schema coverage and no required parameters, the definition is adequate but minimal. With no output schema present, the description could have said what a returned team looks like (id/name) and whether pagination metadata is returned, which an agent needs to chain into team-scoped siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — page ('starts from 1'), perPage, and the role enum (member/owner) are all documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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 ('Retrieves a list of esa teams') plus the scope qualifier 'that the user has access to', so an agent can tell this is a listing endpoint rather than a per-team lookup. It does not explicitly contrast itself with siblings like esa_get_team_members or esa_get_team_stats, which also touch team data.

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 'call this to discover which teams exist before calling team-scoped tools', but the description never says that, nor does it name alternatives or when-not-to-use conditions. Minimum viable routing guidance, no explicit rules.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the contents of the result payload, which is useful, but says nothing about the time window used for daily/weekly/monthly active users, scoping rules, or cost/rate 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?

One front-loaded sentence with no filler; the enumerating clause is doing real work by spelling out return fields. It could be tighter only by grouping the metric list.

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 read tool with full annotation coverage this is nearly complete, and the metric enumeration partly compensates for the absence of an output schema. The remaining gap is that 'daily/weekly/monthly active users' windows and the meaning of an empty default teamName are never explained.

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 parameter's description already notes it is required and how to discover valid values. The description adds no further meaning about teamName, 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 ('Retrieves team statistics') and enumerates the metrics returned, so the agent knows exactly what comes back. It does not, however, distinguish it from close siblings such as esa_get_team_members or esa_get_team_comments, which could plausibly return overlapping-looking counts.

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 contains no when-to-use or when-not-to-use guidance and never names an alternative. The only routing hint ('Use esa_get_teams first to see available teams') lives in the input schema, not in the description, so the narrative guidance is effectively absent.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description does add the return shape (tags plus per-tag post counts), which matters since there is no output schema, but it says nothing about ordering, whether counts are lifetime or windowed, or how pagination behaves across pages.

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 sentence, zero filler, with the resource and the returned payload front-loaded. There is no repetition of the name/title and no tangential 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 read-only, three-parameter list tool with full schema coverage and no output schema, the description is nearly sufficient: it states the resource and the returned fields. The remaining gap is behavioral detail around pagination and tag ordering, which is minor given the annotations already cover safety.

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 page, perPage, and teamName all documented inline, so the baseline is 3. The description adds no parameter-level meaning beyond the schema — notably it never ties the tag list to pagination or explains how page/perPage affect the result set.

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 and resource ("Retrieves all tags used in posts within a team") and adds the payload detail (post count per tag), so an agent knows exactly what comes back. It does not explicitly contrast itself with adjacent siblings like esa_get_categories or esa_get_top_categories, leaving that distinction to inference from the resource names.

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 contains no when-to-use guidance, no exclusions, and no mention of alternatives such as esa_get_categories or esa_search_posts. The only prerequisite hint ("Use esa_get_teams first") lives in the teamName schema field, not the description, so the description itself contributes nothing here.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the team scoping and the top-level constraint; it says nothing about ordering, filtering, or what a returned category contains.

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

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

A single front-loaded sentence with no filler; the resource and scope come first. It is efficient but arguably under-specified rather than deliberately minimal.

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, non-destructive, single-optional-parameter list tool with annotation coverage, this is close to sufficient. The remaining gap is the return shape (what fields a category exposes, flat list vs nested), which no output schema supplies.

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 one parameter and 100% schema description coverage, the schema already fully documents teamName, including the pointer to esa_get_teams. The description adds no meaning beyond that, which matches the baseline for a fully documented 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 ('Retrieves') and resource ('top-level categories') with team scoping, so the operation is unambiguous. It doesn't explicitly distinguish itself from near-siblings like esa_get_categories or esa_get_all_category_paths, leaving the agent to infer the difference between 'top-level' and 'all paths'.

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 offers no when-to-use guidance, no exclusions, and names no alternatives among the many category-related siblings. The only helpful routing hint ('Use esa_get_teams first') lives in the schema, not the description.

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 this as a destructive, non-read-only, closed-world mutation, so the safety bar is partly covered. The description adds real behavioral context beyond that: the change is recorded as a new revision and no read-modify-write cycle is needed. It stops short of stating what happens on a missing/invalid postNumber or what error responses look like.

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 sentences, front-loaded with the core action, then followed by differentiation. The trailing 'Optionally set wip' sentence largely repeats the schema but is short enough not to be wasteful.

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 key semantics: insertion position, revision creation, the no-fetch workflow, and the append sibling. Nothing critical is missing, though failure modes and permission requirements are unaddressed.

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 each parameter carries a substantive description, so the schema does the heavy lifting. The description only echoes the optional wip toggle, adding no format, default, or edge-case detail beyond what the schema already says.

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 ('Prepends Markdown content to the beginning of an existing post's body') and adds the persistence outcome ('saving it as a new revision'). It explicitly distinguishes itself from both esa_update_post and esa_append_post, so an agent can pick it 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?

Names two siblings and the condition that selects each: esa_update_post when you would otherwise fetch the body first, esa_append_post when content goes at the end. The choice is fully determined by the description.

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, so the key added value is the clarification that the restored content is saved as a *new* revision rather than overwriting history — this materially softens how an agent should read the destructive flag. It still doesn't mention permission requirements, side effects on comments/backlinks, or that the target revision must still exist.

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 sentence with the action front-loaded and the non-obvious consequence ('saving the restored content as a new revision') attached immediately. Nothing extraneous, nothing 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 five params, no output schema, and annotations that already signal the safety profile, the description covers the essential mechanics. It could do slightly more for a destructive mutation — e.g., whether the rollback is itself recoverable and what the response contains — but the schema carries the parameter burden well.

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% and every parameter carries a descriptive string, including the useful example for revisionNumber and the teamName lookup hint. The description adds no parameter meaning of its own, 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 (rolls back) and resource (a post) with the target qualifier (the specified revision), which is unmistakably distinct from esa_update_post or esa_append_post. It stops short of naming a sibling for disambiguation, but the operation is unambiguous on its own.

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 sentence describes what happens, not when to choose this over esa_update_post/esa_append_post; there is no guidance on prerequisites, on whether the post must be unlocked/editable, or when a rollback is inappropriate. The only routing hint in the whole definition ('use esa_get_teams first') lives in the schema, not the description.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral detail beyond that: no indication of what a result looks like, whether it searches help-team posts versus static docs, or how paging behaves — notable given the schema is a full post-search query syntax.

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 lines, front-loaded with the purpose followed by usage context. No filler, though the first sentence largely restates the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter, read-only tool with annotations, the essentials are covered, but with no output schema the agent has no idea what the tool returns, and the description never clarifies that the query syntax is a post-search syntax rather than a plain documentation keyword search — a real risk of malformed calls.

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 query parameter carries extensive guidance (date syntax, OR operators, tag:/category: operators), so the schema does the heavy lifting. The description contributes nothing about the query or page/perPage semantics; 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 and resource: 'Search esa documentation for features, terminology, and specifications.' An agent can tell this apart from post-oriented siblings like esa_search_posts, but nothing distinguishes it from the other help-oriented siblings (esa_get_search_options_help, esa_get_markdown_syntax_help), so which help tool to open remains ambiguous.

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 concrete triggers: users mention esa-specific terms, ask about esa functionality, or request help with workflows the agent doesn't know. The 'that you're not familiar with' clause implies trying your own knowledge first, but no alternative tool is named and there are no explicit exclusions against the sibling help 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?

The annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds essentially nothing about search behavior, pagination, result limits, or scope. It repeats the read-only nature without enriching it.

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

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

The description is a single short sentence with no waste, but it is arguably too terse for a six-parameter search tool. There is no front-loaded scope or behavioral context, so its conciseness comes at the cost of completeness rather than through efficient structure.

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 six parameters, a required query, and no output schema, the description should at least explain the search scope and mention pagination or team context. The schema is rich, and annotations cover safety, but the description itself is nearly empty. The implicit team requirement in teamName is also not surfaced.

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 query parameter's schema already documents date syntax, OR semantics, tag/category filters, and required team lookup. The description adds no parameter guidance of its own. A baseline of 3 is appropriate when the schema carries all parameter semantics.

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 ('Search for posts in esa.io'), so an agent can tell it is a search operation rather than a fetch or mutation. It does not distinguish itself from siblings such as esa_get_post, esa_search_help, or esa_get_search_options_help, but the core purpose is 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 gives no guidance on when to use this tool versus alternatives. It does not mention related tools like esa_search_help or esa_get_search_options_help, nor does it explain when to prefer direct post retrieval (esa_get_post) over search. Usage is only implied by the tool name.

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 is a mutation (readOnlyHint=false, destructiveHint=true), so the safety profile is covered. The description adds useful context by explaining the exact field change ('setting wip to false') and its effect ('marks the post as complete and ready to be published'). It does not discuss permissions or reversibility, but that is largely covered by the destructive annotation.

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 tight sentences with no wasted language. It front-loads the core action, then adds the effect, then routes the agent to the correct alternative when conditions differ.

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 mutation tool with full schema coverage and explicit annotations, the description is complete enough. It explains the action, effect, and sibling alternative; no output schema exists, so return-value detail is not required.

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 both parameters, including the teamName requirement and postNumber purpose. The description does not add parameter-specific syntax or constraints beyond what the schema provides, so 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 gives a specific verb and resource ('Ships a post'), explains the underlying action ('setting wip to false'), and distinguishes this tool from the sibling esa_update_post. An agent can tell exactly what this tool does 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?

It explicitly states when to use this tool ('only when you need to ship without making other changes') and names the alternative for the other case ('use esa_update_post with wip: false instead'). Both the positive and negative usage conditions are 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 destructiveHint=true and readOnlyHint=false, so the description adds essentially nothing on the safety profile. It does not say that the update replaces the existing body wholesale, that owner permission may be needed for the author field, or what happens on a bad comment ID — all of which matter for a destructive mutation.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though efficiency here partly reflects under-specification rather than disciplined editing.

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?

This is a destructive mutation with no output schema, and the description covers none of the things an agent would still need: whether the body is fully replaced, what the response contains, or how failures on a nonexistent commentId behave. Annotations carry the safety signal but the description leaves real operational gaps.

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 all four parameters (including the owner-permission caveat on 'user' and the teamName lookup hint) are documented in the schema itself. The description only echoes commentId and adds no format or usage detail beyond it, which is the baseline for full-coverage schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb ('Updates') and resource ('an existing comment in an esa team'), but 'by comment ID' merely echoes the required commentId parameter. It does nothing to distinguish this from siblings like esa_delete_comment or esa_create_comment, which an agent must choose between in the same workflow.

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?

There is no guidance on when to use this versus esa_create_comment, esa_get_comment, or esa_delete_comment, and no stated preconditions (e.g. needing to fetch the comment first). The agent must infer all routing from the name alone.

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?

Adds real meaning beyond the annotations: clarifies that wip=false is the shipping mechanism and that this tool supersedes esa_ship_post for combined updates, which the destructiveHint alone would not convey. The implication that content edits replace the body (rather than append) is only conveyed indirectly via the append/prepend routing, and the originalRevision conflict-check behavior is never described.

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 with the core action first, the mutation surface second, and the alternative routing last. No filler and no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the core operation and the sibling disambiguation well for a mutating 9-parameter tool. It omits the teamName requirement and the originalRevision conflict-check semantics, both of which matter for a tool that can overwrite post bodies, though the nested object is described 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?

Schema coverage is 100%, so all nine parameters are already documented, setting the baseline at 3. The description adds genuine semantic value only for wip (false = ship/complete); the rest of the field list largely restates what the schema property descriptions already say.

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 ('Updates an existing post in an esa team by post number') and enumerates the mutation surface (title, content, tags, category, WIP). It also names the sibling tools it is not (esa_append_post, esa_prepend_post, esa_ship_post), so an agent can distinguish it 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?

Gives explicit routing rules: use this instead of esa_ship_post when shipping plus changing other fields, and use esa_append_post/esa_prepend_post when only adding to the body. Both the when and the when-not are stated with named alternatives.

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