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

Goes well beyond the annotations: discloses the authorization requirement, that the new link is appended rather than prepended, that nobody is notified, that the return value is the whole new list, and how to reverse it. The 'no confirmation needed' note is exactly the kind of operational guidance annotations cannot 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?

Front-loaded with the action and the admin gate, and every sentence carries information. However 'Admins only' is stated twice in a three-sentence description, which is a small but real 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 three-parameter mutation with no output schema, the description covers auth, side effects, return shape, and reversibility. Nothing an agent needs in order to call 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?

Schema description coverage is 100%, so group, label, and url are already documented with format and length constraints. The description adds no syntax, default, or edge-case detail about any parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Add a link to the group's sidebar') plus the insertion position ('after the existing ones'). The verb 'add' cleanly separates it from the sibling update_group_link and delete_group_link, which the description even names for the undo path.

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 preconditions ('Admins only'), the equivalent manual path ('Settings, Links, Add'), and a confirmation policy ('runs without asking first') because it's undoable via delete_group_link. It stops short of naming when to prefer update_group_link over adding a new link, so it is not 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?

Goes well beyond annotations: append-only ordering, returns the full new list, no one is notified, admin authorization required, and reversibility via delete_group_rule — which justifies bypassing confirmation. This is consistent with destructiveHint=false and non-idempotent hints. The only flaw is restating 'Admins only' twice.

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?

Short and front-loaded with the core action and placement first, then constraints. However 'Admins only' appears twice in four sentences, which is pure duplication and the one clear waste in an otherwise tight description.

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

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

For a simple 3-parameter mutation with no output schema, it covers authorization, effect, ordering, return value, and undo path — everything needed to call it safely. Only minor gaps remain, such as how the returned list is shaped or whether title collisions are rejected.

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 group, title, and description semantics are already fully documented in the schema. The description adds no per-parameter guidance (no format hints, no note on optional description beyond what the schema says), 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 ('Add a rule ... group rules') and pins the placement ('at the end', 'after the existing ones'). The UI analogy 'as Settings, Rules, Add does' makes it unambiguous which sibling it is versus update_group_rule, delete_group_rule, and list_group_rules.

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 preconditions: admin-only access, and it should run without a confirmation prompt because it is non-notifying and reversible. It names delete_group_rule as the undo path, which effectively routes the agent to the right counterpart. It does not explicitly contrast with update_group_rule (editing an existing rule), which is the closest ambiguity.

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

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

Adds real behavior beyond the annotations: platform cap of 3 questions, only one allowed of type email, answers surface in list_membership_requests, the call returns all questions, it executes without a confirmation step, and nobody is notified. None of this conflicts with readOnlyHint=false / destructiveHint=false / idempotentHint=false / openWorldHint=true.

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?

Front-loaded with purpose, then constraints, then side effects; nearly every sentence carries information. The only waste is the duplicated 'Admins only,' stated once in the opening line and again near the end.

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 says the call returns all questions and where answers later appear. Together with the permission, count-limit, and notification notes, an agent has everything needed to invoke it correctly; only the return shape detail (fields of a question) is thin.

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 baseline is 3, but the description adds meaning the schema lacks: a group-level cap of 3 questions and the restriction that at most one may be of type email — constraints that affect how the 'type' parameter should be set. It doesn't otherwise elaborate on the 'options' or 'question' fields, which the schema already covers.

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?

Opens with a concrete verb+resource plus the end-user purpose: 'Add a question people answer when they ask to join the group.' This clearly separates it from update_membership_question and delete_membership_question in the sibling list, and from list_membership_requests which only reads.

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?

States the admin-only prerequisite and maps the action to its UI path ('Settings, Membership questions'), giving the agent a clear context for when this tool applies. It does not explicitly say when to prefer update_membership_question over adding a new one, so the alternative-routing guidance is incomplete.

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

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

Adds genuine behavioral context beyond the annotations: an AutoDM is triggered to the applicant as a side effect and the caller must be an admin/moderator. However it never addresses irreversibility (annotations flag destructiveHint=true), failure modes for an already-approved or stale request, or rate/bulk behavior.

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

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

The sentence 'your AutoDM, if set, goes out as usual' appears twice nearly verbatim, and the opening 'Let an applicant into the group' is restated immediately after. Real information is buried in a duplicated, out-of-order block rather than 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?

For a two-parameter mutation whose schema and annotations are fully populated, the description covers the essentials an agent needs: single-request scope, admin/mod requirement, and the AutoDM side effect. Missing only failure/reversibility notes, which is a modest gap given destructiveHint already signals risk.

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 both parameters are already documented, including that request_id comes from list_membership_requests. The description's only addition is the member_id/request_id equivalence note, which is mildly useful but introduces a parameter name that does not exist in the schema.

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

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

States a specific verb and resource: 'Approves one pending request, so the applicant becomes a member,' anchored to a known UI action ('as Skool's Approve button does'). The scope is limited to a single request, which implicitly separates it from bulk/list operations, but the natural counterpart decline_membership_request is never named.

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 a real prerequisite ('Admins and moderators only') and makes clear it acts on one pending request per call, which tells the agent it must loop for multiple requests. It does not route the agent between approving vs declining or removing a member, so no explicit 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 declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: the member loses access and cannot re-request to join, deleted posts/comments are irreversible, and a paid subscription is not cancelled as a side effect. The only blemish is the internal contradiction between "Admins only" and the trailing "Admins and moderators," which leaves the actual permission requirement ambiguous.

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 key facts (ban, irreversible post deletion, no subscription cancel) are front-loaded, but the second sentence is bloated and awkwardly phrased ("as Membership settings, Ban does:"), and the closing permission fragment reads like leftover text. Trimming would also have prevented the admins/moderators contradiction.

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 permissions, irreversibility, side effects on subscriptions, and the reverse operation, which is most of what an agent needs. It does not say what is returned or what happens on a non-admin/moderator call, leaving a small gap for a high-stakes write.

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

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

Schema coverage is 100%, so all four parameters are already documented and baseline would be 3. The description still earns a bump by explaining the consequence of delete_recent_posts (removes recent posts and comments, cannot be undone) beyond the schema's neutral "as Skool offers" wording, and by clarifying the one-member-per-call constraint.

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 ("Ban a member from the group") and immediately adds a distinguishing scope detail (optionally deleting recent posts, one member at a time). It also explicitly distinguishes itself from the sibling remove_member, so an agent can route between the two without opening 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?

Gives a clear usage context (admin action, one member per call) and names the alternative tool remove_member rather than leaving the agent to infer it. However, "remove_member lifts a ban" is a terse, easily misread statement of the reverse relationship, and the guidance closes with a permission clause that conflicts with the opening one.

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

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

The annotations already declare this as non-read-only, non-idempotent, open-world, and destructiveHint=true. The description adds useful identity context by saying the comment appears under your name, but it does not reconcile the destructiveHint=true annotation or explain visibility, moderation, or irreversibility.

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 definition is short and front-loaded. The second sentence somewhat repeats the first but earns its place by adding the parent_comment_id condition and the author-name 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?

For a simple four-parameter mutation with a fully described schema and safety annotations, the description gives enough context to invoke the tool correctly. It is weaker on side effects and does not explain the return value, though no output schema exists and this is not critical for invocation.

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 body, group, post_id, and parent_comment_id. The description only restates the parent_comment_id reply behavior without adding syntax, examples, or constraints beyond the schema.

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

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

States a specific verb and resource: commenting on a post or replying to a comment. It clearly separates the top-level comment case from the reply case, which is enough to distinguish it from siblings such as create_post, like_post, and follow_post.

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

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

Explains that parent_comment_id makes the operation a reply under an existing comment rather than a top-level post comment. It does not name alternatives like create_post or set_post_comments, nor does it state exclusions, so it is clear but not fully routing-oriented.

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=false, destructive=false, openWorld=true), and the description adds real context beyond them: admin authorization requirement, that no color parameter exists because 'Skool picks its color', that members see the category immediately, and that no one is notified so confirmation isn't needed. Remaining gaps are edge cases like duplicate names or failed validation on the 30-character cap.

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?

Front-loaded with the action and the permission gate, and every sentence is short. The main inefficiency is 'Admins only' stated twice in four sentences, which is redundant wording rather than harmful ambiguity.

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 creation tool with annotations but no output schema, the description covers permissions, side effects, notification behavior, and the key enum semantic. It never states what the call returns (e.g., the new category's identifier or slug), which is a minor gap given there is no output schema to lean on.

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 baseline is 3; the description earns above that by explaining the who_can_post value 'admins' as an announcements-style category only admins post in, and by clarifying that color is not settable. The sort parameter is not elaborated beyond the schema, which is the one omission.

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?

Opens with a specific verb + resource and scope: 'Add a category to a group's feed.' The 'as Settings, Categories, Add does' anchor makes it unambiguous that this creates a new category, distinct from update_category/delete_category/list_categories. It doesn't explicitly name a sibling, 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?

Usage is implied rather than stated: creating a brand-new category, admin-only. There is no explicit routing advice such as 'to rename or reorder an existing category use update_category' or a statement about what happens when the name already exists. The 'runs without asking first' line addresses confirmation behavior rather than tool selection.

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 non-read-only, non-idempotent, non-destructive, open-world. Beyond those, the description adds admin-only authorization, the visibility consequence of draft vs published, and the fact that access can be gated by level. It does not say whether publishing notifies members or whether duplicate titles are rejected, which for a non-idempotent create tool would be 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?

Front-loaded and understandable, but it repeats 'Admins only' twice and restates the draft/published rule in three places, plus an opaque 'as Classroom, New course does' UI reference that adds no machine-actionable meaning.

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, and the description doesn't say what comes back (a course id?) — a real gap since create_lesson presumably needs that id to chain. Otherwise complete for a 5-param create tool: authorization, defaults, visibility, and follow-up step are all covered.

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 explains all five parameters including defaults for published and min_level. The description adds context around the published flag (draft visibility) but no new syntax, constraints, or interaction rules beyond the schema. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource ('Add a course to the group's Classroom') and immediately scopes it to draft vs published. It also signposts the adjacent tool ('Add lessons with create_lesson'), which helps separate this from lesson-level siblings. Minor redundancy ('as a draft or published' then 'as a draft unless published is true') keeps it 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?

Gives real selection guidance: use it for a draft when you don't want to ask first ('A draft is seen by admins only, so it runs without asking first'), and directs lesson creation to create_lesson. It also notes paid and time-unlocked courses are configured in Skool, i.e. not here. No explicit statement of when NOT to use it (e.g., for editing an existing course), so not a 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?

Adds substantive behavior beyond the annotations: admin-only authorization, immediate member visibility ("Members see it at once"), and the reminder side effect ("Skool reminds members before it starts"). It does not spell out that repeated calls create duplicate events, which matters given idempotentHint=false, but the surrounding context is well covered.

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?

"Admins only" appears twice in a four-sentence description, and the duplicated clause about member visibility versus the UI reference could be merged. The core content is front-loaded and there is no padding beyond that 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 an 11-parameter mutation with no output schema, the description covers the essentials an agent needs: permission gate, resulting visibility, notification side effect, and the field set. Remaining gaps (duplicate-on-retry behavior, what the response contains) are minor against a fully documented 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 every parameter is already documented, and the description largely re-lists the same fields. The one added gloss is mapping "who sees it" to the access options and clarifying that location can be a link, address, or URL — marginal gain over 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?

"Add an event to a group's calendar" is a specific verb+resource and the following sentence enumerates what gets created (title, start, length, time zone, location, visibility), so an agent knows exactly what this produces. It never names update_event, delete_event, or list_events, so sibling routing is left to the verb alone.

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

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

The description anchors usage in a familiar UI action ("as Add event does") and states an admin-only prerequisite, which is real context. It gives no explicit when-not guidance or alternative — e.g. that editing an existing event requires update_event rather than a second create.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real value beyond them: admin-only authorization, draft-vs-published visibility, that no one is notified, and that the call executes without confirmation. It stops short of describing the return value, and the 'runs without asking first' phrasing is useful but somewhat buried after a repeated 'Admins only'.

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 main behavior is front-loaded and no sentence is filler, but the definition is repetitive: 'Admins only' appears twice explicitly and a third time implicitly via the draft-course visibility clause, and the opening sentence is restated almost verbatim in the second. Trimming the duplication would make it tighter 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?

With six parameters, no output schema, and annotations present, the description covers the essentials an agent needs: authorization, visibility defaults, side-effect (no notification), content constraints, and the requirement for a course_id. The only gap is that it never says what the call returns (e.g. a lesson id), which would matter when chaining into update_lesson.

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 every parameter is already documented, including the default for published and the accepted video providers. The description adds only marginal semantics (the video plays above the text; blank lines create paragraphs is in the schema, not the description), 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 (create a lesson), its placement (at the end of a course), and the payload it accepts (title, text, optional video link). It is clearly distinguishable from the sibling update_lesson and from create_course, and it names what is not supported (uploaded videos and files).

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

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

Gives concrete preconditions and exclusions: admins only, no uploaded video/file uploads, and the effect of published=false. It does not explicitly name an alternative sibling (e.g. use update_lesson to change an existing lesson), so routing is implied 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?

Annotations already declare non-read-only, destructive, open-world, non-idempotent, so the safety bar is lower. The description still adds real value beyond them: category validation happens before the approval wait and fails fast with the group's categories in the error message, and poll_options nests a poll under the text. It doesn't explain the approval flow outcome or what is returned after publishing.

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?

Lead sentence carries the core action, with constraints and failure behavior following in a tight four-sentence block. The second sentence restates much of the first (feed, category, authorship), costing a small amount of 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 no output schema, the description covers what is created, authorship, category validation and its error behavior, poll attachment, and the media limitation. Nothing critical 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 coverage is 100%, so all five parameters are already documented including poll_options' 2–10 range. The description adds only the framing that poll_options places the poll "under the text" and that category matching is case-insensitive via the group's own naming, which is marginal over 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 and resource ("Publish a post to the community feed in a category, as you") plus scope and authorship semantics. An agent can immediately tell this apart from update_post, comment_on_post, or create_category among the 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?

Clear context for use (new post in a group category, authored by the caller) and an explicit exclusion constraint: "Text only; images and files are not uploaded." It does not explicitly name update_post as the alternative for editing existing posts, so routing guidance is present but not exhaustive.

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

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

Annotations already declare the tool destructive, non-read-only, non-idempotent, and open-world. The description usefully adds the admin/moderator permission constraint and clarifies that it acts on exactly one pending request, though it does not explain downstream effects such as applicant notification.

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 short and front-loaded with the action. The second sentence slightly restates the first by repeating 'Decline,' but it also adds useful scope and permission 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 destructive, admin-only mutation with no output schema, the description covers the core action and permissions. It still leaves out what a successful decline does to the applicant or request beyond the destructive annotation, so it is adequate but not fully complete.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds little parameter-level meaning beyond indicating that request_id refers to a single pending request, which is consistent with the schema's reference to list_membership_requests.

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: declining an applicant's request to join. It is clearly distinct from sibling approve_membership_request and list_membership_requests by operation, though it does not explicitly name 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?

It specifies that the tool declines one pending request and is limited to admins and moderators. However, it does not explicitly compare usage against approve_membership_request, remove_member, or ban_member, so the when-to-use guidance 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing what actually happens to dependent data: posts are not deleted but reassigned to move_posts_to or the first other category. It also names the privilege requirement and the minimum-one-category guard, which is exactly the behavioral context an agent needs before a destructive call.

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?

Front-loaded with the action and its consequence in the first sentence, and the Settings/Categories/Delete analogy is compact. 'Admins only' is repeated verbatim in both the first and last sentence, which is the only wasted text.

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 three-parameter tool with no output schema but rich annotations, the description covers privilege, data-preservation behavior, fallback logic, and the blocking invariant. Nothing an agent needs in order to call it safely 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 coverage is 100%, so the baseline is 3; the description adds the causal link between move_posts_to and the reassignment of posts, reinforcing why the parameter exists. It stops short of adding format detail beyond the schema's 'category_id from list_categories' hint.

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 ('Delete a feed category') plus the scope-affecting side effect ('move its posts to another'), which separates it cleanly from update_category, create_category, and delete_post in the sibling list.

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

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

Gives concrete operating conditions: 'Admins only' and the invariant 'A group keeps at least one category', which tells the agent when this call will fail. It does not explicitly contrast with update_category or rename_level, so routing is implied rather than spelled out.

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 idempotentHint=false, so the safety bar is lower. The description still earns credit by adding that the action cannot be undone, that a recurring event's entire series is removed, and that admin privileges are required — all behavior not encoded in the structured fields.

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

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

The destructive scope and irreversibility are front-loaded, which is good. However, 'Admins only' appears twice (opening line and closing line), wasting a sentence in an otherwise very short description.

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 two-parameter destructive tool with full schema coverage, complete annotations, and no output schema, the description covers the essentials an agent needs: permissions, irreversibility, and recurring-series blast radius. Only the single-occurrence case and post-delete response are left implicit.

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

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

Schema coverage is 100% with both parameters fully documented (group URL name, event_id from list_events), so baseline 3 applies. The description adds only the notion of targeting a single event and says nothing about resolving recurring instances or what event_id format is expected beyond the schema.

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

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

States a specific verb and resource ('Delete a calendar event') with an access constraint, which separates it cleanly from the many other delete_* siblings (delete_post, delete_group_link, delete_category). It never explicitly contrasts with update_event or list_events, but the destructive action is unambiguous.

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

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

Adds useful context that it is equivalent to the event's Delete button in the Calendar tab, and that admins are the only permitted callers. It does not say when to prefer update_event or how to handle the recurring-series case if only one occurrence should go, so the agent must infer 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?

Beyond the destructiveHint annotation, the description explains two important behaviors: subsequent links move up a number, and the operation returns the whole new list. It does not discuss failure modes or whether removal can be undone, but it meaningfully supplements 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?

The description is short and front-loads the core action, but 'Admins only' is repeated in both sentences without adding new information. The second sentence is otherwise efficient and informative.

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 action, admin restriction, numbering side effect, and return value. Remaining gaps around error handling or reversibility are minor given the annotations and fully documented parameters.

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 parameter descriptions already carry most meaning. The description still adds useful context by explaining that deleting one link shifts the numbering of links after it, which clarifies the significance of the '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?

The description states a specific verb and resource: 'Remove a link from the group's sidebar.' It is immediately distinguishable from sibling tools like add_group_link, update_group_link, and list_group_links, and it clarifies that exactly one sidebar link is removed.

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

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

It gives the key prerequisite, 'Admins only,' and grounds the action in the familiar UI path 'Settings, Links, Delete.' It does not explicitly name alternatives such as update_group_link or list_group_links, but the intended use is clear.

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

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

Beyond the destructiveHint=true annotation, the description discloses the key side effect that later rules renumber upward and that the full new list is returned, plus the admin permission requirement. For a destructive mutation with no output schema, that is meaningful added context.

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?

Short and front-loaded with the action and the admin restriction. The only waste is the duplicated 'Admins only' at the end, which adds no new 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?

Covers permission, side effects, and return shape, which is most of what an agent needs for a destructive two-parameter tool. It doesn't mention irreversibility or error behavior for an out-of-range number, but annotations already signal destruction.

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 both parameters are already documented, including that the number comes from list_group_rules. The description's note that later rules shift up implicitly warns that stored numbers change, which is a modest value-add but not a substitute for anything missing.

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 ('Delete a group rule') and adds scope ('Deletes one rule'), which cleanly separates it from add_group_rule, update_group_rule, and list_group_rules among siblings. An agent can tell exactly what it removes 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?

'Admins only' gives an explicit prerequisite, and the Settings > Rules > Delete analogy makes the intended editorial context clear. It doesn't name a sibling as an alternative (e.g., list_group_rules for finding the number), but the schema parameter covers that link.

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 and idempotentHint=false, and the description adds genuinely new behavioral facts: subsequent questions shift up a number, the remaining questions are returned, and the call executes without confirmation or notification. That is real side-effect disclosure beyond the annotation block.

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?

Front-loaded with the action, which is good, but 'Admins only' appears twice and 'Remove a membership question' is restated as 'Removes one membership question' — roughly a third of the text is redundant.

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

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

With no output schema, the description usefully states that the remaining questions are returned, so an agent knows what comes back. Combined with the destructive/renumbering warnings, the definition covers what an agent needs to call it safely.

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 both parameters carry descriptive text (including the 'from add_membership_question or get_group' provenance hint). The description adds only the implication that 'number' is a positional index affected by renumbering, so it does not exceed the schema meaningfully.

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 ('Remove a membership question'), which distinguishes it cleanly from add_membership_question and update_membership_question in the sibling list. It doesn't name those siblings explicitly, but the operation is unambiguous.

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

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

'Admins only' gives the key prerequisite, but there is no guidance on when to delete versus update a question, or what to do if the number is out of range. Usage is implied rather than spelled out.

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 idempotentHint=false, so the bar is lower, yet the description adds real value: it discloses the cascade (deleting a post also destroys its comments), that there is no trash and the action is irreversible, and the authorization model required. That is exactly the 'what gets destroyed' context the annotations cannot express.

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

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

Three short sentences, front-loaded with the destructive action and the cascade consequence. Minor filler in the aside 'as Skool's Delete does' that does not help an agent decide or call, but nothing is buried or redundant.

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

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

For a 2-parameter, fully documented, non-idempotent destructive tool with rich annotations and no output schema, the description covers everything an agent needs: what it removes, what goes with it, who may do it, and that it cannot be undone.

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

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

Schema coverage is 100% and the schema itself already explains that post_id may be either a post_id from list_posts or a comment_id from get_post. The description restates this ('pass its comment_id') but adds no syntax, format, or edge-case detail beyond the structured field text, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a post or a comment') and immediately scopes the two modes of operation: a whole post with its comments, or a single comment passed via comment_id. The resource type alone separates it from the other delete_* siblings (delete_event, delete_category, delete_group_link).

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

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

Gives clear permission-based guidance: your own content always, anyone's content only when you are a group admin or moderator. It does not name alternative tools or say when to prefer update_post / set_post_comments instead of deleting, so it stops short of full when/when-not routing.

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 read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to cover safety basics. It adds useful behavior beyond annotations: 30 results per page, passing next_cursor back as cursor, the fields returned, and the exclusion of private hidden groups.

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 front-loaded with the core purpose and then adds the most useful operational details: result fields, pagination, cursor reuse, and scope limitations. There is a small amount of repetition around 'public directory/list of communities,' but every sentence contributes useful 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?

There is no output schema, so the description appropriately lists the directory fields returned and explains pagination. Combined with annotations covering safety and open-world behavior, it gives an agent enough context to call the tool 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%, and the schema already explains query and cursor semantics, including that an omitted query returns top groups. The description adds page size and cursor passback guidance, but this is only a modest supplement over 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 states a specific verb and resource: searching Skool's public directory of communities. The emphasis on the public discovery directory, plus the note that hidden private groups are excluded, distinguishes it from sibling tools like list_groups and search_group that operate on known/private groups.

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

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

It gives clear usage context: this is the public community discovery search, equivalent to skool.com/discovery's search box, and hidden private groups will not appear. It does not explicitly name sibling alternatives such as list_groups or search_group, so it stops short of fully explicit when-to-use-vs-alternative 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?

Adds real context beyond annotations: scope is limited to the caller's own notifications, the effect is reversible via following=false, and it is safe to run without confirmation. That directly supplements destructiveHint=false and idempotentHint=true rather than repeating them. It does not cover failure modes (e.g. following a post in a group you cannot access).

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

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

Three short sentences, front-loaded with the outcome, then mechanics, then the safety note. Every sentence carries information an agent would otherwise have to guess.

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

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

For a 3-parameter toggle with a full schema and no output schema, everything needed to call correctly is present: what changes, what the boolean does, the default, the own-post caveat, and that no approval is required.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by spelling out that 'following false unfollows' and by clarifying the own-post edge case that no parameter expresses. The mapping of post_id to list_posts stays in the schema, which is fine.

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?

Opens with a specific verb and outcome ('Get notified of new comments on a post, or stop') and names the exact resource (post). It distinguishes the tool from adjacent post operations like comment_on_post or set_post_comments by framing it as a notification subscription toggle.

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 states when to use it (wanting new-comment notifications) and how to undo (following false). It also pre-empts a common mistake by noting you already follow your own posts from the start. It stops short of naming a sibling alternative for notification management (e.g. list_notifications), so not 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real context beyond that: the admins-only auth requirement and the placeholder substitution rule (#NAME# becomes the member's first name, #GROUPNAME# the group's name). It doesn't discuss errors for non-admin callers, which keeps it from a 5.

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

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

The text is materially redundant: the opening line restates the 'welcome message ... whether it is on' summary that the second paragraph repeats in full, and 'Admins only' appears twice. The useful details are present but buried in duplicated phrasing.

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 one-parameter read tool with no output schema, the description covers what is returned (message text, sender, enabled state), the auth restriction, and placeholder behavior. Details of the exact return shape are the only omission, and those are low risk here.

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 single `group` parameter is documented with a concrete example format in the schema. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource: returns the group's AutoDM welcome chat message, its sender, and whether it is enabled. An agent can tell this is the read side of a settings pair. It does not explicitly name set_auto_dm as the mutation counterpart, so it stops 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?

'Admins only' establishes the authorization prerequisite and implies the read-versus-write split with set_auto_dm, but that alternative is never named. There is no explicit when-to-use or when-not-to-use guidance beyond the admin restriction.

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, yet the description adds real value: the ordering guarantee, the limit-capping behavior, and notably that reading does not mark the conversation read. That last point is a genuine side-effect disclosure not derivable from 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?

The opening sentence and the following sentence convey the same fact ('latest messages ... oldest first') almost verbatim, which is redundant. The ordering does confirm the response-value note, but the duplication costs space without adding 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?

With no output schema, the description usefully explains the 'from' field semantics and where member names come from, plus the non-marking-read behavior. It is complete enough to call correctly, though it does not describe pagination or what happens when fewer than limit messages exist.

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%, with limit's 1-100 range and default already documented. The description adds marginal clarification ('up to limit latest messages') but no syntax or edge-case handling beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: reads the latest messages of one Skool Chat conversation, ordered oldest first. It is distinguishable from list_conversations, though it stops short of explicitly contrasting the two. The purpose is unmistakable.

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?

Implies when to use by pointing at list_conversations and send_message as the source of conversation_id, but never states when this tool is preferred over alternatives or any prerequisites. 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?

Annotations already cover read-only/idempotent/no-destructive, so the bar is lower, and the description adds real behavioral detail beyond them: ordering guarantees ('in Classroom order'), folder kind markers interleaved with their lessons, and a visibility scoping rule for drafts vs admins. It does not cover pagination or size limits, which keeps it from a 5.

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

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

Front-loaded with the core identity and the sibling disambiguation, then a detail sentence. There is some redundancy: the opening fragment 'One course with its lessons and folders in Classroom order' is restated by 'Returns one Classroom course...', costing a little tightness.

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 shape, and it does so (fields listed, folders tagged by kind, lessons ordered). Minor gaps remain around nesting depth and missing-course behavior, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, with both group and course_id documented (including that course_id comes from list_courses or create_course). The description adds no further parameter-level 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?

The description names a specific verb and resource ('Returns one Classroom course') and enumerates returned fields (title, description, published, lessons in order). It explicitly distinguishes itself from get_lesson, which reads a single lesson's text and video, so an agent can pick between the two 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?

It gives clear routing context: use get_lesson for a lesson, and this tool for the course with its lessons/folders in order. It also states an access condition ('Only courses this account can open; admins also see drafts'), which tells the caller when results may be missing. No explicit exclusion versus list_courses, so not a 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real value by describing the returned payload (UTC-normalized times, explicit time zone, visibility scope), which matters because there is no output schema. It omits failure behavior (e.g., nonexistent event_id or access-restricted event).

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 with the return summary front-loaded. The first sentence ('full description, place and access') is largely restated by the second, a small redundancy, but there is 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 two-parameter read tool with no output schema, the description adequately conveys what comes back and in what form (UTC, time zone, visibility). It lacks only edge-case behavior such as not-found or permission-denied handling.

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%: 'group' is explained with the URL-name convention and 'event_id' is tied to list_events. The description adds no parameter-level meaning 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+resource ('Returns one event of the group's calendar') and enumerates the fields surfaced (title, description, times in UTC, time zone, location, visibility). It is clearly a single-item fetch distinct from list_events, though the description never names that sibling 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?

Usage is only implied: 'One calendar event' suggests fetching details for a known event, and the schema's event_id note ('from list_events') supplies the discovery path. No exclusions or explicit when-to-use versus list_events/update_event appears in the 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new context: output is admin-dependent, with pending_requests, reported_posts and membership questions returned as 0/empty for non-admins. It doesn't cover behavior for a nonexistent or inaccessible group, which keeps it from a 5.

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

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

The lead fragment 'A group's name, About text, privacy, price, counts, owner and membership questions.' is immediately restated in more detail by the following sentence, so the opening line does not fully earn its place. The remainder is front-loaded and dense with no further waste.

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 full burden of describing return values, and it does so thoroughly, including the conditional admin-only fields. What remains missing is edge-case behavior (invalid group name, permission errors), which an agent would need to handle.

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

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

Schema coverage is 100% and the schema already explains the 'group' parameter with a URL-name example ('yourgroup' for skool.com/yourgroup). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names a specific resource and enumerates exactly what is returned ('name, the About text, whether it is private, the price, member, admin, post and course counts, and the owner'), and 'Returns one group' distinguishes it from the list_groups/search_group siblings. It stops short of explicitly contrasting with get_group_stats, which is the closest ambiguity.

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 explicit when-to-use guidance and no alternatives are named, even though get_group_stats, search_group and list_groups overlap heavily in this domain. The only usage-relevant signal is implicit: the role-dependent field set, which is behavioral 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?

Beyond the readOnly/idempotent annotations, it discloses a real latency profile ('up to about 15 seconds' because computation is backgrounded) and the exact failure mode for non-admins (APP_PERMISSION_DENIED). It also explains how each metric is derived, which tells the agent these numbers are dashboard-sourced and may not match a manual count.

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?

Front-loaded with the payload and the admin gate, followed by metric definitions and latency. Nearly every sentence carries new information, though 'Admins only' is stated twice and could be consolidated.

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, yet the description itemizes the returned fields and their units (MRR in US dollars), states the period semantics, the latency, and the auth failure. Nothing material is missing for an agent to call this correctly.

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

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

Schema coverage is already 100%, so baseline would be 3, but the description adds genuine meaning: it defines what 7d/30d mean (growth of the daily member count) versus 90d (sum of three months of the members chart). The `group` parameter adds nothing beyond the schema, keeping it from a 5.

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 first sentence names the exact metrics returned (total/new/churned members plus MRR) and the period scope, which is far more specific than the title's 'Get group stats'. It doesn't distinguish itself from nearby siblings like get_group or get_leaderboard, but the resource and output are unambiguous.

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

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

Usage context is implied: it returns dashboard analytics for a group you administer, and the admin restriction is stated. However, with ~70 siblings including get_group, get_leaderboard and search_members, the description never says when to prefer this tool over those, so the agent must infer the boundary.

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

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

Beyond the readOnly/idempotent annotations, it discloses the scoring rule (one point per like received), the refresh cadence ('Skool recounts it every few minutes'), and the presence of an updated_at freshness field. That is meaningful behavioral context; only the absence of pagination/size limits or failure behavior keeps it from a 5.

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

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

Two sentences, the scope and periods front-loaded, then the return shape and freshness note. No filler and nothing repeated from the title.

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

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

There is no output schema, so the description carries the return contract itself: top 10, points, your rank when on the board, updated_at. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call it and read the result.

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

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

Schema coverage is 100% and both parameters are documented there, including the 30d default and the enum values, which the description merely restates. The description adds no format or edge-case guidance for the parameters, so the baseline 3 applies.

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

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

Names a specific resource (the group leaderboard), its exact scope (top 10 members by points), the supported periods, and the inclusion of the caller's own rank. That is precise enough to separate it from list_members or get_group_stats 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?

The phrase 'Returns the Leaderboards tab' implies when it applies, and the period options imply the choice within the tool. But it never states when to prefer this over sibling reads like list_members or get_group_stats, nor any exclusions or prerequisites.

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?

Although annotations already establish that this is a safe, idempotent read operation, the description adds substantial behavioral context beyond them: formatting is dropped but paragraph/list structure is preserved, uploaded Skool videos and attached files are omitted, uploaded_video indicates upload status, and only accessible lessons are returned. These are exactly the omissions and caveats an agent needs to avoid misinterpreting the result.

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 front-loaded with the essential outcome — one lesson's text and video link — and every following sentence adds useful detail about return format, omissions, or access. There is no redundant or filler content.

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

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

For a read-only lesson retrieval tool with complete parameter documentation and no output schema, the description provides sufficient completeness: it explains what is returned, what is excluded, and the access boundary. An agent can call it correctly without needing additional documentation.

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 input schema has 100% description coverage for all three required parameters, so the schema already explains group, course_id, and lesson_id. The description does not add parameter-specific meaning beyond what the schema provides, 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?

The description states a specific verb and resource: it returns one Classroom lesson, specifically its text and linked video. This clearly distinguishes it from lesson-mutating siblings like create_lesson, update_lesson, and mark_lesson_complete, as well as from course-level tools like get_course.

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 description: an agent would use this to fetch a single lesson's content after identifying its course and lesson IDs. However, the description does not explicitly say when to use this instead of get_course, list_courses, or other lesson-related siblings, nor does it name prerequisites or alternatives.

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

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

Annotations already declare this a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds meaningful context beyond annotations: exactly which fields are exposed (online status, time zone) and an explicit privacy guarantee ('Never their email or other private details').

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?

Front-loaded and generally tight, but the two sentences restate the same field list (name, bio, role, level, points) almost verbatim, so one sentence could be trimmed 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?

With no output schema, the description usefully enumerates the returned profile fields and privacy boundaries, which is the main thing an agent needs. Minor gaps remain around error behavior for a missing member, but the core is complete for a simple read tool.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema, including the member_id provenance. The description adds no syntax or format detail beyond that, 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+resource ('One member's profile in a group') and enumerates the fields returned, so an agent can distinguish it from list_members/search_members at a glance. Scope is precise: a single member within a named group.

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 'profile card when you click a member' framing, but the description gives no explicit when-to-use guidance or alternatives. It never says to call list_members/search_members first to obtain the member_id, leaving that routing to the schema.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: voters=true caps at 30 per answer, mirroring how vote counts render in the Skool UI, which sets expectations about truncation. It doesn't discuss rate limits or omission cases, keeping it at 4.

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 packed sentences, front-loaded with the primary return content and followed by the optional expansion. No filler; 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?

With no output schema, the description fully carries the return-shape burden: per-answer number, text, vote count, and the caller's own vote, plus the voters cap. Nothing an agent needs to call and interpret 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?

Schema coverage is 100% so baseline is 3; the description still adds meaning by explaining that the returned answer 'number' is the identifier vote_on_poll consumes, and by restating the 30-voter cap on the voters flag. That is real semantic value beyond the schema's terse boolean description.

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: answers and vote counts of a post's poll, with an explicit optional expansion (who voted for what). It also differentiates itself from the sibling mutation tool by naming vote_on_poll and explaining the link between answer numbers and that tool.

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?

Clear on when to enable the voters expansion and what it yields, and implicitly routes voting actions to vote_on_poll via the answer-number parenthetical. It stops short of an explicit 'use X instead when...' statement, so it's strong context rather than 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?

Goes well beyond the readOnly/idempotent annotations by disclosing real behavioral traits: attachments and files are omitted while in-text links survive, and comments are capped at 25 with replies nested. The 25-comment cap is exactly the kind of truncation limit an agent needs to know to avoid misreporting completeness.

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 lead line front-loads the essential scope and the remaining two sentences add return shape and a workflow link, all of which earn their place. There is mild redundancy between the headline sentence and 'Returns one post by post_id or slug', but nothing wasteful.

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

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

With no output schema, the description carries the full burden of describing return values and does so completely: fields returned, comment cap, nesting, and what is excluded. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented, including that post_id accepts a slug. The description restates 'post_id or slug' but adds no new format, validation, or default information, and says nothing about the 'group' parameter. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('One post with its full text and comments') and defines the returned shape precisely, including nested replies. An agent can tell this apart from list_posts or get_conversation without opening the schema, since it is explicitly the single-post-by-identifier retrieval.

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?

Makes the selection condition clear: retrieve one post by post_id or slug, with the identifier coming from list_posts (schema) and a follow-on path to comment_on_post using comment_id. It never explicitly says when NOT to use it (e.g., to browse many posts use list_posts), so it is clear context without exclusions.

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, openWorldHint=true, and idempotentHint=false, so the safety burden is partly covered; the description adds real context the annotations cannot, namely that an invitation email is actually sent externally, that existing group members are silently skipped, and that acceptance bypasses approval. It never explains why this is 'destructive' (are invites revocable? does it consume seats?) nor any rate limits, which matters for a 50-address batch.

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?

'Admins only' appears twice, wasting a sentence, and the phrase 'as Invite people, Invite by email does' is garbled and costs the reader a pass to parse. The useful scope statement (no membership request, external recipients) is present but not front-loaded ahead of the duplication.

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 should say what a batch call returns — per-address success, skipped-existing, or invalid — which is important when up to 50 emails are submitted at once. Permissions and side effects are covered adequately, but the outcome shape is left entirely to inference.

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 group, emails, and course_ids are already documented in the schema, including the 50-address cap and the course-id hint. The description adds no format or semantic detail beyond what the schema states, which is the expected baseline behavior.

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 (email an invitation to members) and pins down the distinguishing effect: recipients join directly without a membership request, which separates it from approve_membership_request. It also clarifies that the emails go to people outside the group, distinguishing it from send_message.

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?

'Admins only' sets a clear precondition, and 'whoever accepts joins without a membership request' tells the agent this is a pre-emptive path rather than a request-handling one. It never explicitly names a sibling tool as the alternative, so the routing is implied 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?

Annotations already flag it as a non-read-only, idempotent, non-destructive open-world mutation, and the description adds real context beyond that: the author gets a leaderboard point, Skool sends them a notification, rapid liking returns rate_limited, and the action is undone with one call. These are exactly the side effects and failure modes an agent needs before mutating state.

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

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

Four short sentences, each doing distinct work: purpose, inverse semantics, social side effects, rate limits, and reversibility. The purpose and the liked=false mechanic are front-loaded ahead of the caveats.

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

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

Covers the mutation's side effects, its rate-limit failure mode, and reversibility for a 3-parameter tool with no output schema and solid annotation coverage. It does not say what a successful response contains or how an already-liked target behaves, though idempotentHint partially covers the latter.

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

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

Schema description coverage is 100%, and the description restates the same facts the schema already carries ('liked false takes the like back', post_id doubling as comment_id) without adding syntax or format detail. 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 (like/unlike) and resource (post or comment), and the 'take the like back' phrasing covers the inverse operation explicitly. It is clearly separable from siblings like follow_post and vote_on_poll.

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 a clear condition for the inverse path ('liked false takes the like back') and states it 'runs without asking first', so the agent knows no confirmation is needed. It never names alternatives such as follow_post or vote_on_poll, so the routing guidance is implicit rather than explicit.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world profile for this listing tool. The description adds real value beyond them: the returned fields (name, who can post, sort order, post count), the ordering guarantee, and the exact value domains for who_can_post (members/admins) and sort (default, new, top_week, top_month, top_year).

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 blocks, front-loaded with the returned fields, then the enumeration meanings. No filler sentences; every clause carries information the schema does not.

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 response and does so adequately, including the sort field's value set and ordering. Minor gaps: no mention of auth/permission requirements or behavior for a nonexistent/invalid group.

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?

Only one parameter, and schema description coverage is 100% with an example ('yourgroup' for skool.com/yourgroup). The description adds nothing about the group argument itself, 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: 'Lists the categories a group's feed is split into, in the order the group shows them.' Clear enough to distinguish from create_category/update_category/delete_category by verb alone, and it names the returned fields. It does not explicitly route to those mutation siblings, so it stops short of the top score.

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 explicit 'use this when...' statement or named alternative. Usage is only implied by the note that 'create_post and update_post take the name,' which hints that this is a prerequisite lookup for creating or updating posts, but the agent must infer that.

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, so safety is covered. The description adds genuinely non-structured behavior: results span all groups, sort order is most-recent-first, and the pagination contract ('pass next_cursor back as cursor') is spelled out so the agent knows how to continue.

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 zero padding, front-loaded with the inbox framing and immediately followed by scope, sort order, the filter hint, and pagination. Every sentence 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?

With no output schema, the description correctly compensates by naming the returned fields and ordering, and it closes the pagination loop. Minor gaps remain (empty-inbox behavior, whether the total count is exposed), but an agent can call this correctly from what is given.

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

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

Schema coverage is 100%, so baseline is 3; each parameter is already documented, including the 1–30 limit cap. The description only restates the cursor round-trip and the unread_only purpose, adding little meaning beyond the schema.

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

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

States a concrete verb and resource — 'Lists your Skool Chat conversations across all groups' — plus ordering ('most recent first') and returned fields (other member, unread count, last message). This clearly separates it from the singular get_conversation sibling, though that sibling is never named 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?

The only usage steer is 'Set unread_only to see only what needs an answer,' which implies an inbox-triage workflow. There is no explicit statement of when to use this versus get_conversation, list_notifications, or search_members, and no exclusions or prerequisites.

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), so the description's extra context is the real value: result ordering, the open/locked 'unlock' semantics, the honest caveat that Skool doesn't reveal the lock reason, and the fact that locked courses list no modules. It doesn't mention auth requirements or behavior for an invalid group name.

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 purpose is front-loaded in the title sentence, followed by concrete details about ordering, lock status, and module links. The closing 'Use the module links in welcome messages' is slightly tangential but short enough not to bloat the definition.

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 has to describe what comes back, and for that it does well: courses in order, unlock status, modules with links for open courses only. It falls short of fully complete by omitting any error/invalid-group behavior, but the shape of the result is clear enough to call the tool 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?

With a single parameter at 100% schema coverage, the schema already documents 'group' with an example. The description only implies the group scoping through 'the group's Classroom' and adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

A specific verb and resource: it lists the courses of a group's Classroom, and it states the scope (open and locked courses, modules only for open ones). It doesn't explicitly name a sibling such as get_course or create_course, but the plural-list semantics separate it well enough in practice.

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: you use it to see a Classroom's courses. The one directive, 'Use the module links in welcome messages', tells the agent what to do with the output rather than when to pick this tool over get_course or list_lessons-style siblings. No exclusions or prerequisites are given.

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/openWorld, so the safety profile is covered. The description adds real behavioral value the annotations lack: recurring events appear once per date, month view semantics, and timezone handling. Only minor ambiguity is that 'start and end are UTC' appears to describe returned fields rather than the schema's two params, which is not a contradiction but slightly unclear.

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?

Front-loaded with scope and output summary, then the sibling routing. Two tight sentences plus an informative clause; the 'title, time, place and who can join' list earns its place by previewing the return shape absent an output schema.

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

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

With no output schema, the description usefully summarizes the returned fields and discloses recurring-event deduplication and timezone semantics. Nothing essential is missing for a simple two-param read tool, though pagination/limits and the exact meaning of the UTC note could be tighter.

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% — both 'group' and 'month' are documented with format and default — so the schema carries the parameter burden. The description reinforces month scoping ('in one month') but adds no format or syntax detail beyond the schema, matching the baseline 3.

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

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

States a specific verb and resource ('Events on a group's calendar') plus scope ('in one month') and even previews the returned fields. It explicitly distinguishes itself from get_event and create_event, so an agent can pick 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 two relevant alternatives and what each does ('get_event returns one event, create_event adds one'), which effectively routes the agent. It doesn't spell out exclusions (e.g., multi-month ranges, non-calendar event sources), so it stops short of a full when/when-not rubric.

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 safety (readOnly, idempotent, non-destructive), so the bar is lower; the description adds the non-obvious behavioral fact that entries are 1-based and ordered as the sidebar displays them, which is essential for downstream calls. It omits ordering stability and behavior when the group has no links, so it isn't exhaustive.

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, no filler, with the resource statement first and the numbering-consumer note second. The opening noun-phrase fragment is slightly clipped but still front-loads the key 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 one-parameter, read-only list tool with no output schema, the description supplies what an agent needs: what is listed, how it's ordered/numbered, and who consumes the number. Missing only minor details like empty-list behavior and whether numbering shifts as links change.

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 single 'group' parameter is documented with a concrete URL-name example, so the schema carries the load. The description only implies the group scoping via 'a group's sidebar' and adds no format or edge-case guidance 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?

The description names a specific verb and resource ('Lists the links the group shows in its sidebar under the description') rather than restating the title. It also clarifies that results are numbered from 1, which is the distinguishing characteristic versus other list_* tools. It stops short of 5 because it doesn't explicitly contrast with the nearest reading siblings (list_group_rules, list_categories).

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 closing sentence 'update_group_link and delete_group_link take the number' tells the agent exactly when this tool matters: as the prerequisite lookup for link-index-based mutations. That's clear workflow context, though it doesn't spell out 'call this before updating/deleting' or any exclusions explicitly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds a genuinely non-obvious behavioral fact: numbering starts at 1 and follows the group's display order, tying it directly to the sibling mutation tools.

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 definition is short and front-loaded, but the opening fragment ('The rules of a group, numbered as the group shows them') is fully subsumed by the sentence that follows, so the numbering point is stated twice. One sentence plus the sibling linkage would have been tighter.

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 one-parameter read tool with rich annotations and no output schema, the description supplies the crucial piece an agent cannot get elsewhere: the meaning and 1-based ordering of the returned rule numbers. It does not describe the returned fields, but the low complexity keeps that minor.

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?

There is a single parameter and schema description coverage is 100%, so the schema fully documents 'group' with an example. The description never mentions the parameter or its format, so it adds nothing 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 and resource ('Lists the group rules') and names the scope ('members agree to'). It also distinguishes itself from the mutating siblings by explaining that update_group_rule and delete_group_rule consume the numbers it returns, though the opening fragment largely restates the title.

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?

Makes the usage context clear: call this to obtain rule numbers that update_group_rule and delete_group_rule then take, which is exactly the lookup-then-mutate workflow an agent needs. It stops short of explicit when-not guidance or naming a distinct alternative for the same data.

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 read-only/idempotent/non-destructive, so the bar is lower; the description still adds real context: a hard cap of 50 results, the role vocabulary (admin/moderator/member/pending), and the caveat that a pending group shows no posts or members yet. It stops short of saying what happens past 50 groups (no cursor/offset described).

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

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

Front-loaded with what is returned and the cap, then field semantics, then the downstream usage hint. Slight redundancy between the lead fragment 'Skool groups of your account' and 'Returns up to 50 Skool groups of your account', but no sentence 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?

There is no output schema, and the description does document the meaningful returned fields (role, members count origin, price, pending state). The gap is that it tells the agent to pass 'group' to other tools without describing that identifier's form, which matters for chaining.

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?

Zero parameters, so the baseline of 4 applies; there is nothing parameter-level for the description to compensate for.

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: returns up to 50 Skool groups tied to the account, scoped to owned/joined/pending. It delineates scope well but never names the obvious siblings (get_group for one group, discover_groups for finding new ones), so the agent must infer the boundary.

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

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

It gives one concrete downstream instruction: 'Use group as the group parameter of the other tools,' which is genuinely useful routing. However there is no explicit when-to-use-this-vs-alternative guidance against discover_groups or get_group, so the choice 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 declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds useful context beyond that: the level set is fixed at 9, titles can be empty, and a per-level member share is returned — genuine added value without contradicting 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?

Front-loaded summary sentence followed by a field-by-field elaboration; every clause carries information. Slight redundancy between the lead line and the enumeration keeps it from a 5.

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

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

There is no output schema, and the description compensates by enumerating exactly what each returned level entry contains (number, Skool's name, admin title or empty, member share). An agent has everything needed to call and interpret it.

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

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

Only one parameter and schema coverage is 100%, with the schema itself explaining the group URL name format. The description adds no further parameter guidance, 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 ('Lists the 9 levels of the group's leaderboard') plus the exact fields returned, so an agent can distinguish it from get_leaderboard and rename_level 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?

Names the sibling alternative explicitly ('get_leaderboard ranks the members') and clarifies where points originate, which effectively routes ranking questions elsewhere. It stops short of an explicit 'use this when / not when' statement, so it lands just below the top band.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: fixed page size of 30, newest-approved-first ordering, cursor round-trip protocol, the per-tab semantics of status including that admins count as active, and the non-obvious caveat that joined_since filters only within the fetched page rather than the whole group. That last point is exactly the kind of trap disclosure that prevents wrong conclusions.

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?

Front-loaded with the resource and ordering, then the paging protocol, then per-parameter semantics — a sensible priority order. Dense but nearly every clause carries information; the one cost is a somewhat run-on middle section where the three sentences blend paging, status and role together.

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 carries the needed burden: it enumerates returned attributes, states page size and ordering, explains the pagination handshake, and covers both enum parameters and the page-scoped filter. An agent could call this correctly and interpret the results without further documentation.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: it clarifies that role=admin/moderator is applied server-side ('asks Skool for the admins only') and warns that joined_since is page-scoped, neither of which appears in the schema. It also disambiguates member_id (person-level, used by send_message/get_member) from membership_id (group-level, used by set_member_role/ban_member/remove_member), which are return identifiers rather than inputs but still resolve real ambiguity for follow-up calls.

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 with scope: 'Lists members of one group, newest approved first.' The return fields (role, level, points, join date) and the tab variants (banned, churned, cancelling) make the capability concrete. It never names the nearby sibling search_members, so an agent can't fully rule out the alternative without opening both 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?

Operational guidance is strong — pass next_cursor back as cursor, status selects the tab, role=admin/moderator restricts to admins — but that is how-to-use, not when-to-use-this-vs-something-else. No exclusion or routing against search_members or list_membership_requests, which are the obvious confusable siblings in a roster-listing 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?

Beyond the annotations, the description adds important behavioral details: only admins and moderators can see requests, unauthorized access returns APP_PERMISSION_DENIED, results are paginated 30 per page and ordered oldest first within the page, and applicant answers are included. These details materially help the agent understand permissions, failure behavior, and 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?

The description is front-loaded with the core purpose and includes useful operational details without excessive length. There is minor redundancy around 'Admins and moderators only' and 'Only admins and moderators see requests', but the structure remains 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 listing tool with no output schema, the description explains the returned data, pagination behavior, permission requirements, failure behavior, and the follow-up action for request IDs. An agent has enough information to call the tool correctly and interpret the 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 group, limit, and cursor are already documented in the schema. The description adds useful pagination context with '30 to a page' and 'oldest first', but it does not add parameter-level meaning 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?

The description states a specific verb and resource: pending requests to join a private group, including applicants' Membership Questions answers. It clearly distinguishes this from sibling tools like list_members, approve_membership_request, and decline_membership_request by focusing on pending join requests and admin/mod visibility.

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

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

It gives clear usage context: admins and moderators should use it, other accounts receive APP_PERMISSION_DENIED, and returned request_id values are meant for approve_membership_request or decline_membership_request. It does not explicitly contrast with every alternative listing tool, but the intended workflow is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real value: ordering (newest first), scope (all groups or one), the returned fields (type, line, post, link), and the crucial side-effect disclosure that reading does not mark notifications read. It stops short of describing pagination behavior or what happens when the cursor is exhausted.

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?

Front-loads the resource and ordering before the mechanics, and the second sentence carries the scope, return contents, and alternative routing. Slightly dense and repetitive ('newest first' appears twice), but no sentence 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 no output schema, the description usefully sketches the returned shape (type, display line, related post, link). Pagination details are left to the cursor parameter in the schema, so an agent knows enough to call and page correctly, though the response envelope itself remains implied.

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 group, limit, cursor, and unread_only. The description reinforces group ('all groups or one') and unread_only semantics but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (lists) and resource (notifications) with scope spelled out: this account's bell, newest first, all groups or one. It also enumerates the notification kinds returned, so an agent can tell it apart from siblings like list_posts or list_conversations 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?

Explicitly routes the agent: use unread_only to narrow to unread, and use mark_notifications_read to actually mark them read, with the clarifying note that this tool does not. The alternative is named along with the condition that selects it.

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

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

Annotations already cover readOnly, idempotent, and non-destructive semantics, so the description need not restate them. It adds real behavioral context beyond the annotations: ordering (newest first), a hard cap (up to 100), and the fact that the returned member_id plugs into other tools.

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 purpose. The phrase 'as the like count under it opens' is slightly awkward UI-flavored prose but still earns its place by conveying invocation context.

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 supplies the essentials: result ordering, result cap, and the key of the returned records. It does not mention pagination or what happens past 100 likes, which is a minor gap for a capped 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 group, limit, and post_id are already documented. The description only reinforces that post_id may be a comment id or a post id, which the schema also states, so it adds marginal meaning beyond structured data. Baseline 3 is appropriate.

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

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

The description states a specific verb (lists members) and resource (who liked a post or comment), with scope details: newest first, capped at 100. This clearly separates it from the write-side sibling like_post, though it never names the alternative 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?

It establishes the retrieval context ('as the like count under it opens') and gives downstream chaining guidance ('member_id is what send_message and get_member take'), which tells the agent what to do with the result. It lacks explicit when-not-to-use conditions or named alternatives.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so this description wisely adds behavior they don't: page size cap of 30, the pinned-then-newest ordering, the non-obvious pagination-plus-filter interaction, and that preview is truncated to 200 characters. That last detail prevents an agent from assuming it got the full post body.

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, each earning its place: the first states purpose and ordering, the second pagination and the filter caveat, the third the preview/get_post split. Front-loaded with the core purpose, no redundant restatement of the name or title.

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