KonbiniAPI MCP

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 only needs to add beyond that. It does: the fixed 12-items-per-page constraint is a genuine, non-obvious behavioral trait, and the paginated-with-cursor nature of the response is stated. Auth requirements and rate limits are not disclosed.

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, zero waste, front-loaded with the core action and page-size constraint before the optional payload-tuning parameters.

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

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

No output schema exists, but the description plus the item_fields enum give the agent a workable picture of the return payload, and the fixed page size plus cursor parameter make pagination clear. Only the response envelope's shape and any access constraints 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 description coverage is 100%, so the schema already documents cursor, audioId, and the three field-selection parameters in detail. The description's only addition is the rationale that projection_preset/data_fields/item_fields exist 'for payload reduction', which is mild extra value and does not help choose between presets.

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

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

States a specific verb+resource+scope: a paginated list of reels filtered by a given audio/music track. That scope distinguishes it from the sibling reels tools (instagram_get_user_reels, instagram_get_trending_reels), though it never names them 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 implied by the resource qualifier: use this when you have an audio/music track and want its reels. There is no explicit when-not guidance and no routing to the alternative reels endpoints, so the agent must infer the choice from the names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds behavioral context beyond annotations by naming the returned content (images and videos) and the payload-reduction mechanism (projection_preset, data_fields, item_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?

Three tightly written sentences with the core purpose front-loaded, followed by the ID provenance and payload-reduction note. No filler or repetition.

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

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

For a read-only tool with full schema coverage and annotations covering safety, the description need only summarize return content and usage prerequisites. It does both, and no output schema exists so nothing further is required. Minor omission: no mention of pagination or limits, though none are indicated.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the enum values for projection_preset and field arrays. The description only adds a high-level note that these options exist for payload reduction, which is marginal added meaning 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?

Specific verb and resource: 'Returns all story items within a highlight reel.' It distinguishes itself from sibling instagram_get_user_highlights by clarifying that the highlight ID comes from the highlights list endpoint, so an agent knows this tool operates on an individual reel rather than listing highlights.

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 names the source for the required highlightId ('from the highlights list endpoint'), which is a clear prerequisite and implicitly routes the agent to the correct sibling for obtaining IDs. It does not state explicit when-not conditions, but the context 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 establish the safe-read profile (readOnly, idempotent, non-destructive, openWorld), so the description's additional disclosure of the ~15-post single-page platform cap and the numeric Facebook Places ID format is genuinely additive. It stops short of noting auth requirements or how the location ID is obtained.

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 the core purpose front-loaded, followed by the page-size limit and the payload-reduction options. No filler or restatement of the title.

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

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

With no output schema, the description usefully covers the return shape indirectly (about 15 posts, single page) and the field-selection mechanics. It is close to complete for a six-parameter read tool, with only the origin of the location ID and any auth expectations left unstated.

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 baseline is 3, but the description adds real meaning: projection_preset, data_fields, and item_fields are framed as payload-reduction controls and locationId is characterized as a numeric Facebook Places ID. That clarifies intent beyond the schema's terse field descriptions.

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 posts tagged at a location, which no sibling covers (the nearest, instagram_get_user_tagged, is user-scoped rather than place-scoped). The one-line scope sentence makes the resource unambiguous, though it never explicitly names a sibling to distinguish itself from.

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

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

Usage is implied by the purpose statement rather than spelled out; there is no when-to-use/when-not or alternative routing. It does add a practical constraint (single page only, ~15 posts due to platform limit) that steers the agent away from expecting heavy pagination, which is more than nothing but not explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses media types supported (photos, videos, carousels) and that projection_preset/data_fields exist to reduce payload size, which is useful for an agent managing response size.

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

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

Three tight sentences, front-loaded with the core purpose before the supporting media-type and payload-reduction details. No filler or redundancy.

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

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

With no output schema available, the description carries the burden of describing return content and does so by naming media, captions, and engagement counts. It is nearly complete, though it could mention whether the response is a single object and note the default projection behavior more prominently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly further by explaining the intent of projection_preset and data_fields — payload reduction — which the schema only describes mechanically ('Add top-level data keys on top of the selected projection_preset').

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 details for a single post by its shortcode', then enumerates the content (media, captions, engagement counts). This cleanly separates it from siblings like instagram_get_post_comments or instagram_get_user_posts, which operate on collections or comments rather than a single 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?

The description implies usage by naming the shortcode as the lookup key, but it offers no explicit when-to-use guidance or named alternatives. An agent must infer that comments, user posts, and reels have their own dedicated tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the fixed page size of 15 imposed by the platform, the fact that only top-level comments are returned, and the projection controls for payload reduction. It stops short of describing rate limits or failure modes.

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

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

Three sentences, front-loaded with the core purpose before the pagination constraint and the projection controls. Every sentence carries information, though the page-size detail partially duplicates the count parameter's schema 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?

With no output schema, the description correctly enumerates the returned fields (comment text, author info, like counts, timestamps) and covers pagination behavior and payload shaping. For a read-only 6-parameter tool this is nearly complete, lacking only guidance on when this tool is preferable to adjacent comment tools.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents cursor, postId, count and the projection parameters in detail. The description adds value by explaining the intent of projection_preset/data_fields/item_fields (payload reduction) and restating the platform-imposed page size, which clarifies why count is effectively fixed.

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?

"Returns top-level comments on an Instagram post" states a specific verb (returns) and resource (top-level comments) plus the scoping qualifier "top-level," which distinguishes it from reply-fetching siblings like tiktok_get_comment_replies and reddit_get_comment_replies. It does not explicitly name a sibling it is meant to be used instead of, so it falls just 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?

There is no when-to-use statement, no prerequisites (e.g., that postId must be a shortcode), and no exclusions or alternatives named among the many comment-related siblings. The only hint of usage context is the schema-level note about omitting cursor for the first page, which is not 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that results arrive in paginated batches, which is useful context, but it says nothing about rate limits, auth requirements, or feed freshness beyond what the annotations and schema already imply.

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

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

Two sentences, no filler, with the core resource stated first and the payload-reduction capability second. Nothing is padded 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 zero-required-parameter read tool with full schema coverage and rich annotations, the description is largely sufficient, and the absence of an output schema is mitigated by the item_fields enum documenting the return shape. The one real gap is that the projection presets (full/minimal/identity/engagement/content) are never characterized, which matters when the default is 'minimal'.

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

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

Schema description coverage is 100%, so the baseline is 3. The description merely lists projection_preset, data_fields and item_fields as existing for 'payload reduction' without explaining what any preset contains or how the additive fields interact with a preset — no 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 specific verb ('Returns') and resource ('paginated batch of reels') and pins the source to Instagram's public trending reels feed, which distinguishes it from instagram_get_user_reels and instagram_get_audio_reels. It never names a sibling explicitly, so an agent must infer the distinction from the source phrase rather than being told.

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

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

There is no when-to-use or when-not-to-use guidance. The description says what the feed is but never contrasts it with instagram_search_popular, instagram_get_user_reels, or instagram_search_media, leaving the agent to guess which entry point fits a given request.

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, and destructiveHint false, so the safety profile is covered. The description adds useful context about public-only access and payload reduction, but does not disclose rate limits, auth requirements, or any edge-case behavior. Given the annotations, this is adequate but not rich.

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

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

Three compact sentences front-load the core purpose, then cover lookup alternatives and payload reduction. Every sentence earns its place with no redundant filler or repetition of schema details.

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

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

For a simple read-only profile lookup with a rich schema and comprehensive safety annotations, the description provides enough: output contents, public-scope caveat, lookup modes, and payload options. With no output schema, a slightly more explicit return-format note would make it fully complete, but the current summary is sufficient for correct 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 all four parameters in detail. The description adds a little value by framing projection_preset and data_fields as payload reduction and by mentioning the numeric-ID shortcut, but it does not meaningfully compensate or extend beyond the schema.

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

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

The description states a specific verb and resource: 'Returns profile information for an Instagram user.' It names concrete output content (bio, follower counts, profile picture, account metadata) and clarifies it covers any public account. This clearly differentiates it from sibling tools focused on posts, reels, tagged content, and highlights.

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

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

The description gives clear lookup context: use a username, or pass userId for a numeric ID lookup, and optionally reduce payload with projection_preset/data_fields. It does not explicitly name sibling alternatives or state when not to use this tool, but the single-purpose profile resource makes the intended use obvious.

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 the safety profile is fully covered. The description adds that it returns a list and supports projection presets for payload reduction, but does not disclose pagination behavior, rate limits, or authentication needs. A 3 is appropriate given the annotations carry the behavioral burden.

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

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

Two sentences with zero waste. The primary purpose is front-loaded, followed immediately by the routing alternative and a brief note on payload reduction options.

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

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

No output schema exists, but the description states what is returned (list of story highlight reels), and annotations fully cover the read-only safety profile. The input schema handles parameter details and pagination cursor, so nothing critical is missing for correct 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining that projection_preset, data_fields, and item_fields exist for payload reduction, which clarifies their purpose rather than just restating them.

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 (returns) and resource (list of story highlight reels on a user's profile). Distinguishes itself from the sibling instagram_get_highlight_stories by explicitly naming that alternative for individual stories within a highlight.

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 names the alternative endpoint (highlight endpoint) and the condition under which to use it (to get individual stories within a highlight). This leaves no ambiguity about when to use this tool versus the sibling.

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 destructive=false, so the bar is lower. The description still adds real context beyond them: a 12-post page ceiling, the content types returned (photos, videos, carousels), and engagement counts. It omits auth requirements and rate limits.

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

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

Three tight sentences, front-loaded with the purpose and pagination limit. The trailing sentence enumerating the projection parameters adds little but is short enough not to be wasteful.

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

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

No output schema exists, so the description carries the return-value burden; it covers pagination, page size, and included media types reasonably well. It stops short of describing the response envelope shape or cursor lifecycle, but is usable as-is.

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 parameters are already documented (count max, cursor nextCursor, username @ handling). The description only names projection_preset/data_fields/item_fields as payload-reduction knobs without adding semantics beyond the schema. 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: 'Returns a paginated list of posts from an Instagram user's profile feed.' The 'profile feed' scoping implicitly separates it from instagram_get_user_reels and instagram_get_user_tagged, but no sibling is 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?

Usage is only implied through scope ('user's profile feed'); there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance despite many overlapping siblings like instagram_get_user_highlights and instagram_get_user_tagged.

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, open-world, non-destructive), and the description adds genuinely useful behavior: newest-first ordering, an 8-per-page cap, pagination, and the return contents (video URLs, captions, engagement counts). It stops short of noting rate limits or how many pages are practically retrievable, but goes well beyond what the annotations provide.

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

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

Four short sentences, front-loaded with purpose, then behavior, then return contents, then the payload-reduction option. No sentence is redundant with another and nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the included fields and the projection mechanism. A brief note on pagination termination (when nextCursor is absent) would close the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining the shared purpose of the three projection parameters ('for payload reduction') and confirming the per-page cap that constrains count, adding intent the enum lists alone do not convey.

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 a paginated list of reels from an Instagram user's profile"), which cleanly separates it from instagram_get_user_posts and instagram_get_user_highlights. It does not explicitly name the closer siblings it could be confused with, such as instagram_get_audio_reels or instagram_get_trending_reels, but the scope ('from a user's profile') makes the distinction inferable.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative tool is named. The 'newest first' and '8 per page' details describe behavior, not selection criteria, so an agent gets no help choosing between this and the audio/trending reels siblings.

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 genuinely useful behavior beyond that: a 12-post page cap, pagination via nextCursor (schema), and the payload-reduction knobs, though it omits rate limits or ordering.

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

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

Three sentences, front-loaded with the core behavior, then pagination limit, then payload controls. No filler, though the third sentence is largely a restatement of schema parameters.

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

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

No output schema, but the description says what is returned (full post details and engagement counts) and covers the page cap and pagination. For a read-only paginated listing with 100% schema coverage, this is nearly complete, with only ordering/rate-limit details 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 the schema already documents count, cursor, username, and the field selectors. The description restates the projection/data_fields/item_fields purpose for payload reduction without adding syntax or selection guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource plus a distinguishing scope: posts where the user was tagged by other accounts, which cleanly separates it from instagram_get_user_posts (own posts) and instagram_get_user_reels among the many siblings.

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

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

The scope wording implies when to reach for it (tagged-by-others rather than authored content), but there is no explicit when-to-use/when-not or named alternative such as instagram_get_user_posts. Usage is inferable 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuine behavioral context beyond that: a hard cap of 24 results per page and the caveat that valid keywords may return empty because results are trending-driven, not exhaustive. Pagination via cursor is left implicit, 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?

Three sentences, front-loaded with the core purpose and the result cap, followed by the empty-result caveat and payload-reduction note. Every sentence carries information, though the payload-reduction line is somewhat incidental.

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 six-parameter search tool with no output schema, the description covers result limits, the surprise-empty-result behavior, and the projection options, which is close to what an agent needs. No output schema means return values needn't be explained, but cursor-based pagination behavior is only 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 description coverage is 100%, so the schema already documents all six parameters, establishing a baseline of 3. The description adds only marginal meaning by explaining that projection_preset, data_fields, and item_fields exist for payload reduction, without adding format or syntax detail beyond the schema.

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

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

The description states a specific verb (Searches) and resource (Instagram trending reels and videos) scoped by keyword, so the agent can tell it apart from getter-style siblings like instagram_get_trending_reels. It does not, however, explicitly name the nearest alternatives (instagram_search_popular, instagram_get_trending_reels), so it falls 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?

It gives useful context that some keyword searches return nothing because this surfaces trending content rather than full-text search, setting expectations about success. But it provides no when-to-use/when-not framing against the nearby search or trending siblings, leaving the routing decision to inference.

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

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

Adds real behavior beyond the annotations: fixed batch of 12 posts per page, cursor-based pagination, and the important warning that coverage varies by keyword (some results return posts, description, related terms, or none). Annotations already cover read-only/idempotent/open-world safety, so this variable-coverage disclosure is the genuinely useful addition.

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

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

Three sentences, front-loaded with what the tool returns, and every sentence carries useful information (coverage caveat, batch size, projection support). Slightly dense but nothing is 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?

Given 100% schema coverage, safety annotations, and no output schema, the description supplies what an agent needs: pagination model, fixed page size, unpredictable coverage, and payload-reduction options. It stops short of describing the shape of returned post objects, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including cursor and the projection fields. The description only names projection_preset, data_fields, and item_fields 'for payload reduction,' adding minimal semantics beyond the schema, 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: 'Returns a paginated batch of posts matching a keyword' plus the topic description and related sub-topics. It clearly scopes what comes back, but it never contrasts itself with the obvious sibling instagram_search_media (or the other get_* tools), so an agent has to infer which search tool to pick.

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?

'Not an exact-topic lookup' implies when this is and isn't appropriate, which nudges the agent away from using it as a precise topic matcher. However, no alternative tool is named and no explicit when-to-use trigger is given, so usage is only implied rather than directed.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds that it returns 'public information' and supports 'payload reduction' via projection_preset and data_fields. It does not contradict annotations, and adds incremental value by stating the read-only nature and customization options, though it could mention rate limits or that data is cached.

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

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

The description is extremely concise, one sentence that states the core purpose, lists included data fields, and mentions the two customization parameters. Every word earns its place, and there is no fluff or repetition.

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

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

Given that it is a simple read operation with annotations covering safety, the description is nearly complete. It explains what is returned and how to reduce payload, but does not specify the output format (e.g., JSON structure) or error cases. However, since there is no output schema, a brief note on return structure could have improved it, but it remains adequate for an agent to call 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 descriptions for company ('Company vanity name') and optional projection_preset/data_fields. The description adds no new parameter details beyond what 'payload reduction' implies, but the schema already provides sufficient documentation. Since coverage is high, a baseline of 3 is appropriate; the description does not introduce any confusing or missing semantics.

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

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

The description clearly states the tool returns public information for a LinkedIn company page, listing specific fields (description, location, employee count, logo). It is distinct from siblings like linkedin_get_company_posts, which focus on posts rather than page details. The purpose is unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternativestons. However, the context of retrieving company page information is inherently clear, and the sibling list shows obvious distinctions like company_posts for post feeds. There is no exclusions or alternatives specified, but the use case is straightforward enough to imply when to use.

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, openWorld, idempotent, and destructive hints. The description adds useful behavioral context beyond that: newest-first ordering, cursor-based pagination, and the payload-reduction purpose of projection/data/item 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?

Two sentences, front-loaded with the primary action and result ordering, followed by pagination and projection controls. Every phrase carries information and there is no repetition.

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

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

For a read-only five-parameter list tool with no output schema, the description covers return content, ordering, pagination, and response-size controls. Nothing essential for correct invocation appears to be 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 the schema already documents all five parameters. The description only names the projection-related parameters and adds 'payload reduction,' without adding syntax, defaults, or usage details beyond the schema.

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

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

The description states a specific verb and resource: 'Returns recent posts from a LinkedIn company page.' It distinguishes company posts from sibling tools like linkedin_get_company and linkedin_get_user_posts by naming the resource and scope.

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

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

There is no explicit when-to-use, when-not, or alternative-tool guidance. The cursor instruction is operational, not selection guidance, and no sibling LinkedIn retrieval tools are referenced.

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 genuinely useful context beyond that: results are public-only and comments are truncated to ~5 inline items, which prevents an agent from assuming a complete comment set.

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

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

Two sentences, zero filler, and the returned-content summary is front-loaded ahead of the optional parameter note.

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 returns and does so adequately (author, engagement counts, comments). It could say more about what projection presets yield or whether counts are approximate, but for a simple 3-parameter read tool this is close to sufficient.

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 postId formats, the data_fields enum, and the projection_preset default. The description only adds the rationale ('for payload reduction') for the two payload-shaping params, which is marginal value over the structured data.

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 (Returns) and resource (public LinkedIn post) plus the payload contents: author, engagement counts, and up to ~5 inline comments. The 'up to ~5 inline comments' detail distinguishes it from sibling comment tools like linkedin_get_post_comments, though it doesn't name any 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as linkedin_get_post_transcript or linkedin_get_user_posts. The word 'public' hints at an availability constraint but never states the exclusion condition 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 a safe, idempotent, read-only open-world read. The description adds genuinely useful behavior beyond that: the 404 condition when there is no video or no captions, and the availability of payload-reduction options. It stops short of describing rate limits or auth requirements.

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

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

Three tight sentences, zero filler, with the capability, the failure condition, and the optional parameters presented in a logical, front-loaded order. Every sentence earns its place.

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

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

With no output schema, the description names the returned content (caption/transcript) but does not describe the response shape or field structure. For a single-purpose read tool with fully documented params and clear annotations, this is nearly complete, with only the return format 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 description coverage is 100%, so the baseline is 3. The description adds a rationale the schema lacks by stating that projection_preset and data_fields exist for payload reduction, which tells the agent why it would set them. It does not elaborate on the enum values, 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?

States a specific verb and resource (returns caption/transcript for a video post) and scopes it precisely to captioned video posts. This is clearly distinct from sibling linkedin_get_post, which fetches the post itself; an agent can pick between them 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?

Gives clear usage context: applicable only when the post carries captions, with a stated failure mode (404 if no video or captions). It does not name an explicit alternative (e.g., linkedin_get_post) for posts without captions, so it falls short of a full when/when-not routing statement.

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 openWorld, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond annotations: restricted fields are omitted, so the agent knows results may be incomplete. It stops short of explaining error/not-found 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?

Three short sentences, front-loaded with the return payload before the caveat and the optional params. Nothing redundant; each sentence carries distinct 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 competently enumerates the return shape (headline, location, job titles, school/employer names) plus the restricted-field caveat. It omits edge behavior such as invalid/unknown username handling, but is otherwise sufficient for a 3-param 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 the baseline would be 3. The description adds rationale beyond the schema by explaining that projection_preset and data_fields exist 'for payload reduction', giving the agent a reason to use them rather than just their definitions.

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 profile information for a public LinkedIn member') and enumerates the actual returned fields (headline, location, job titles, school/employer names). An agent can tell this apart from linkedin_get_user_posts or linkedin_get_user_articles, which return content rather than the profile itself.

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 name and purpose (fetch a member's profile), and the 'public LinkedIn member' phrasing is a useful scope hint. However, there is no explicit when-to-use/when-not guidance or routing to sibling tools like linkedin_get_user_posts, leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the endpoint is not paginated and returns all available items in one response, and the projection parameters exist for payload reduction. It does not describe error cases or rate limits.

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

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

Three sentences, front-loaded with the core purpose, then the pagination trait, then the projection knobs. No filler, though the last sentence largely restates functionality the schema already exposes.

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

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

No output schema exists, but the description conveys the response shape indirectly by stating everything is returned in one unpaginated response and that payload size is controllable via projections. Missing only a brief note on what an item represents or error behavior.

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

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

Schema description coverage is 100%, so the schema already documents username and the projection/data_fields/item_fields parameters in detail, including the 'minimal' default. The description names the reduction parameters and their purpose but adds no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: returns a public LinkedIn member's published articles. The 'articles' vs 'posts' distinction implicitly separates it from linkedin_get_user_posts, though no sibling is named. An agent can identify the resource 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?

There is no explicit when-to-use guidance or mention of alternatives such as linkedin_get_user_posts or linkedin_get_user. Usage is only implied by the tool name and the statement that the endpoint is unpaginated.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: the endpoint is not paginated and returns everything available in one response, plus it notes the public-data access constraint. No contradiction with annotations.

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

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

Three sentences with no filler: purpose first, then the key pagination behavior, then the optional payload-reduction parameters. Every sentence earns its place and the most important facts are 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 read-only tool with fully described parameters and rich enum values for item_fields, the description is nearly complete. It lacks an explicit description of the response envelope beyond 'single response', but the schema fields and item_fields already reveal the expected output shape.

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 extra value by framing projection_preset, data_fields, and item_fields as payload-reduction controls, giving the agent a reason to use them beyond the raw schema descriptions.

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

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

The description uses a specific verb ('Returns') and a precise resource ('a public LinkedIn member's recent posts and shares'). It clearly distinguishes from sibling tools such as linkedin_get_user and linkedin_get_user_articles without requiring schema inspection.

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 context: use this when you need a public member's recent posts and shares, and expect a single non-paginated response. It does not explicitly name alternatives or state when not to use it, so it stops short of 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about what the payload contains (author info, scores, reply presence, media) but says nothing about rate limits, projection side-effects, or failure modes when the comment is deleted/private.

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

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

Two sentences, front-loaded with what is returned and followed by the payload-shaping options. No redundant restatement of the name or title, though the second sentence is terse enough that it could have been folded in.

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?

Read-only annotations cover the safety profile and the schema fully documents parameters, so the description's remaining job is to hint at return value. It does so lightly (author info, scores, reply presence, media), which is adequate given there is no output schema, though the projection presets' actual output shape is left unexplained.

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 postId, commentId, data_fields, and projection_preset, including the enum and default. The description adds only a brief rationale for projection_preset/data_fields ('for payload reduction'), which is marginal beyond what the schema states. 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 a public Reddit comment') and enumerates included data (author info, scores, reply presence, media). It is clearly distinct from a generic list tool, but it never names the obvious siblings (reddit_get_comment_replies, reddit_get_post_comments) to draw the boundary 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 description gives no when-to-use or when-not-to-use guidance. With siblings like reddit_get_comment_replies and reddit_get_comments_batch, an agent must guess whether this single-comment fetch is the right choice versus the batch or replies variants.

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 genuinely new behavior: cursor-based pagination (omit cursor for first page) and the projection/field controls used for payload reduction, which is meaningful for an agent planning calls.

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 tight sentences: purpose and pagination model first, reduction controls second. No filler, nothing repeated from the name/title, and the most decision-relevant information is front-loaded.

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

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

For a read-only, 7-parameter tool with no output schema, the description covers what is fetched, the pagination contract, and the payload-shaping options — enough to invoke it correctly. The remaining gap is the lack of explicit differentiation from sibling comment-retrieval tools.

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

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

Schema description coverage is 100%, with per-parameter docs including count default/max, cursor semantics, ID formats, and preset/field enums. The description only restates the presence of projection_preset, data_fields and item_fields, adding no syntax or constraint detail 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: returns direct replies to a Reddit comment, and adds the pagination model. It is clearly distinguishable from reddit_get_comment (a single comment) and reddit_get_post_comments (top-level post comments), though it never names those siblings explicitly.

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

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

Usage is implied by 'direct replies to a Reddit comment' — an agent can infer this is for expanding a comment thread rather than reading a post's comment list. But there is no explicit when-to-use, when-not-to-use, or named alternative, so the routing is left to inference.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, so the safety bar is low. The description usefully adds a billing behavior ('Costs 1 credit per ID submitted') and mentions payload-reduction controls, which are not captured by the structured annotations.

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

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

Two sentences, front-loaded with the core batch action, followed by cost and payload-shaping information. No wasted words or repetition of schema details.

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 batch read tool with no output schema and fully documented parameters, the description covers purpose, batch limit, credit cost, and payload controls. It does not state behavior for missing or invalid IDs, but that is a minor gap for this tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents entityIds, data_fields, and projection_preset. The description adds only that projection_preset and data_fields exist 'for payload reduction,' a slight contextual addition over the schema's own text, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Returns up to 100 Reddit comments by ID'), and the 'in a single request' scope distinguishes it from the single-comment sibling reddit_get_comment. An agent can tell it is a batch-by-ID retrieval without opening the schema.

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

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

The phrase 'by ID in a single request' implies this is for fetching multiple comments at once, but it never names an alternative (e.g., reddit_get_comment for one ID) or states when not to use it. Usage is implied 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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds useful payload-reduction context (projection_preset/data_fields/item_fields), but omits pagination behavior via cursor, the count cap, and the fact that the projection defaults to a reduced 'minimal' payload.

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 tight sentences: purpose first, capability second. No filler, no restatement of the title, and the scope-limiting qualifier is front-loaded.

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

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

For a seven-parameter list tool with full schema coverage and annotations but no output schema, the description covers purpose and the projection feature. It leaves pagination flow (cursor round-tripping) and the default minimal projection to the schema, which is acceptable but slightly short of 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 coverage is 100%, so the schema already documents all seven parameters including enums, defaults, and the cursor's nextCursor origin. The description only gestures at the three projection controls without adding semantics (e.g., how data_fields vs item_fields differ from a preset). 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 (returns posts) plus the exact scope ('top-level Reddit feed') and enumerates the feed kinds, which implicitly separates it from subreddit- or user-scoped siblings. It never names an alternative tool (e.g., reddit_get_subreddit_posts), so the differentiation is left to inference.

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

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

The description says what the tool returns but gives no when-to-use guidance, no prerequisites, and no indication of when to prefer it over reddit_get_subreddit_posts, reddit_search_posts, or reddit_get_posts_batch. The projection prose describes capability, not selection criteria.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. Beyond that, the description adds genuinely useful context with no output schema present: it lists what the response contains (title, body, author, engagement counts, attachments) and notes that payload size can be controlled. It stops short of noting behavior for deleted, private, or quarantined posts.

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 tight sentences: the first establishes what is returned, the second covers payload control. Nothing is redundant with the title, and the primary capability is front-loaded.

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

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

With no output schema, the description carries the burden of describing return content and does so adequately, and the single required parameter is covered by the schema. An agent still lacks error/edge-case behavior for inaccessible posts, which keeps this from a 5.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the enum values for projection_preset and data_fields. The description only echoes that these two knobs exist 'for payload reduction' without explaining preset differences or the 'minimal' default, so the baseline of 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 and resource ('Returns a public Reddit post') and enumerates the payload contents, so an agent immediately knows this is a single-post fetch. It does not, however, explicitly distinguish itself from close siblings like reddit_get_posts_batch, reddit_get_post_comments, or reddit_get_post_duplicates, leaving the singular-vs-batch distinction to the name alone.

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

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

Usage is only implied: the tool fetches one post given an ID. There is no statement of when to prefer it over reddit_get_posts_batch or reddit_search_posts, nor any prerequisite or failure conditions. The only guidance offered concerns payload reduction via projection_preset/data_fields, which is parameter-level rather than tool-selection guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely non-obvious behavior: cursor pagination, that `new`/`old` are exact across pages while `best`/`top`/`controversial` degrade to oldest-first on later pages, and that deleted comments can shorten a page below `count`. This is exactly the kind of subtlety an agent could not infer from 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?

Four sentences, return value front-loaded, each sentence carrying a distinct, non-redundant behavioral fact. No filler or restatement of the title.

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

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

For a read-only, fully documented-schema tool with no output schema, the description covers pagination, ordering and payload reduction well. It could say a bit more about what a comment item contains by default, but that gap is modest given the projection options are enumerated in the schema.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the enum list by explaining the cross-page semantics of specific `order` values and naming projection_preset/data_fields/item_fields for payload reduction. It omits `qa` and does not elaborate on `cursor`/`count`, so it stays just above baseline.

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

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

States a specific verb and resource with scope qualifier: 'Returns top-level comments on a Reddit post.' The 'top-level' qualifier distinguishes it from sibling reddit_get_comment_replies and reddit_get_comment, so an agent can route 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?

Usage is only implied through the pagination and ordering caveats; there is no explicit 'use this when / use X instead when' routing against siblings like reddit_get_comments_batch or reddit_search_comments. Adequate but leaves alternative selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and access profile is fully covered by structured data. The description's only additional behavioral content is that the result set is reduced by the projection parameters; it says nothing about pagination, rate limits, or result volume beyond what the schema implies.

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 tight sentences with the core purpose front-loaded and no filler. The second sentence lists three parameter names that are already documented in the schema, which is slightly redundant, keeping 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?

With no output schema, the description carries the burden of describing return shape; it does state that duplicates and crossposts are returned, but omits that results are paginated via count/cursor/nextCursor and how the projection presets shape the payload. Adequate but leaves real gaps for a 6-parameter paginated retrieval 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%, with count, cursor, postId, and the three projection parameters all documented in the schema itself, so the baseline is 3. The description's mention of projection_preset, data_fields, and item_fields adds only the framing 'for payload reduction', which is marginally useful but largely restates 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 ('Returns duplicate submissions and crossposts associated with a Reddit post'), which clearly distinguishes it from siblings like reddit_get_post, reddit_get_post_comments, and reddit_get_posts_batch. An agent can tell what unique data this tool yields 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?

No explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The reader must infer that this is used when deduplicating or finding reposts of a known post ID, but nothing in the text states that intent or warns when another tool (e.g. reddit_get_post) is more appropriate.

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, covering the safety profile. The description adds genuinely new behavioral context: the 1-credit-per-ID cost model and that projection_preset/data_fields exist for payload reduction, which an agent can't infer 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?

Three tight sentences with zero filler; the core capability, cost model, and reduction options are all front-loaded and each sentence carries distinct 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?

No output schema exists, yet the description adequately conveys the return (Reddit posts), the batch cap, the cost, and payload controls. Only the routing against the single-post and search siblings is 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%, so the baseline is 3, but the description goes further by explaining the intent of projection_preset and data_fields ('for payload reduction') rather than merely listing them, adding meaning about why an agent would set them.

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

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

States a specific verb+resource+scope: returns Reddit posts by ID, up to 100, in one request. The 'batch' scope distinguishes it from the single-post reddit_get_post sibling, though it never names that 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?

Usage is implied by 'in a single request' and 'up to 100 ids', and the credit cost hints this is for bulk retrieval, but there is no explicit guidance on when to prefer this over looping reddit_get_post or using reddit_search_posts.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds useful context that this returns only public metadata and that projection_preset/data_fields reduce payload, but it discloses no auth needs, rate limits, or default-preset behavior beyond the schema.

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

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

Two tightly written sentences with the return scope front-loaded and the payload-reduction feature second. Every sentence earns its place with no 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?

With no output schema, the description carries the burden of describing return content and does so by listing the key metadata fields. Combined with annotations and full schema coverage this is sufficient, though it could note the default payload shape given minimal is the default preset.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the enum values and defaults. The description's mention of projection_preset and data_fields for payload reduction adds intent but no syntax or semantics beyond what the schema provides, 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 public subreddit metadata") and enumerates the returned fields. This clearly distinguishes it from sibling subreddit tools that return posts, comments, rules, sticky, or wiki content.

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 never says when to use this tool versus alternatives such as reddit_search_subreddits, reddit_get_subreddits_batch, or the various reddit_get_subreddit_* endpoints. It only lists what is returned and which payload-tuning params exist, leaving selection entirely to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is fully covered there. The description adds that comments are public and that payload-reduction presets exist, but says nothing about pagination limits, rate limits, or auth requirements beyond what annotations imply.

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

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

Three short sentences, front-loaded with the core purpose before the option enumeration, with no filler. The ordering and time-window sentence largely duplicates enum information available in the schema, which is the only mild 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 an 8-parameter read tool with full schema coverage and safety annotations, the description covers purpose, sort options, time windows, and payload-reduction controls. Pagination (cursor) and the missing output schema are the only items an agent might want more on, and the cursor parameter is self-documented in the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (count cap of 100, cursor semantics, enum values, projection presets). The description only restates that ordering, time windows, and projection fields are supported, adding no syntax or constraint detail beyond the schema.

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

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

The description states a clear verb+resource ('Returns public comments from a subreddit'), so an agent knows exactly what it retrieves. It does not, however, distinguish this tool from close siblings such as reddit_get_comments_batch or reddit_search_subreddit_comments, which retrieve similar data under different conditions.

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

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

The description implies usage by listing supported sort orders and time-window behavior, which tells the agent when certain options apply. But it never states when to prefer this tool over the batch or subreddit-search siblings, leaving the key selection decision to inference.

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

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

Annotations already carry readOnly, idempotent, openWorld, and non-destructive hints, so the safety profile is covered. The description adds useful constraints, namely that time windows apply only to top/controversial, and notes payload reduction, but it omits pagination/rate-limit behavior and what a page contains.

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

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

Three sentences, front-loaded with the core action and no filler. Every sentence carries a distinct point (what it returns, ordering options, payload reduction), though the third sentence slightly crowds in three parameter names.

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 a full schema and rich annotations, the description covers purpose and the notable ordering constraints. There is no output schema and the description appropriately does not attempt return-format detail, though pagination semantics are left entirely to the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented, which sets a baseline of 3. The description's mentions of projection_preset, data_fields, item_fields and the top/controversial time-window rule largely restate what the schema already says, adding no syntax or format detail beyond it.

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 (Returns) and resource (public posts from a subreddit), which cleanly separates it from reddit_get_post and reddit_get_subreddit. However it never names or contrasts the closest siblings, reddit_search_subreddit_posts and reddit_get_feed, 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?

The description explains ordering and time-window capability but gives no when-to-use guidance versus reddit_search_subreddit_posts, reddit_get_feed, or reddit_get_posts_batch. No prerequisites or exclusions are stated, leaving selection entirely to inference.

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

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

Annotations already cover read-only and idempotent behavior, so the description does not need to restate those. It adds useful context about returning structured rules and supporting payload reduction, but does not disclose additional behavioral details such as output shape or any limitations.

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 core purpose and followed by a concise mention of relevant parameters. Every word earns its place, and there is no redundant restatement of the tool name or title.

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

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

For a simple read-only tool with one required parameter and fully documented optional parameters, the description is largely complete. The only minor gap is the absence of an output shape description, especially since no output schema is provided, though 'structured community rules' and the field enums give a reasonable picture.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the subreddit prefix rule, projection presets, and field arrays. The description adds modest value by noting that projection_preset, data_fields, and item_fields serve payload reduction, but it does not explain parameter semantics beyond that.

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

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

The description uses a specific verb and resource: 'Returns structured community rules for a subreddit.' This clearly identifies what the tool does and distinguishes it from sibling Reddit tools like post, comment, or sticky retrieval without requiring the schema to be opened.

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 intended use is implied by the stated purpose: use it when you need a subreddit's rules. However, it does not explicitly mention when to prefer this over sibling tools, nor does it provide exclusions or alternative routing guidance.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable context beyond them: a per-ID credit cost, the 100-ID cap, and payload reduction via projection_preset and data_fields. It does not cover auth needs or error 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?

Two tight sentences, front-loaded with the primary action and scope. The credit cost and payload options follow efficiently; every clause adds useful information without 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?

No output schema exists, but the description explains the return scope ('up to 100 Reddit subreddits') and payload shaping options. Annotations carry the safety profile. Minor gaps around missing-ID behavior are not critical for a read-only batch retrieval 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 the schema fully documents entityIds, projection_preset, and data_fields. The description names projection_preset and data_fields as payload reduction options but adds no syntax or semantic detail beyond what the schema already provides. 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 ('Returns') and resource ('Reddit subreddits by ID'), plus the batch constraint ('up to 100 in a single request'). It implicitly distinguishes itself from the single-item sibling reddit_get_subreddit through the batch limit, but does not explicitly name that sibling.

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?

Implied usage is batch retrieval by IDs, reinforced by the cost note ('1 credit per ID submitted'). However, it gives no explicit when-to-use guidance relative to alternatives like reddit_get_subreddit or reddit_search_subreddits, and no when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral note that results span 'all available slots', but leaves 'slots' unexplained, which is a missed opportunity to clarify ordering/coverage.

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

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

Two sentences, front-loaded with the core action, and no filler. The second sentence re-lists parameter names already visible in the schema, which is slightly redundant but not 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?

Adequate for a read-only tool with full annotation coverage and no output schema, but the undefined 'slots' concept and the absence of any routing guidance against the many reddit_get_subreddit* siblings leave the definition only minimally complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds the rationale for the projection params ('for payload reduction'), which gives context beyond the schema's per-field text, but no format or interaction detail beyond that.

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

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

States a specific verb+resource ('Returns sticky posts for a subreddit') that cleanly separates it from siblings like reddit_get_subreddit_posts and reddit_get_subreddit. However, it never explicitly names the sibling it is not, so the differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as reddit_get_subreddit_posts for non-sticky content. The agent must infer the use case entirely from the purpose phrase.

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 non-destructive. The description adds that content is markdown, includes the last revision, and supports projection_preset and data_fields for payload reduction, which is useful behavioral context beyond the annotations. It does not cover auth or rate limits, but that is a minor gap for a read-only tool.

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

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

A single front-loaded sentence with no wasted words. It efficiently conveys the action, output format, and optional payload-reduction controls.

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 return-value disclosure and does state markdown plus last revision. Annotations cover safety. Minor gaps like error behavior or pagination are not specified, but for a single wiki-page read tool the definition is nearly complete.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description only reiterates that projection_preset and data_fields reduce payload, adding marginal purpose beyond what the schema already provides. 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 the specific verb 'Returns' and the resource 'one page of a subreddit's wiki', including output format (markdown) and revision metadata. It distinguishes itself from the sibling 'reddit_get_subreddit_wiki_pages' by specifying a single page.

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?

Does not explicitly name alternatives or state when to use this tool versus 'reddit_get_subreddit_wiki_pages'. The phrase 'one page' implies single-page retrieval, but no conditions or exclusions 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the payload-reduction capability (projection_preset/data_fields/item_fields), which is useful behavioral context, but says nothing about pagination, rate limits, or whether private/restricted wikis are accessible.

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 action and followed by the optional payload controls. No filler, though the second sentence is largely a restatement of parameters the schema already names.

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

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

For a simple read-only list tool with a fully documented 4-parameter schema and annotations covering the safety profile, this is adequate. Missing is any indication of the shape of the returned page list (no output schema exists) and no routing guidance toward the singular sibling 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% — subreddit, data_fields, item_fields and projection_preset are all documented in the schema, including the enum values and the 'minimal' default. The description merely enumerates three of the four parameter names without adding syntax, defaults, or interaction semantics beyond what the schema already states.

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 pages of a subreddit's wiki.' An agent can distinguish it from reddit_get_subreddit_wiki_page by the plural 'pages', but the description never explicitly contrasts the two siblings, so the differentiation is left to the name.

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

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

No when-to-use guidance, no mention of the closely related reddit_get_subreddit_wiki_page sibling, and no note on when this is preferable to fetching a single page. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the useful facts that the data is public and that projection_preset/data_fields reduce payload, but says nothing about auth requirements, rate limits, or behavior when the user is missing/suspended.

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

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

Two sentences, no filler, with the resource and return contents front-loaded before the payload-reduction note. Slightly terse for a tool with five projection presets, but nothing is wasted.

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

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

For a simple read-only profile fetch with full schema coverage, no output schema, and annotations covering safety, the description tells the agent what comes back and how to trim it. The remaining gap is sibling disambiguation against reddit_get_user_overview, which the description does not address.

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 username, the projection_preset enum, and data_fields semantics. The description only restates that these two parameters exist for 'payload reduction', adding no format, default, or interaction detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Returns public Reddit user profile information') and enumerates the returned fields (bio, avatar, verification flags, creation date), which distinguishes it from data-oriented siblings like reddit_get_user_comments or reddit_get_user_posts. However it never names or contrasts reddit_get_user_overview, the closest sibling, so an agent must infer the split.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternative tools. With reddit_get_user_overview and reddit_get_user_achievements sitting directly alongside it, the definition gives the agent nothing to route on beyond the word 'profile'.

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, openWorld and non-destructive, so the safety profile is covered. The description adds useful behavioral context by explaining that projection_preset, data_fields and item_fields exist for payload reduction, and it disambiguates the returned data set from trophies.

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

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

Three short sentences, front-loaded with the core purpose, then the sibling boundary, then the parameter note. No filler or repetition.

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

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

With no output schema, the description carries some burden of describing the return, and it does so adequately via 'achievements (e.g. streaks)' plus the item_fields enum hints. It stops short of describing the response envelope (totalItems/orderedItems), leaving a minor gap for an agent reasoning about the shape of 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 description coverage is 100%, so each parameter is already documented including the enum values and defaults. The description only restates the three optional parameter names and their collective purpose (payload reduction), adding little semantics beyond what the schema provides.

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

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

States a specific verb and resource ('Returns a user's achievements') and immediately bounds it with 'Trophies are a separate set', which is exactly the distinction needed against the sibling reddit_get_user_trophies. An agent can route 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?

The 'Trophies are a separate set' sentence functions as an implicit routing rule to the sibling tool, and the mention of payload-reduction options signals when to tune the request. However, it never explicitly says when to call this tool over alternatives like reddit_get_user or reddit_get_user_overview.

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 the safety profile is fully covered. The description adds that only public comments are returned and that time windows apply solely to top/controversial ordering, but says nothing about pagination limits, rate limiting, or empty/deleted-user 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?

Three sentences, front-loaded with the core return value and followed by ordering and payload-reduction notes. No filler, though the payload-reduction sentence is close to a restatement of schema-documented parameters.

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

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

For an 8-parameter read tool with no output schema and full annotation coverage, the description covers the return content, ordering options, and projection capability. Minor gaps remain around pagination behavior and the count cap, but these are already in the schema.

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

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

Schema description coverage is 100% and every parameter, including the ordering enum, time-window enum, cursor, and projection fields, is documented in the schema itself. The description largely restates those parameters, so it earns the baseline 3 rather than adding new semantic detail.

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 public comments made by a Reddit user, which is immediately distinguishable from reddit_get_user_posts or reddit_get_post_comments by name alone. It does not, however, explicitly name the sibling tools it competes with, so the differentiation is inferred rather than stated.

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 explains supported sort orders and time windows but gives no when-to-use guidance relative to siblings such as reddit_get_user_overview, reddit_get_user_posts, or reddit_search_comments, and no exclusions or prerequisites. The agent must infer selection purely from the tool name.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: which orderings exist, that time windows apply only to top/controversial, and that projection_preset/data_fields/item_fields exist specifically for payload reduction. It omits pagination behavior and rate limits, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the return shape, then ordering, then payload controls. No filler, though the third sentence is a list of parameter names that the schema already exposes.

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, 8-parameter, fully schema-documented list tool with no output schema, the description covers purpose, ordering, time-window constraints and payload options adequately. Pagination (cursor) is only in the schema, but that is a minor gap given full coverage elsewhere.

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 mostly restates it (orderings, time windows, projection fields). The only marginal addition is framing the projection parameters as payload reduction, which is a useful hint but not new semantics. Baseline 3 applies.

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

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

States a specific verb and resource: returns a mixed Reddit user activity feed including posts and comments. The word 'mixed' implicitly distinguishes it from reddit_get_user_posts and reddit_get_user_comments, but neither sibling is named, so the differentiation is left for the agent to infer.

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: by describing a combined posts-and-comments feed, the description hints this is the choice when you want both types at once. It never names reddit_get_user_posts/reddit_get_user_comments as alternatives, nor states any when-not condition, so the agent gets no explicit routing guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds that the posts are public and that time windows only apply to top/controversial ordering, but says nothing about authentication needs, rate limits, or pagination behavior beyond what the schema exposes.

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

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

Three tight sentences that front-load the core action and then enumerate supported options. No filler, though the closing projection sentence is somewhat list-like.

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 8-parameter tool with no output schema, the description omits anything about the returned payload shape, which is non-trivial given the projection_preset/data_fields/item_fields reduction mechanics. Annotations cover safety, but return-format transparency 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 all eight parameters are already documented, including the enum values for order, published, and the projection fields. The description restates the ordering and projection options without adding syntax, defaults, or format detail 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?

"Returns public posts submitted by a Reddit user" gives a specific verb and resource, and implicitly separates itself from siblings like reddit_get_user_comments and reddit_get_subreddit_posts by scoping to a user's posts. Clear, though it does not explicitly name a sibling to differentiate against.

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

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

The description lists ordering and time-window features but offers no when-to-use guidance, no prerequisites, and no alternatives. An agent is left to infer that this is for user post timelines rather than subreddit feeds or user comments.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the return content shape (trophies with grant dates) but says nothing about rate limits, auth requirements, pagination, or empty-profile behavior, so it only moderately exceeds the annotation baseline.

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

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

Three tight sentences: purpose and return shape first, sibling distinction second, payload-reduction knobs last. No filler and 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 usefully describes what is returned and explicitly notes the payload-reduction controls. For a single-required-parameter read tool with full annotations this is nearly sufficient; only pagination and edge-case behavior are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning by explaining why projection_preset, data_fields and item_fields exist ('for payload reduction'), a rationale the schema descriptions do not state. It still does not explain what each preset actually contains, so it falls short of 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?

States a specific verb and resource (returns the trophies on a user's profile), gives a concrete example (Ten-Year Club), and names the return content (the date each was granted). Crucially, it distinguishes itself from the very similarly named sibling reddit_get_user_achievements by noting that achievements are a separate set.

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

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

The sentence 'Achievements are a separate set' explicitly routes the agent away from this tool when it wants achievements, which is the highest-risk confusion among siblings. It does not, however, clarify the boundary against reddit_get_user or reddit_get_user_overview, so no exclusions are stated for those.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety and idempotency are covered and the bar for the description is lower. The description adds useful context about payload-reduction knobs (projection_preset, data_fields, item_fields) and sort options, but says nothing about pagination behavior beyond what the schema's cursor field implies.

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

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

Two sentences, no filler, front-loaded with the core operation and scope before the optional knobs. Every clause earns its place.

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

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

For an 8-parameter, non-output-schema tool, the description covers the operation, subreddit scoping, sorting, and the three projection parameters that meaningfully change the response shape. What is missing is pagination behavior (how cursor/nextCursor round-trips), which the agent must infer from the schema.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including the query operators, count default/max, cursor, and enum values. The description only restates sort modes and the projection fields at a high level, adding no syntax or default detail beyond the schema; baseline 3 applies.

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

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

The description states a specific verb+resource ('Searches public Reddit comments') and adds scope ('optionally limited to one or more subreddits'), which is enough for an agent to understand the operation. It does not, however, differentiate itself from the very close siblings reddit_search_subreddit_comments and reddit_get_subreddit_comments, so the sibling distinction is left to be inferred.

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

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

There is no statement of when to use this tool versus alternatives, and no named alternative. Given that reddit_search_subreddit_comments exists as an obvious near-duplicate, the absence of routing guidance is a real gap; only a weak implied scope ('optionally limited to subreddits') is present.

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/openWorld, so the safety profile is covered. The description adds that sorts, time windows, and format filters are supported and that projection_preset/data_fields/item_fields exist for payload reduction — the latter explains the intent of the projection params, which annotations/schema do not.

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

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

Three tight sentences, front-loaded with what the tool does before the capability and payload-reduction details. 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?

No output schema exists, but the description hints at return structure through projection presets and item/data fields, and covers filtering, sorting, and pagination via cursor in the schema. It never explicitly describes the returned envelope, so it is strong 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 all nine parameters are already documented in the schema. The description restates sorting, time windows, formats, and projection fields without adding syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource ('Searches public Reddit posts') and clarifies platform-wide scope ('across the platform'), which implicitly distinguishes it from the subreddit-scoped sibling reddit_search_subreddit_posts. It does not name the sibling explicitly, so it falls just short of 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?

'Across the platform' implies the use case (broad search vs a subreddit-restricted search), but there is no explicit when-to-use/when-not guidance and no sibling alternative is named. Usage must be inferred from the scope phrase.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that results are public comments and that projection parameters reduce payload, but it omits rate limits, data freshness, and pagination 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?

Three sentences, front-loaded with the core purpose, then sorting support and payload reduction options. No wasted words, and the most important information appears first.

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 rich annotations, full schema coverage, and no output schema, the description is nearly sufficient. It could better distinguish itself from reddit_search_comments and reddit_get_subreddit_comments, but an agent has enough context 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%, so the schema already documents all eight parameters. The description repeats sorting options and mentions projection_preset, data_fields, and item_fields for payload reduction, which adds a small amount of rationale but no syntax or format details beyond the schema.

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

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

The description states a specific verb ('Searches'), resource ('public Reddit comments'), and scope ('within a subreddit'), which distinguishes it from global comment search and subreddit post search siblings. An agent can identify the tool without opening the schema.

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

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

The description gives no guidance on when to use this tool versus alternatives such as reddit_search_comments or reddit_get_subreddit_comments. It implies a search-in-subreddit use case but provides no explicit conditions or 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 declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds that results are 'public' and can be narrowed by sort/time/format, but says nothing about rate limits, result caps, or pagination behavior beyond what the schema states.

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

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

Two sentences, no filler, and the core scope ('within a subreddit') leads before capability detail. Slightly dense in the second sentence with parameter names, but still front-loaded and disciplined.

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 10-parameter, no-output-schema search tool with annotations covering the safety profile, the description covers scope, sorting, time windows, format limiting, and projection. Only minor gaps remain around result caps and paging, which the schema already handles.

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 every parameter, including count limits, cursor, and enum meanings. The description adds only a light gloss ('optional time windows', 'payload reduction') and no syntax or interaction detail beyond that baseline.

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

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

States a specific verb+resource+scope: 'Searches public Reddit posts within a subreddit.' The 'within a subreddit' scoping implicitly separates it from reddit_search_posts (site-wide) and reddit_get_subreddit_posts (query-less listing), but no sibling is 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?

It enumerates capabilities (sort orders, time windows, format filters) which implies when the tool is useful, but never states when to prefer it over reddit_search_posts or reddit_get_subreddit_posts, nor any prerequisites or 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral trait – that projection_preset/data_fields/item_fields exist for payload reduction – but says nothing about pagination via cursor, rate limits, or auth. Some added context, but not rich.

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

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

Two sentences, front-loaded with the core purpose and no filler. The projection/payload-reduction clause is compact. Slightly terse given there is room for a when-to-use clause, but nothing is wasted.

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

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

For a read-only search tool with full schema coverage and no output schema, the definition is adequate to invoke but thin on context: it doesn't describe the shape of returned subreddit results (member counts, description, etc.) or paging behavior, both relevant since no output schema exists.

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 all six parameters are documented in the schema, so the baseline is 3. The description names three parameters and frames them as 'payload reduction', which clarifies intent but adds no syntax or format detail beyond the schema.

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

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

The description gives a specific verb and resource ('Searches public Reddit subreddits across the platform'), clearly distinct from siblings like reddit_get_subreddit (fetch a known subreddit) and reddit_search_users/posts. It stops short of explicitly naming an alternative, but the verb+resource combination 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The word 'Searches' and the scope phrase 'public subreddits' imply discovery-by-query, but the agent must infer this rather than being told. No exclusions are offered.

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, open-world, and non-destructive behavior, so the safety profile is covered. The description adds useful pagination context ('up to 100 users per page') but says nothing about rate limits, auth requirements, or ordering of results.

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

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

Three short sentences with no filler, and the core action is front-loaded. Slightly more could be trimmed but it is well structured.

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

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

Adequate for a read-only search tool whose annotations cover safety and whose schema covers all params, and it does disclose the page size. With no output schema, it could still say more about the shape of returned user objects.

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 query, count, cursor, and the projection fields. The description adds only the purpose of the projection params ('payload reduction'), which is marginal 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+resource ('Searches public Reddit users') that clearly separates it from retrieval siblings like reddit_get_user. However, it doesn't explicitly contrast itself with other search tools (reddit_search_posts, reddit_search_subreddits), leaning on the 'users' resource noun to differentiate.

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

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

No when-to-use guidance, no alternatives named, and no conditions distinguishing search from a direct user lookup. Usage is only implied by the tool name.

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

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

Annotations already establish readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral trait beyond the schema: that projection_preset and data_fields exist to reduce payload size. It says nothing about rate limits, auth requirements, or behavior when the audioId is invalid/private.

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

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

Three short sentences, front-loaded with what the tool returns before the identifier and the payload-reduction options. No filler, though the middle sentence ('Look up any sound by its audio ID') is partly redundant with the required-param name.

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?

Despite no output schema, the description enumerates the key returned fields, and with read-only annotations plus fully documented parameters there is little risk of misinvocation. Missing only the sibling disambiguation and any note on error/rate-limit behavior.

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

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

Schema description coverage is 100% and all three parameters (including the enum for projection_preset and the data_fields item list) are documented in the schema. The description only adds that the two optional knobs are for 'payload reduction' and does not explain what each preset or field key yields, so it stays at the baseline 3.

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

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

The description pairs a specific verb ('Returns metadata') with a precise resource ('a TikTok audio track') and even enumerates the returned fields (title, artist, duration, usage count, cover image). It does not, however, distinguish itself from the close sibling tiktok_get_audio_videos, so an agent must infer the split between 'audio details' and 'videos using this audio'.

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?

'Look up any sound by its audio ID' implies the lookup precondition and required identifier, but there is no explicit when-to-use/when-not guidance and no mention of the alternative tiktok_get_audio_videos. Usage is reasonably inferable but not 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds pagination behavior ('Maximum 30 per page'), which is genuinely useful context, but much of the pagination detail (cursor, count) and the payload-reduction mechanism is already documented in the schema.

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

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

Three sentences, front-loaded with the core action and scope, then pagination and payload options. The 'Discover trending content by sound or music' sentence is mildly decorative but the whole is tight and free of repetition.

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

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

For a read-only list endpoint with no output schema and full schema coverage, the description supplies the essentials: what it returns, the page size cap, and available projection controls. It leaves return-item shape and cursor semantics to the schema, which is acceptable 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 description coverage is 100%, so every parameter is documented in the schema, making the baseline 3. The description's mention of projection_preset, data_fields, and item_fields adds the rationale ('payload reduction') but no syntax or format detail beyond what the schema already states.

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

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

The description gives a specific verb and resource: 'Returns a paginated list of TikTok videos using a specific audio track.' This clearly separates it from tiktok_get_audio (the audio entity itself) by implication, but it never names that sibling explicitly, so differentiation is left partially to inference.

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

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

'Discover trending content by sound or music' hints at the use case but is vague and evocative rather than directive. There is no explicit when-to-use, when-not-to-use, or alternative routing against tiktok_get_audio or tiktok_search_videos.

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, open-world safety. The description adds that pagination is capped at 35 per page and that projection_preset, data_fields, and item_fields enable payload reduction, which is useful context beyond annotations. It stops short of auth, rate limits, or cursor 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?

Four short sentences, front-loaded with the core action and pagination limit, then payload controls. No filler or repetition.

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

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

No output schema, but the description gives the essential return shape: paginated video list, max page size, full details, and engagement counts. It does not unpack cursor semantics or all selectable field groups, but it is sufficient for invocation given the 100% schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names three optional parameters and frames them as payload reduction, but that framing is imprecise because data_fields and item_fields add keys on top of a preset rather than strictly reduce payload.

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 'Returns' and resource 'videos in a TikTok collection (playlist or mix)', with pagination scope. It does not explicitly distinguish from siblings like tiktok_get_user_collections or tiktok_get_user_videos, so it is clear but lacks explicit sibling contrast.

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

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

No explicit when-to-use or when-not guidance and no alternative tool named. Usage is only implied by the retrieval verb and the 'maximum 35 per page' note, so it meets the minimum viable bar but leaves routing to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing the 50-per-page cap, the paginated nature of the result, and the payload-reduction mechanism via projection_preset/data_fields/item_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?

Three tight sentences with the core behavior front-loaded and no filler. It is efficient, though the third sentence listing projection parameters borders on restating schema 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 simple paginated read tool with a fully described schema and no output schema, the description covers what is returned, page limits, and payload shaping. It is nearly complete, with only the cursor-based pagination flow 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 description coverage is 100%, so the schema already documents each parameter, including enum values and the cursor continuation semantics. The description names the projection parameters but adds no syntax or selection guidance beyond what the schema provides, 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 ('Returns a paginated list of replies to a TikTok comment'), which is precise enough to separate it conceptually from tiktok_get_video_comments. However, it never names that sibling or otherwise explicitly distinguishes itself from the top-level comment 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as tiktok_get_video_comments for top-level comments. The agent must infer the use case purely from the verb and resource.

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