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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful context beyond that: content is saved as a new revision (so it is recoverable via rollback) and the optional wip flag changes WIP state. It does not state auth/permission requirements, but the revision disclosure is substantive added value.

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 compact sentences: what it does first, then how it differs from the alternative, then the optional flag. No padding, every clause carries 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 mutation tool with annotations covering the safety profile and 100% schema coverage, the description covers purpose, alternative routing, and side effects adequately; no output schema is needed. Minor gap: it never mentions teamName, which the schema itself flags as required despite not being in the required list.

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 five parameters including boundary/indentation rules and wip defaults are already documented. The description only re-states the optional wip behavior, adding no syntax or format detail beyond the schema. 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 (appends) plus resource and target location (end of an existing post's body), and names the side effect (new revision). An agent can distinguish it from esa_update_post and esa_prepend_post without inspecting schemas.

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 contrasts with esa_update_post ('does not require fetching the current body first') and gives concrete use cases (log entries, meeting notes). The append-to-end framing also separates it from the sibling prepend operation.

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, but the description adds real context beyond them: the exact category transformation rule, including the nested case ('dev/docs' -> 'Archived/dev/docs') and the no-category fallback. It stops short of stating reversibility or failure behavior (already-archived posts, missing categories).

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 the primary action and followed by the category-path edge cases. No filler, though the second and third sentences could be merged without loss.

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

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

For a destructive mutation with no output schema, the description covers the mutation's outcome well but omits error/edge cases (post already archived, nonexistent category), permission requirements, and whether the operation is reversible. Annotations carry the safety signal, so the gaps are not severe, but an agent still has open questions.

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 postNumber, teamName and message; baseline is 3. The description adds how postNumber selects the resource but says nothing about teamName (which its own property description calls required) or the meaning of the change message.

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 and even specifies the mechanism (moving to the Archived/ category) plus the resulting category path. This distinguishes it implicitly from siblings like esa_ship_post or esa_delete_comment/rollback, since archive is a category-move, not a status change or deletion.

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 implied by the described effect — you call this when you want to retire a post into the Archived tree — but there is no explicit when-to-use, when-not-to-use, or mention of alternatives such as esa_ship_post (which also relocates a post). With a dense sibling set, an explicit pointer would have helped.

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 it is a non-read-only, non-destructive, non-open-world write, and the description merely restates that a comment is created. It adds no behavioral context such as permission requirements, rate limits, or who can comment, so it earns little beyond the structured hints.

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 the brevity borders on under-specification rather than deliberate 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?

For a 4-parameter mutation tool with no output schema, the schema covers parameters well and annotations cover the safety profile, so the description is minimally sufficient. It nonetheless omits any usage or prerequisite context that would make the definition self-contained.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the owner-permission note on 'user' and the teamName prerequisite. The description adds no parameter meaning beyond that, which is the expected baseline when the schema carries the load.

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+scope: creating a comment on an existing post within an esa team. An agent can distinguish it from esa_create_post or esa_update_comment by resource type, but the description never names those siblings or explicitly contrasts the operation.

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 guidance on when to use this versus esa_update_comment or esa_create_post, and no prerequisites stated in the description (the teamName prerequisite for esa_get_teams lives only in the schema). The agent must infer the usage context entirely.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), lowering the burden. The description adds only that tags, category and WIP are optional — it says nothing about authorization requirements, whether an existing same-named post is overwritten, or the effect of the wip default. Adequate but thin given the annotations do the heavy lifting.

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 front-loaded and no waste. It is appropriately sized for the tool, though it omits anything beyond the bare enumeration, so it is efficient rather than exemplary.

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

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

With a 7-parameter write tool, no output schema, and a schema whose teamName description says '(required)' while not appearing in the required array, the description should have disambiguated team targeting and noted the need to resolve teams first. It is minimally viable but leaves that gap 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%, so the schema already documents all seven parameters, including the important 'set wip to false to ship' semantics. The description merely echoes tags, category and WIP without adding syntax, format, or default behavior beyond what the schema states, which is the baseline-3 case.

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 — 'Creates a new post in an esa team' — and enumerates the optional dimensions (tags, category, WIP). It is clearly distinct from mutation siblings like esa_update_post or esa_append_post by virtue of 'creates a new', though it does not explicitly name or route against those 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?

There is no when-to-use versus when-not guidance and no alternatives named. Given siblings such as esa_duplicate_post, esa_update_post, and esa_ship_post, an agent gets no help deciding whether creating here (versus duplicating or updating) is the right call. Usage is only inferred 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 safety profile is covered structurally. The description adds nothing on top of that: it never says the deletion is irreversible, whether it requires ownership/admin rights, or what happens to replies or attachments on the comment.

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 efficient sentence with the resource and lookup key front-loaded; nothing is wasted. It is, however, so terse that brevity shades into under-specification.

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

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

For a destructive, non-read-only operation with no output schema, the description should carry the irreversibility and permission context that annotations cannot express. It omits both, and while the schema covers the parameters, an agent is left without the operational caveats a delete tool warrants.

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 (teamName, commentId) are documented in the schema and the baseline is 3. The description's 'by comment ID' merely restates what the schema already says and adds no format, type, or lookup guidance.

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 (deletes) and resource (a comment) plus the scoping resource (esa team), so the agent can distinguish it from esa_get_comment, esa_update_comment and esa_create_comment. It stops short of explicitly naming or contrasting those siblings, so it is clear but not maximally differentiating.

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 its siblings, nor any precondition or caution for a destructive operation. The agent gets only 'what', never 'when' or 'only if'.

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 mark it as a non-read-only, non-destructive write; the description adds the meaningful context that the result is a WIP post copying name and body_md and that the source team is the default destination. It omits auth/permission needs but exceeds what the annotations convey.

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

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

Two sentences, zero waste: the core duplication behavior is front-loaded, followed immediately by the team-selection option. Nothing needs restructuring.

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 full annotation coverage and no output schema, the description supplies the essential behavior (what is created, where, and in what state). It could add a note on prerequisites (e.g., valid source post/team), but is otherwise 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% and already documents teamName, postNumber, and targetTeamName including the source-team default. The description restates the targetTeamName default rather than adding syntax or format 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+resource ('Duplicates a post') and goes further to define the output ('a new WIP post with the same name and body_md'). The WIP/copy semantics clearly separate it from esa_create_post, which starts from scratch.

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?

Explains the default behavior (duplicate into the source team) and the condition that changes it (specify targetTeamName). No explicit when-not or alternative tool is named, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: results are paginated, include post counts, and are sorted in lexicographic order. It omits page-size defaults and any rate/scope 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?

Three sentences, front-loaded with purpose, then use cases, then output/filter behavior. The use-case list ("organization, cleanup, migration planning...") is slightly enumerative but each sentence carries information, so it stays efficient.

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 list tool with no output schema, the description covers the essentials: pagination, sort order, returned fields (paths with post counts), and filtering capability. It lacks only edge details such as default page size or maximum results, which is a minor gap given the strong schema.

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

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

Schema description coverage is 100%, so all seven parameters including the four filter modes are already documented with examples. The description only restates the filter names (prefix/suffix/match/exact_match) without adding syntax or precedence semantics, 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 category paths in a team") and clarifies the scope with "overall category structure," which an agent can distinguish from a point lookup. However, it never names or contrasts with the closer siblings esa_get_categories or esa_get_top_categories, so an agent still has to open schemas to route correctly.

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?

Lists intended scenarios ("category organization, cleanup, migration planning, or finding similar categories") which implies usage, but gives no explicit when-not conditions and no guidance on choosing this over esa_get_categories or esa_get_top_categories. Usage is inferred rather than stated.

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 readOnly/non-destructive annotations by disclosing the actual return-shape logic: base64 for JPEG/PNG/GIF/WebP under 30MB, signed URLs otherwise or when forceSignedUrl is set. This tells the agent what payload to expect and why, which is exactly the behavioral context annotations 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 the core action before the conditional return-format rules. Every sentence carries information; the opening 'with signed URLs' phrasing is slightly awkward but quickly clarified.

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 carries the return-value burden and does so fully by specifying the two response modes and the conditions that select them. An agent has everything needed to call this correctly and interpret results.

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 are already documented, and the description only restates the forceSignedUrl effect. Baseline 3 is appropriate since the schema does the heavy lifting on parameter meaning.

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') that is unambiguous and distinct from every sibling, none of which deal with attachment files. An agent can identify this tool's domain 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?

Usage is implied by the purpose (fetch an attachment when you have its URL), and the description explains the base64/URL branching, but it never states when to prefer this tool over alternatives or any prerequisite. No explicit when-not or alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds useful context about what is returned (subcategories plus optionally posts and parent categories), but says nothing about ordering, depth limits, or behavior when the path does not 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 no filler, and the scope (specific category path) is front-loaded ahead of the optional inclusions. It is efficient and readable, though it could have spent one more clause on differentiation from siblings.

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 carries the burden of describing the return content, and it does so by naming category info, subcategories, and optional posts/parent categories. For a moderate six-parameter read tool this is reasonably complete, though pagination behavior (page/perPage) and error cases are left 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%, so all six parameters are already documented in the schema, making the baseline 3 appropriate. The description maps loosely to the 'include' enum (posts, parent categories) and descendantPosts, but adds no format, syntax, or default details 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 names a specific verb (retrieves) and resource (category information and subcategories) scoped to a specific category path, which is clearer than the terse title. It does not, however, differentiate itself from close siblings such as esa_get_top_categories or esa_get_all_category_paths, leaving the agent to infer the distinction.

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 by the phrase 'for a specific category path' – the agent can infer that this tool is for a single path rather than top-level or all paths. There is no explicit statement of when to use this versus esa_get_top_categories or esa_get_all_category_paths, and no prerequisites beyond what the schema already states.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that stargazers can optionally be included, which is useful behavioral context, but it does not elaborate on response details or permission requirements.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the core action and the optional inclusion behavior efficiently.

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 low-complexity read tool with full schema coverage and clear annotations, the description is minimally adequate. It does not surface the team-context requirement or route to alternatives, but those gaps are partly mitigated by the schema and sibling tools.

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 commentId, include, and teamName are already documented in the schema. The description repeats the comment ID and stargazers option but adds no syntax or meaning beyond the structured parameters.

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

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

The description states a specific verb and resource: retrieve a comment by comment ID. It is clear what the tool does, but it does not distinguish itself from sibling list tools like esa_get_post_comments or esa_get_team_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?

The description implies use when a comment ID is known, but it gives no explicit when-to-use guidance, prerequisites, or alternatives to related comment-retrieval tools. It does not tell an agent when to choose this over esa_get_post_comments or esa_get_team_comments.

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 only declare a safe read operation; the description adds that the response always includes backlinks_count, a genuinely useful behavioral detail not available from the schema or annotations. It stops short of covering not-found behavior or auth requirements, but no output schema exists so this disclosure is valuable.

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 the tool does, then the guaranteed response field, then the two alternative tools. Every sentence earns its place with no filler.

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

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

For a read tool with rich schema coverage and annotations, the definition covers purpose, routing to siblings, and one key return field. Minor gaps remain around failure modes and output shape, but nothing essential to 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%, so teamName, truncate and postNumber are already documented thoroughly in the schema (including truncation semantics). The description adds no parameter-level 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 (retrieves) and resource (a specific post in an esa team), scoped by post number. It is clearly distinguishable from search_posts and the sibling comment/backlink tools.

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

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

Explicitly routes the agent to esa_get_post_backlinks for referencing posts and esa_get_post_comments for comments, which is exactly the disambiguation needed among nearby siblings. It does not, however, state when to reach for this tool versus esa_search_posts or discuss prerequisites such as resolving teamName first.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: archived and WIP posts are filtered out, results are newest-first by registration date, and the list is paginated. It stops short of discussing permissions or rate limits, but that is a minor gap given the annotation coverage.

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

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

Three tight sentences with zero filler, front-loading what the tool returns before adding the exclusion and ordering constraints. Every sentence contributes actionable 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, no-output-schema tool, the description covers filtering behavior, sort order, and pagination, which is what an agent needs to call and interpret it correctly. It does not describe the shape of returned backlink entries or whether totals/counts are included, a minor omission given the safety profile is fully carried by 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 all four parameters (page, perPage, teamName, postNumber) are already documented in the schema. The description confirms the paginated nature and the target post but adds no format, default, or constraint detail beyond the schema, matching the baseline 3 for high-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?

States a specific verb (Retrieves) and resource (paginated list of posts that link back to the specified post), which no sibling tool does. An agent can immediately distinguish it from esa_get_post, esa_get_post_comments, or esa_search_posts 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?

The description gives useful operational context (excludes archived/WIP posts, orders by backlink registration date newest-first), which implies when the result is appropriate. However, it never names a when-to-use trigger or an alternative tool, so usage is only implied rather than guided.

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. The description's only added claim, 'with pagination support,' merely restates the page/perPage parameters already visible in the schema, so it contributes essentially nothing behavioral beyond structured 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?

A single front-loaded sentence with no filler; the verb, resource, and scoping qualifier come first 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?

Adequate for a read-only list tool whose annotations cover safety, but it does not resolve the schema's internal ambiguity where teamName is described as 'required' yet absent from the required array, nor does it mention ordering or comment shape. An agent calling it correctly has to work around that gap unaided.

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 (page, perPage, teamName, postNumber) are already documented in the schema and the baseline of 3 applies. The description adds no format, default, or ordering detail beyond that.

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') plus the scope ('for a specific post'), which implicitly separates it from esa_get_team_comments and the singular esa_get_comment. However, it never names those siblings explicitly, so differentiation relies on the agent inferring from scope wording.

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 when-to-use or when-not-to-use guidance and no alternative tool is mentioned, despite close siblings (esa_get_comment, esa_get_team_comments) that an agent could easily confuse with this one. 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 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 structurally. The description adds only that pagination is supported, which is a modest behavioral detail and is also implied by the page/perPage parameters.

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. Nothing could be removed without losing 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 simple read-only list tool with full schema coverage and no output schema, the description is barely adequate. It omits ordering, default page/perPage behavior, and how team-level results relate to post-level comment tools, all of which an agent would need to call it confidently.

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

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

Schema description coverage is 100% and the schema documents page numbering (starts from 1), perPage, and the teamName prerequisite, so the baseline is 3. The description's "pagination support" merely echoes the schema rather than adding format or defaulting nuance.

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") and scopes it to a team, which implicitly separates it from the sibling esa_get_post_comments. It does not name that sibling or otherwise tell the agent how team-scoped comments differ from post-scoped ones, so it falls short of full sibling differentiation.

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 appears in the description. The only routing hint ("Use esa_get_teams first") lives in the teamName schema field, not the description, and nothing explains why an agent would pick this over esa_get_post_comments or esa_get_comment.

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 and the bar is lower. The description usefully discloses the returned content (roles and profile information) but also claims it retrieves 'all members' while the schema exposes page/perPage paging, leaving pagination behavior and result limits undisclosed.

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 no filler and a front-loaded verb, which is appropriate for a simple list tool. It is arguably under-specified rather than over-verbose, 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?

With full schema coverage and annotations, the definition is largely adequate, and no output schema means return values need not be described. However, the description omits the esa_get_teams prerequisite and does not reconcile 'all members' with the available pagination parameters, leaving a moderate gap for a five-parameter 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%, including enum-constrained sort/order fields and a note on teamName, so the schema carries the parameter burden. The description adds nothing about sortable fields, ordering defaults, or that teamName is effectively required despite being listed as optional, so it earns only the baseline.

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

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

States a specific verb and resource ('Retrieves all members of a team') and adds what is returned (roles and profile information), so the agent knows exactly what the call yields. It does not reference any sibling such as esa_get_teams, though no sibling directly overlaps this resource, so the lack of differentiation is a minor gap rather than a confusion risk.

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 guidance and no prerequisites, even though the schema itself notes that esa_get_teams should be called first to obtain valid team names. That critical routing information exists only in the input schema, not in the description the agent reads first.

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 the access-scoped nature of the results, which is genuinely useful, but says nothing about pagination behavior or result shape.

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 economical sentence with the resource and scope front-loaded and zero filler. It is short but not padded, so conciseness is a strength rather than an under-specification problem.

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 this is close to adequate, and annotations plus a fully documented schema carry most of the weight. With no output schema, however, the description should ideally hint at the returned team shape or pagination semantics, and it does not.

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, role, and perPage all documented in the schema, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already provides.

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

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

States a clear verb ('Retrieves') and resource ('a list of esa teams'), plus a scope qualifier ('that the user has access to'). This is unambiguous, though it never contrasts itself with team-scoped siblings like esa_get_team_members or esa_get_team_stats.

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 guidance on when to use this versus alternatives, nor any mention of how pagination or role filtering should drive the call. The agent gets a purpose but no operating 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?

Annotations already declare this is a safe, non-destructive, closed-world read, so the safety profile is covered structurally. The description adds value by disclosing exactly what the payload contains (total/WIP/shipped post breakdowns, DAU/WAU/MAU), but it says nothing about the empty-default teamName behavior or the shape/size of the response.

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 sentence, front-loaded with the verb and resource, with every clause contributing concrete return-field information. The field enumeration is dense but earns its place since there is no output schema to describe the payload.

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 no output schema, the description usefully compensates by listing the metrics returned. The remaining gap is the semantics of the empty default teamName, which neither the description nor the annotations explain.

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 is fully documented there, including the 'call esa_get_teams first' hint. The description adds no syntax or format 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?

States a specific verb ('Retrieves') and resource ('team statistics') and enumerates the returned metrics (member count, posts, comments, stars, watches, active users), which cleanly separates it from siblings like esa_get_team_members or esa_get_team_comments. It does not explicitly name a sibling it is distinct from, 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 description offers no when-to-use guidance, no prerequisites, and no comparison to the sibling tools that return adjacent team data. The only routing hint ('Use esa_get_teams first') lives in the schema's parameter description, not here, so the description itself carries no usage direction.

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 the return shape (tag list plus per-tag post counts), but says nothing about pagination behavior, ordering, or whether archived posts are included.

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 tight sentence that front-loads the core action and appends the most useful extra detail (post counts). No filler or redundancy.

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

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

There is no output schema, so the description must carry return-value information, and it does state the tag+count shape. However, pagination semantics and the scope of 'posts' (published vs. archived) remain unstated, leaving gaps for a paginated 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 description coverage is 100%, so page, perPage, and teamName are already fully documented in the schema. The description adds no parameter-level meaning beyond that, 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?

The description gives a specific verb and resource ('retrieves all tags used in posts within a team') plus scope ('along with the count of posts for each tag'), which distinguishes it from siblings like esa_get_categories or esa_get_team_members. It is clear and unambiguous, though it does not name any sibling tool 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, and no mention of prerequisites or alternatives. The prerequisite (call esa_get_teams first) lives only in the schema's teamName description, not in the tool description itself.

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 without the description. The description adds only the 'top-level' scoping notion; it says nothing about whether children are included, ordering, or what happens if the team has no categories.

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 the resource and scope front-loaded and no filler. It is efficient, though it is arguably under-specified rather than truly concise.

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, closed-world read tool with no output schema, the description is minimally sufficient: the agent knows it lists top-level categories for a team. It omits the shape of the result (flat list vs. tree) and how the empty-default teamName resolves, which would help given the schema marks it 'required' but gives it a default.

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 teamName parameter, including the pointer to esa_get_teams, so the schema carries the full semantic load. The description contributes nothing about the parameter, which is the expected baseline when the schema is complete.

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 ('Retrieves all top-level categories') with a clear scope qualifier ('top-level') and the owning entity ('for a team'). It does not, however, differentiate itself from near-name siblings like esa_get_categories or esa_get_all_category_paths, leaving the agent to guess which one returns the hierarchy.

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 in the description about when to use this tool versus esa_get_categories, esa_get_all_category_paths, or the team-scoped siblings. The only routing hint ('Use esa_get_teams first') lives in the schema, not the description, and no prerequisites or exclusions are stated.

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 destructiveHint=true; the description usefully qualifies that by saying changes are stored as a new revision, which tells the agent the prior body is recoverable. It also notes wip is optional and otherwise inherited from the post's current state. No permission or rate-limit context, so not a 5.

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

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

Three tight sentences with the core action front-loaded, followed by the two sibling differentiations and the wip note. No filler or 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?

For a 5-parameter mutation with full schema coverage and no output schema, the description covers action, revision semantics, sibling routing, and the optional wip change. Missing only edge behavior such as how postNumber/teamName interact or failure modes, which keeps it from a 5.

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 baseline is 3. The description only reiterates the optional wip parameter, adding no syntax, formatting, or boundary detail beyond what the schema already documents.

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

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

States a specific verb (prepend) and resource (existing post body) plus the effect (saved as a new revision). It explicitly differentiates from the two closest siblings, esa_update_post and esa_append_post, so an agent can place it 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 the alternatives and the condition that selects this one over esa_update_post ('does not require fetching the current body first') and over esa_append_post (inserted at start). There is no explicit when-not guidance (e.g. when to prefer append/update anyway), so it falls short of a full 5.

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 safety profile is covered. The description adds genuinely useful context beyond that: the rollback preserves history by saving the restored content as a new revision. It omits permission/team requirements and reversibility of the new revision, so it is good but not complete.

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 tight sentence that front-loads the action and appends the one non-obvious behavior (new revision). No filler or redundancy.

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

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

For a mutation tool with annotations covering the destructive flag and a fully documented 5-parameter schema, the description is nearly sufficient. It would be complete with a note on required team context and how the resulting revision is identified, but nothing essential 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%, so every parameter (including postNumber, revisionNumber, wip, message, teamName) is already documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, 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 ('rolls back') and resource ('a post') with the target ('the specified revision'), and adds the key side effect of creating a new revision. It is clearly distinguishable from siblings like esa_update_post or esa_archive_post, though it never names those alternatives.

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

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

The description implies a restore/history use case but gives no explicit when-to-use guidance, no contrast with esa_update_post (the obvious alternative for editing), and no prerequisites such as needing a revision number obtained earlier.

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 the 'unfamiliar workflows' framing but says nothing about return format, pagination, or result ranking, so it only marginally exceeds what structured fields already 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?

Two tightly written sentences: purpose first, usage conditions second, with zero filler. The front-loading lets an agent decide in the first clause whether the tool is relevant.

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 search-help tool with no output schema, the description covers purpose and triggering conditions adequately, and the rich query schema fills in the search syntax. Minor gaps remain around pagination/return shape, but nothing critical 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%, and the query parameter's schema text is extremely detailed (date syntax, OR operators, tag:/category: modifiers), so the schema carries the burden. The description adds no parameter guidance beyond what the schema documents, making the baseline 3 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?

States a specific verb and resource: 'Search esa documentation for features, terminology, and specifications.' The word 'documentation' implicitly separates it from esa_search_posts (which searches user posts), but no sibling is named explicitly, so the differentiation is left to inference.

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

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

Provides concrete when-to-use triggers: 'users mention esa-specific terms, ask about esa functionality, or request help with esa workflows that you're not familiar with.' Clear context, but no when-not guidance and no alternatives named (e.g., esa_get_markdown_syntax_help or esa_get_search_options_help for narrower doc topics).

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 nothing behavioral on top — no mention of pagination limits, result ordering, or that the search is team-scoped.

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 short sentence with zero filler, and the purpose is front-loaded. It is efficient, though the brevity shades into under-specification for a tool with six parameters.

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

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

There is no output schema, so return shape is outside the description's remit, and the schema documents parameters thoroughly. Still, a search tool with pagination, sorting, and team scoping offers nothing in the description about result caps or the required team context, leaving an agent to infer it all from 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 description coverage is 100%, including a very detailed query description covering date syntax, AND/OR behavior, and advanced operators, so the schema carries the parameter burden. The tool description contributes no additional parameter meaning, which makes the baseline 3 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?

States a specific verb+resource ('Search for posts') in 'esa.io', so an agent knows this retrieves posts matching a query rather than fetching one post like esa_get_post. However, it offers no differentiation from nearby tools such as esa_search_help or esa_get_search_options_help, and no scope detail (team-scoped, paginated).

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 named alternatives — it never says to reach for this tool over esa_get_post or esa_get_team_tags. All the practical search guidance lives in the query parameter's schema text, not in the tool 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 write (readOnlyHint=false) and destructive (destructiveHint=true), so the safety profile is covered. The description adds real context by naming the exact mutation (wip set to false) and its semantic effect (marked complete and ready to publish), though it omits side effects typical of publishing, such as subscriber notifications.

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: mechanism first, effect second, disambiguation last. No filler, and the most decision-relevant information is front-loaded.

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?

No output schema exists, but the description makes clear what the call does to the post state and when to prefer it. It stops short of describing publish-time side effects (e.g. notifying subscribers) or error conditions, which would matter for a destructive-flagged publish action.

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 teamName and postNumber both documented in the schema, so the schema carries the parameter burden. The description adds no syntax or format detail beyond what the schema already states, making the baseline 3 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?

States a specific verb and resource ("Ships a post") and explains the underlying mechanism ("setting wip to false"). It explicitly distinguishes itself from esa_update_post, so an agent can choose between them without opening 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?

Provides an explicit when-to-use condition ("only when you need to ship without making other changes") and names the concrete alternative ("use esa_update_post with wip: false instead") for the excluded case. This is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, telling the agent this is a mutating operation. The description adds nothing beyond that: it doesn't say the existing body is overwritten, that only the author/owner can edit, or how partial updates behave. Minimal added value over structured 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?

A single, front-loaded sentence with no filler. It is efficient, though it is so terse that it omits useful detail rather than being verbose.

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

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

For a destructive update tool, the description is thin: it doesn't communicate that the comment body is replaced, that the operation is tied to a specific team context, or that the author permission may be required. Annotations cover the safety profile, which partially compensates, but a destructive mutation warrants more.

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 (commentId, bodyMd, user, teamName) are already documented in the schema, including the owner-permission note and the teamName lookup hint. The description contributes no additional parameter meaning, 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 ('Updates') and resource ('an existing comment') scoped to an esa team by comment ID, which cleanly separates it from esa_create_comment and esa_delete_comment. It does not explicitly name those siblings, but the verb makes the distinction obvious.

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 or esa_get_comment, nor any mention of prerequisites such as the owner permission the 'user' field requires. 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 declare destructiveHint=true but the description compounds that by disclosing that body edits replace content rather than append, which is the key behavioral distinction driving the sibling routing. It stops short of covering auth/permission needs or the conflict-checking implications of originalRevision, so it is useful but not complete.

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 sentences, front-loaded with the action and identifier, then field inventory, then two routing rules. No sentence is filler and the most decision-relevant guidance (ship vs. append) comes before the less critical detail.

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

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

Adequate for invocation of a nine-parameter destructive mutation with a nested object: the agent knows what it does, which fields it can change, and where to go for append/ship alternatives. The gap is originalRevision conflict handling, which is passed through without any behavioral explanation, and no output schema exists to clarify 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 the schema already documents all nine parameters including wip, bodyMd, and originalRevision, making 3 the baseline. The description restates the five primary mutable fields and clarifies the ship semantics of wip, but adds nothing for message, teamName, or the nested originalRevision conflict object.

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 immediately enumerates the mutable fields. This is clearly distinguishable from esa_create_post, esa_ship_post, and esa_append_post/esa_prepend_post, which the description names directly.

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: use wip=false to ship rather than esa_ship_post when also updating other fields, and use esa_append_post/esa_prepend_post when only adding content at the start or end of the body. Both the when and the when-not are spelled out with named alternatives.

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