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

With readOnlyHint and idempotentHint already provided by annotations, the description adds a critical behavioral nuance: post numbers are only unique within a team, which is essential knowledge beyond the annotation layer.

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, front-loaded with the action, zero waste, and immediately conveys both purpose and a key constraint.

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

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

Given annotations cover safety and idempotency, the description provides the needed scoping rule for post_number, though it could note that the team parameter is required and perhaps formats for other fields.

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

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

Schema coverage is 0% and description text does not define either parameter in detail, but the statement about post number uniqueness within a team adds significant meaning to the post_number 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?

States a specific verb (read) and resource (full Markdown body of an esa post), clearly distinguishing this from siblings like esa_search_posts or esa_list_recent_posts which do not return full bodies.

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 this is the tool to use when you need the full body instead of a snippet or list, but it does not explicitly compare to alternatives like esa_search_posts or esa_list_recent_posts.

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

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

Annotations already declare readOnly, idempotent, and non-destructive reads, so the safety bar is met; the description adds genuinely new behavior: comments are ordered by update time descending and the result carries a next_page cursor. That pagination and ordering detail is what an agent needs 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 efficient sentence that front-loads the action and return shape with no wasted words.

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

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

With no output schema, the description usefully discloses the return content (Markdown bodies, next_page) and ordering. It is adequate for a read-only list tool, with the only gap being the undocumented team/post_number semantics.

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

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

Schema coverage is 50%: page and per_page are well documented in the schema (including 'use next_page from previous result'), while team and post_number are undocumented. The description does not compensate by explaining those two parameters, but it does reinforce the pagination contract. Baseline 3 fits.

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 (read comments on a post) and adds scope details (a page, Markdown bodies, next_page). It does not differentiate from siblings like esa_get_post, but the resource is distinct enough that confusion is unlikely.

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 names no alternatives among the sibling tools. It only states the ordering, which is informational rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely non-structured behavioral detail: results are paginated per team and a next_page cursor is returned, which is not derivable from the annotations.

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

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

Three short sentences with no filler, and the core purpose is front-loaded ahead of the pagination and default-scope notes. Nothing needs to be removed.

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 steps in to explain the return shape (one page per team plus next_page) and the default all-teams scope. That covers what an agent needs to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so the schema already documents page, per_page, team, and teams. The description's 'Omit team/teams for all teams' largely restates the schema's own note about querying all accessible memberships, so it adds little beyond 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 ('List recently updated posts per team') plus ordering ('newest first'), which is enough to distinguish it from esa_get_post or esa_list_comments. It does not explicitly name a sibling such as esa_search_posts, so it stops short of full 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?

Gives one useful routing rule — 'Omit team/teams for all teams' — which tells the agent how to query broadly. However, it never states when to prefer this over esa_search_posts or other listing tools, so usage is only implied.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavior: pagination is followed automatically ('following all pages') and results are cached for 60 seconds, which tells the agent staleness can occur.

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

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

Two short sentences, front-loaded with the verb and resource, with the pagination and caching facts attached where they matter. Nothing superfluous.

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, no-required-params list tool with no output schema, the description covers scope, pagination, and caching. Only the shape of returned team objects is unspecified, which is a minor gap.

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 refresh param is already documented as bypassing the cache. The description's 'Cached for 60 seconds' reinforces why that flag exists and what its effect is, adding slight value over the schema baseline of 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?

States a specific verb (List) and resource (teams), plus a precise scope: teams 'accessible to the current esa user'. This is unambiguous and cannot be confused with the post/comment siblings.

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

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

The purpose implies the use case (enumerate the caller's teams), but there is no explicit when-to-use guidance, no exclusions, and no alternatives referenced. Since no sibling covers teams, ambiguity is low, but the description still leaves usage 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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuine value beyond them by disclosing the return shape (one page per team, newest updated first, excerpts, per-team next_page), which is not derivable from annotations or schema.

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. The core purpose is front-loaded, followed by return shape and then the team/teams constraint, in the order an agent needs them.

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 explaining results and does so well (per-team pages, excerpts, next_page). The mutual-exclusion constraint is covered. The only gap is that the referenced 'esa search syntax' is not characterized at all, which an agent unfamiliar with esa must guess at.

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 page, per_page, team, teams, and query semantics. The description restates the team/teams mutual exclusion and the omit-to-search-all behavior, which is useful but largely duplicative of the structured fields. Baseline 3 applies 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 ('Search esa posts') plus scope ('using esa search syntax'), and adds the return shape (one page per team, newest updated first). It does not explicitly name siblings like esa_list_recent_posts or esa_get_post, so the agent must infer the distinction, but the 'search syntax' framing distinguishes it reasonably well.

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 real usage constraints: 'team/teams omitted searches all teams' and 'team and teams cannot be combined.' However, it never says when to choose this over esa_list_recent_posts or esa_get_post, so the when-to-use guidance is only implied by the search-syntax framing.

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