Bridgly

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

The read-only statement is consistent with, but largely repeats, readOnlyHint=true and destructiveHint=false. The description adds materially useful behavior beyond the annotations by disclosing that invocation is free and consumes no credits, while also clarifying that it reads the connected account's current state.

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

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

Two short sentences front-load the operation and resource, then state the safety and cost characteristics. There is no filler, redundant setup, or unnecessary structural overhead.

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

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

For a zero-parameter read, the description provides enough information to select and invoke the tool correctly, including account scope and credit cost. Because there is no output schema, briefly identifying the included billing settings or noting whether values such as currency and plan are returned would make it more 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?

The tool has no parameters, so the baseline is 4 and there are no argument meanings or formats left to explain. The description still supplies useful implicit scope by specifying the connected Bridgly account rather than an arbitrary account identifier.

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 identifies both returned resources: the current credit balance and billing settings of the connected Bridgly account. Its Bridgly billing scope clearly distinguishes it from all supplied siblings, which concern social-platform data.

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

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

An agent can infer that this is the tool for checking the connected account's present balance or billing configuration, and the zero-credit cost encourages its use for that purpose. It does not provide explicit when-not guidance or alternatives, but none of the listed siblings appears to overlap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the sentence 'Read-only: returns public data and changes nothing' largely restates structured data. The one genuinely additive fact is 'Costs 1 credit per request', which is useful budget context not available elsewhere. With no output schema, it still says nothing about the shape of the returned calendar/totals, so it does not go far beyond 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 short sentences, front-loaded with purpose, then safety, then cost — easy to scan with no filler. Slight deduction because the read-only sentence duplicates annotation content and could have been spent on return-value detail instead.

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 three-parameter read tool with fully documented parameters, the description covers purpose, safety, and cost adequately. Because there is no output schema, the definition leaves the return shape (per-day calendar vs. aggregated totals, fields returned) entirely unexplained, which is the main 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 description coverage is 100%, with from/to format, inclusivity, defaults, and the one-year window constraint all documented in the schema. The description adds no parameter meaning at all, 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?

The description names a specific verb (Fetch) and a specific resource (a GitHub user's contribution calendar and totals), which is meaningfully narrower than the sibling github_get_profile. An agent can tell what this returns without opening the schema, though it never explicitly contrasts itself with github_get_profile.

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

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

Usage is only implied by the purpose statement — there is no explicit when-to-use, when-not-to-use, or named alternative among the many github_* siblings. The read-only note mildly signals it is a lookup rather than a search, but the agent must infer that a profile lookup belongs to github_get_profile instead.

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 read-only/no-side-effects sentence largely duplicates the supplied readOnlyHint and destructiveHint annotations, so it earns little on its own. However, "Costs 1 credit per request" is genuine operational context absent from the annotations — a quota constraint the agent cannot see in structured fields. No return-format detail, but that is a minor omission for a single-entity fetch.

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

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

Three compact sentences: what it does, safety profile, cost. The most decision-relevant fact (the operation and cost) is front-loaded with zero filler or marketing language.

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

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

For a one-parameter, read-only fetch with full annotation coverage and a fully documented schema, the description covers purpose, safety, and cost — enough to invoke correctly. The remaining gap is that no output schema exists and the description does not indicate what the profile payload contains or how many pinned repositories come back.

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

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

With one parameter at 100% schema description coverage, the schema already documents the username field and even its URL-form acceptance. The description adds no format, casing, or encoding guidance beyond that, so the baseline of 3 applies.

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

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

"Fetch a GitHub user's profile and pinned repositories" gives a specific verb (fetch) and a precisely scoped resource, including the distinguishing detail of pinned repositories. It is clearly a single-user lookup rather than a search or listing, though it never names the nearest alternatives like github_search_users or github_list_repositories.

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 nothing about when to reach for this tool instead of github_search_users (to resolve a handle) or github_list_repositories (for repo lists). The only implicit cue is the word "pinned," which hints that full repository listing belongs elsewhere, but that inference is left entirely to the agent.

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 read-only and non-mutating claims are consistent with the annotations but largely repeat them. The description adds useful operational context by emphasizing that only public data is returned and disclosing a cost of 1 credit per request.

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 front-loads the operation and scope, then concisely covers safety and cost. It is easy to scan, although "Read-only" and "changes nothing" are mildly redundant with each other and with the annotations.

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?

Combined with the complete input schema and safety annotations, the description is sufficient to invoke this simple paginated listing operation correctly. Its main remaining gaps are the implicit distinction from github_list_repositories and, with no output schema, the absence of any indication of what project information is returned.

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?

All three parameters are fully documented in the schema, including accepted username forms, count limits and default, and cursor-based pagination. The description adds no parameter meaning beyond that complete coverage, so the high-coverage baseline 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 uses a specific verb and resource—"List a GitHub user's public projects"—and clearly states the public-data scope. It does not explicitly distinguish projects from repositories or starred items, leaving sibling differentiation incomplete.

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 wording implies use when an agent needs a particular user's public project list, but it provides no explicit selection criteria. It also does not direct agents to github_list_repositories or another sibling when a different GitHub resource is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds a genuinely new trait not present in structured fields: a concrete cost of 1 credit per request, which matters for agent budgeting. It does not discuss pagination limits or result-size behaviour, but the cursor parameter covers paging 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 short clauses, front-loaded with the core action, followed by the safety statement and the cost. No filler and nothing redundant beyond a brief restatement of read-only for emphasis.

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

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

For a four-parameter read-only list tool with full schema coverage and no output schema, the description plus schema is sufficient to call it correctly. The remaining gap is routing context against similarly named GitHub listing and search siblings, which the description never addresses.

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 bounds, the order enum, cursor semantics and the username format all documented inline. The description adds no additional meaning about these parameters, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("List a GitHub user's public repositories") and makes the public-only scope explicit, so the agent knows exactly what is fetched. It does not differentiate from close siblings like github_search_repositories or github_list_starred, which is the only thing keeping it from 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 guidance on when to choose this over github_search_repositories, github_list_starred, or github_list_projects. The only implied condition is that you need a named user's repos, which the agent must infer from the title 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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds two things not in the annotations: the scope of returned data ('public data') and a credit cost of 1 per request. It does not mention the 10-result cap or pagination behavior, which are left entirely to 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 short sentences, each carrying distinct information: purpose, safety/scope, and cost. Purpose is front-loaded and there is no filler or restatement of the title alone.

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

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

For a three-parameter read tool with full schema coverage and no output schema, the description covers purpose, read-only nature, data scope and credit cost. The remaining gap is return-shape expectation (a list of repos with a nextCursor), which the cursor parameter implicitly signals 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 the schema already explains count (1-10, default 10), cursor (previous response's nextCursor) and username (login or profile URL). The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the repositories a GitHub user has starred'), which is precise enough to separate it from github_search_repositories and github_list_repositories. It stops short of explicitly contrasting with the sibling list of a user's own repositories, so an agent must infer the distinction from the word 'starred'.

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 narrow scope: fetch the repos a user has starred, given a username. There is no explicit statement about when to prefer github_list_repositories or github_search_repositories instead, and no prerequisites mentioned. An agent can figure it out from the name, but the description does no routing work.

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, so the safety profile is covered and "returns public data and changes nothing" largely restates it. The genuinely additive disclosure is "Costs 1 credit per request", a budgeting constraint not present in any structured field, plus the implicit guarantee that only public (non-private) repositories are reachable.

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 filler, with the purpose front-loaded and the safety/cost facts trailing. Nothing is repeated or 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 12-parameter search tool with no output schema, the description says nothing about result shape, paging behavior, or the 1,000-result ceiling that matters when chaining calls (the schema only hints at it via start's max). Annotations plus a fully documented schema keep it adequate, but the routing gap versus sibling search tools leaves it incomplete.

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 one of the 12 parameters carries its own description, including GitHub query-syntax mappings (path:, repo:, user:, filename:). The description adds no parameter meaning of its own, so the baseline 3 applies.

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

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

States a specific verb+resource ("Search code across public GitHub repositories") and pins the scope to public repos, which separates it from write-oriented GitHub tools. It does not explicitly distinguish itself from the nearest sibling, github_search_repositories, so an agent must infer that this one matches file contents rather than repository metadata.

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

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

Usage is only implied by the phrase "search code"; there is no explicit when-to-use or when-not-to-use guidance and no named alternative such as github_search_repositories or github_search_commits. The scope word "code" is the only routing signal the agent gets.

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, destructiveHint=false, idempotentHint, and openWorldHint, so the safety profile is covered. The description still earns credit for two things annotations cannot express: that only public data is touched and that each request costs 1 credit, which matters for call budgeting. It omits the 1,000-result pagination ceiling, though the schema's start parameter covers that.

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, each doing distinct work: purpose, safety/scope, and cost. The purpose statement is front-loaded and nothing is padded or repeated from the structured fields.

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 13 parameters, nested date filters, and no output schema, the definition is arguably under-specified about what a returned commit record contains and whether the credit cost scales with pagination. The description is adequate for correct invocation because the schema is exhaustive, but an agent has no picture of the response 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 description coverage is 100%, with every parameter documented inline including the hash/author/committer/repo qualifier mappings and the date-range nested objects. The description adds no syntax or interpretation guidance 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?

The description names a specific verb and resource ("Search commits") and constrains scope to public GitHub repositories, which cleanly separates it from github_search_code, github_search_issues, and github_search_pull_requests. It stops short of explicitly naming those siblings or the conditions that would pick one over the other.

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 beyond the implied scope of "public repositories." The agent must infer on its own whether to reach for commit search versus code search, issue search, or a repository listing when investigating a project.

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 'read-only: returns public data and changes nothing' largely restates structured data. The one genuinely additive fact is 'Costs 1 credit per request', a real budget constraint absent from annotations, but nothing is said about result caps, pagination behavior, or what a discussion record 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 short sentences with the purpose front-loaded and no filler. The second sentence is close to redundant with the readOnly annotation, but the text is otherwise tight and scannable.

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 11 parameters, nested date/comment range objects, and no output schema, the description is thin: it never explains that results are paginated via nextCursor, that count is capped at 10, or what fields a discussion returns. Annotations and full schema coverage carry most of the burden, making this adequate but not complete.

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

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

Schema description coverage is 100% and all 11 parameters are documented in-schema, including the GitHub-qualifier mappings (repo:, author:, is:answered) and cursor pagination. The description adds no parameter meaning 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?

The description states a specific verb and resource ('Search GitHub discussions'), so an agent knows exactly what it queries. However, it never distinguishes this from the many sibling search tools (github_search_issues, github_search_pull_requests, github_search_code), leaving the agent to infer that discussions are a distinct content type rather than issues or PRs.

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 and no named alternative. The description does not say to prefer this over github_search_issues when looking for Q&A-style threads, nor does it state any precondition (auth, scope, rate budget) beyond the credit cost.

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 description's read-only claim is partly redundant. However, it adds two genuinely useful facts not in the annotations: results are public data only, and each request costs 1 credit. It omits pagination behavior and result-shape details, keeping it below 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 short, front-loaded sentences with no filler; the purpose comes first and the cost note last. The read-only sentence largely restates the annotations, which is minor redundancy rather than bloat.

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

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

This is a complex 18-parameter tool with nested date-range objects and no output schema, yet the description never describes what a result contains or how pagination works beyond the schema's cursor field. It covers safety and cost adequately but leaves the agent guessing about return shape for a search-heavy 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%, and each parameter documents its GitHub search qualifier mapping (repo:, state:, author:, etc.), date ranges, and defaults. The description adds nothing beyond the schema for any of the 18 parameters, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Search GitHub issues"), which is enough for an agent to separate it from sibling search tools such as github_search_pull_requests or github_search_code by name. It does not explicitly name those siblings or clarify whether PRs are included, 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?

There is no guidance on when to choose this tool over github_search_pull_requests, github_search_discussions, or github_list_repositories, and no exclusions or prerequisite conditions are stated. The only implied usage cue is the word "issues" combined with the filtering parameters in the schema.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds one genuinely new piece of context — 'Costs 1 credit per request' — which affects call budgeting, but it otherwise restates the read-only trait and says nothing about rate limits, result caps, or 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?

Three short sentences, front-loaded with purpose, with no filler or throat-clearing. The middle sentence partially duplicates the readOnlyHint annotation, which is mild redundancy rather than wasted space.

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

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

For a 20-parameter search tool with nested objects and no output schema, the description covers purpose, safety, and cost but leaves the agent guessing about the response shape, result limits (count caps at 10), and pagination workflow. The rich schema compensates for the parameter side, but the return side is entirely undocumented.

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 every one of the 20 parameters documented in the schema itself, including enum meanings and the gt/gte/lt/lte date-range pattern. The description adds no meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Search GitHub pull requests'), so an agent knows exactly what the tool retrieves. It does not, however, distinguish itself from the many adjacent siblings such as github_search_issues, github_search_commits, or github_search_discussions, so the agent must infer the boundary from the name alone.

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

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

There is no guidance on when to use this tool versus github_search_issues or github_search_repositories, and no mention of prerequisites or exclusions. The only contextual hint is the implicit 'pull requests' in the name; the description itself says nothing about alternatives.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, and the sentence 'Read-only: returns public data and changes nothing' largely repeats them. The one genuinely additive fact is 'Costs 1 credit per request', which gives budget-relevant context not present in annotations, but nothing is said about result caps or paging behaviour beyond what the schema already encodes.

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 purpose front-loaded and the cost signal last. One sentence is partly redundant with the annotations, but nothing is verbose or buried.

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

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

For an 18-parameter, nested-filter search tool with no output schema, the description is thin: it says nothing about how filters combine, whether query is optional, or that results are paginated via cursor. The rich schema compensates for the per-parameter gaps, but behavioural completeness for a tool this complex is only adequate.

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 one of the 18 parameters is documented inline, including range semantics, enum meanings and GitHub qualifier mappings. The description adds no parameter meaning on top of that, so the baseline 3 applies.

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

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

The description gives a specific verb + resource ("Search public GitHub repositories"), which cleanly separates it from siblings like github_search_code, github_search_issues and github_search_users. The word 'public' also signals it is not the same as github_list_repositories, though 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?

There is no guidance on when to choose this over github_list_repositories (list your own repos) or github_search_code / github_search_topics when a query spans code or topic entities. The agent must infer the selection rule from the tool name alone.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the sentence 'Read-only: returns public data and changes nothing' largely restates structured data. The one genuinely new behavioral fact is the cost ('1 credit per request'), which is not captured in annotations and is useful for planning; nothing is said about result caps, rate limits, or page 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 short sentences, front-loaded with the action, with no filler. The cost sentence earns its place because it is not derivable from structured fields, though the read-only sentence is largely redundant with annotations.

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 7-parameter search tool with nested objects and no output schema, the description is complete on identity and safety but silent on result shape, the 10-per-page and 1,000-result paging ceilings (only implicit in the schema), and how topics are matched. It is minimally adequate rather than thorough.

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% across all 7 parameters, including nested date-range and repository-count bound objects, so the schema fully carries parameter meaning. The description adds no filtering syntax, default behavior, or interpretation beyond what the schema already 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 ('Search GitHub topics') that is unambiguous and distinguishes it from sibling searches like github_search_repositories or github_search_code by resource type. It does not explicitly contrast with those siblings, but the named resource is distinct enough for an agent to select correctly.

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

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

There is no guidance on when to use this rather than github_search_repositories, github_search_code, or any other sibling search tool. The only implicit signal is the word 'topics'; no exclusions, prerequisites, or alternative routing 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=true, so 'read-only: returns public data and changes nothing' largely restates what is already structured. The one genuinely additive fact is the cost signal, 'Costs 1 credit per request', which is behavior an agent cannot get from the schema or annotations. Return shape and result-set limits are left unexplained, though the schema's count cap of 10 partly covers that.

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 clauses, front-loaded with the resource identification, with no filler or preamble. The read-only sentence partly duplicates the annotations, which is minor waste but not enough to undermine the efficient framing.

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 12 parameters, three required fields, nested range filters, and no output schema, the definition is thinner than the tool's complexity warrants. The agent is not told what a result record looks like or that paging is handled through the cursor field, forcing it to reconstruct that from the schema alone.

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 nested gt/gte/lt/lte range objects and the cursor, carries its own documentation, so the schema does the heavy lifting. The description adds no semantic detail beyond it and does not mention the required sort/order/count triplet or pagination via cursor, so the baseline 3 applies.

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

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

The description uses a specific verb ('Search') plus a precise resource ('GitHub users and organizations'), which cleanly separates it from siblings like github_search_repositories, github_search_code, and github_search_issues. It stops short of naming the closest lookup alternative, github_get_profile, so an agent must still infer which one applies to a known handle.

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 named alternative. The description never says to prefer github_get_profile when a specific username is known, nor how this differs from x_search_users or reddit_search_users among the 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 and openWorldHint, so safety is covered; the description adds the cost model (1 credit per result, minimum 1 credit per request), which is billing context absent from annotations. It stops short of saying how failures or empty/private results are handled.

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, front-loaded sentences with no padding; the safety and cost facts come before any detail. The opening clause duplicates the title verbatim, which is the only wasted text.

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

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

For a three-parameter read-only list tool with full schema coverage and no output schema, the description covers scope, safety and cost adequately. Remaining gaps (return shape, rate limits, behavior on private or nonexistent accounts) are minor but real.

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 username, count and cursor are already fully explained in the schema. The description's credit-per-result line adds costing meaning to `count` but says nothing beyond the schema about cursor semantics or result ordering.

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

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

States a specific verb and resource ('Get paginated user followers'), which cleanly separates it from the sibling instagram_following. It does not name the sibling explicitly, but the direction of the relationship is unambiguous from the name and verb.

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

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

No guidance on when to use this versus instagram_following or instagram_user, and no stated prerequisites (e.g., private accounts, missing profiles). Pagination behavior is only inferable from the word 'paginated' and the schema's cursor field.

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, so the safety profile is covered. The description adds genuinely new context not in structured fields: a per-result credit cost with a 1-credit minimum per request, which matters for invocation decisions. It is slightly redundant in restating read-only, and says nothing about failure modes for private or non-existent accounts.

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 resource named first and the cost caveat placed after the safety note. Little waste, though "returns public data and changes nothing" partially restates the readOnly annotation.

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 list tool with a fully documented schema, the definition covers scope, safety, and cost adequately. However, there is no output schema and the description never indicates what a returned user record contains or that the response carries a nextCursor, leaving the caller to discover the result shape empirically.

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

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

With 100% schema description coverage, all three parameters (including cursor semantics and the 1–10 count bound) are already fully documented in the schema. The description adds no meaning beyond the word "paginated", 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?

Names a specific verb and resource ("Get paginated users followed by the user") scoped to Instagram, which is unambiguous versus instagram_followers. It stops short of explicitly contrasting with that sibling, so an agent must infer the following/followers distinction from the wording alone.

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

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

No when-to-use, when-not-to-use, or alternative-tool guidance is given; nothing tells the agent to prefer instagram_followers for the inverse direction or instagram_user for profile data. Pagination is only named in the title, leaving the agent to discover the cursor workflow from the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so "Read-only: returns public data and changes nothing" largely restates structured data. It does add two useful pieces of context beyond annotations: that only public data is reachable (implying private accounts will not resolve) and the cost of 1 credit per request. It says nothing about error behavior or whether failed lookups still consume a credit.

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 verb+resource, followed by safety and cost. No filler, no repetition of the title beyond the identifying clause, and the most decision-relevant constraint (cost) is near the front.

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

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

For a single-parameter read tool with full schema coverage and complete annotations, this is close to adequate, but with no output schema the description gives no hint about what "post details" includes (caption, media, metrics, timestamp) or how private/deleted posts surface. The credit-cost claim also raises an unresolved question about charging on failure.

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

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

Schema description coverage is 100%, and the schema itself already explains that the parameter accepts a bare shortcode or a full post/Reel URL with examples. The description's "by shortcode" adds no format, URL-parsing, or validation detail beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Get post details by shortcode"), which is unambiguous about what is returned. It does not explicitly differentiate itself from nearby siblings like instagram_user_posts or instagram_post_comments, but the shortcode-keyed lookup is distinguishable from those by 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?

There is no statement of when to use this tool versus alternatives such as instagram_user_posts (listing a user's posts) or instagram_post_comments. No prerequisites, no guidance on what to do if the shortcode is private or invalid, and no mention of whether other tools accept the same shortcode.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description's 'read-only ... changes nothing' is largely redundant. It does add genuinely new behavioral context by disclosing the billing model ('1 credit per result, minimum 1 credit per request'), which annotations cannot express, but it says nothing about result ordering or pagination 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 short sentences, front-loaded with purpose and safely padded with the safety and cost facts. Nothing is wasted, though the title is repeated verbatim in the first clause.

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 three-parameter read tool with a fully described schema and explicit annotations, the description covers purpose, safety and cost. It is still thin on result shape (no output schema exists) and on any guidance about iterating pages, which an agent must derive from the cursor field.

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 shortcode, count and cursor are all fully documented in the schema, including the range limit and pagination semantics. The description adds no parameter-level meaning, 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?

The description states a specific verb and resource ('Get comments on a post') scoped to Instagram, so an agent can tell it fetches comments rather than the post itself. It does not distinguish itself from near siblings such as instagram_post or tiktok_get_video_comments, leaving the platform/scope difference to the tool 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 or when-not-to-use guidance is given; nothing says whether to use this rather than instagram_post or the TikTok equivalent, and no prerequisites (e.g., that the post must be public) are stated. The agent must infer usage from the tool name alone.

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

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

The read-only phrasing largely repeats what readOnlyHint, destructiveHint, and openWorldHint already declare, so it earns little credit. The one genuine addition beyond the annotations is the cost disclosure ('1 credit per request'), which is useful for planning, but return format and result limits are unstated.

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 purpose and with no filler. The only waste is the opening restatement of the tool title, which duplicates the name field.

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

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

For a one-parameter search tool with no output schema this is minimally adequate, but search tools live or die on matching semantics and result shape, both of which are absent. The cost note is a nice touch but does not fill the semantic 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 0% for the single 'query' parameter, and the description does nothing to compensate. It never explains whether query is a username fragment, exact handle, or free-text display-name match, which is the key ambiguity an agent needs resolved before calling.

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 the verb and resource ('Search users') on Instagram, but it is essentially the title restated with a platform prefix. It gives no detail on what is being matched (username vs. display name vs. bio) or what a result record contains, so it barely distinguishes this from the sibling instagram_user lookup.

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

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

There is no guidance on when to use this instead of instagram_user, instagram_followers, or instagram_following. The agent must infer that search is for partial-name discovery rather than fetching a known account, with no explicit exclusions or alternatives named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so 'changes nothing' largely restates them. The description does add genuinely new context — that only public data is returned and that each request costs 1 credit — but it is silent on what happens for private or nonexistent accounts and whether credits are still charged.

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, with the core action front-loaded and constraints following. Nothing is padded or repeated for its own sake.

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

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

For a single-parameter read-only lookup this covers the essentials: what it fetches, that it is safe, and its cost. The main residual gap is that with no output schema, the description does not hint at what profile fields come back.

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

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

Schema description coverage is 100% and the single username parameter is already documented with an example covering both a bare handle and a full profile URL. The description adds no additional meaning about input format or normalization, 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?

The description names a specific verb and resource ('Get user profile by username'), so an agent immediately knows the operation. It does not explicitly differentiate itself from nearby siblings such as instagram_search_users or instagram_user_posts, leaving that distinction to be inferred from names.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. The agent must infer that instagram_search_users should be used for discovery and this tool for a known handle, which is inferable but never 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered and the 'Read-only: returns public data and changes nothing' sentence largely restates it. The genuinely additive element is the billing behavior (1 credit per result, minimum 1 per request), which is real context an agent cannot get from annotations or schema.

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

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

Three short sentences, front-loaded with purpose, then safety, then cost — an efficient order with no filler. The read-only sentence is partially redundant with the annotations, which is the only wasted wording.

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 three-parameter read tool with no output schema and full schema coverage, the definition covers purpose, safety, and cost. The one gap is that return shape beyond the nextCursor hint and any rate-limit behavior are unstated, though the schema largely compensates.

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%: username format, the 1-10 count bound, and the cursor/nextCursor paging contract are all documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get paginated user posts') for a named platform, so an agent can distinguish it from instagram_user (profile) and instagram_post (single post) by resource scope. It stops short of explicitly naming those siblings, which keeps it from 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 or when-not-to-use guidance: nothing says to prefer instagram_post for a single post or instagram_user for profile data, and no prerequisites (public account, rate limits) are mentioned. The only implied usage cue is 'paginated', which the cursor parameter already conveys.

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, and the description redundantly restates read-only but adds two genuinely new facts: results are public data, and there is a stated cost model of 1 credit per result with a 1-credit minimum per request. It does not cover authentication needs or how pagination interacts with billing on large pulls.

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 action and resource, then the safety profile, then the cost. Every sentence carries information; there is no filler.

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

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

For a four-parameter read tool with rich annotations and full schema coverage, the description supplies the one thing the structured fields cannot: the credit cost. Minor gap in not clarifying whether replies are included or how credits scale with the start offset on deep pagination.

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 ranges, start offset, sortOrder enum meanings, and accepted activityUrn formats all documented in the schema itself. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Fetch the comment thread on a LinkedIn post.' That is enough to distinguish it from linkedin_get_post_reactions and linkedin_get_profile_comments, which operate on different object types, though 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?

The description gives no when-to-use or when-not-to-use guidance and names no alternative. It does not say, for example, to use linkedin_get_post_detail for the post body or linkedin_get_profile_comments for a person's comments, so the agent has to infer the boundary from the tool name and schema 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, destructiveHint=false and openWorldHint, so "read-only: returns public data and changes nothing" largely repeats structured data. The one genuinely new fact is the cost (1 credit per request), which annotations do not cover and is useful for budgeting, but return shape and failure modes (invalid slug, private page) go unstated.

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 action front-loaded and no filler. The middle sentence is partly redundant with the read-only annotation, which is the only minor 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?

For a single-parameter, non-destructive lookup with no output schema, the definition covers purpose, safety and cost adequately. A note on what company fields are returned or what happens for an unknown slug would make it fully complete.

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

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

Schema description coverage is 100% and the schema already explains that universalName accepts either a bare slug or a full linkedin.com/company/ URL with examples. The description's "by company slug" adds nothing beyond that, so the baseline of 3 applies.

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

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

"Fetch a LinkedIn company by company slug" gives a specific verb and resource, and the slug-based addressing implicitly separates it from linkedin_search_companies. It does not explicitly name the search sibling or explain how it relates to linkedin_get_posts_from_company, so differentiation is only implied.

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 phrase "by company slug" hints that this is for direct lookup rather than discovery, but the agent must infer that linkedin_search_companies is the path when it only has a company 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, yet the description adds a genuinely new behavioral fact: a cost of 1 credit per request. It also confirms the response is limited to public data, which is useful context. It says nothing about failure modes for invalid or private URLs.

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 purpose front-loaded, followed by the safety profile and the cost. Every sentence carries distinct information and nothing is redundant.

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

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

For a single-parameter read tool with a fully documented schema, the description covers purpose, safety, and billing cost, which is close to sufficient. With no output schema, a brief note on what fields the posting payload contains 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 description coverage is 100%, and the schema itself spells out accepted formats (full URL, numeric id, search link with currentJobId). The description adds no parameter detail beyond "by URL", 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?

"Fetch a LinkedIn job posting by URL" gives a specific verb and resource and the "by URL" scope implicitly separates it from linkedin_search_jobs, which discovers jobs rather than retrieving a known one. It stops short of naming that sibling explicitly, 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?

Usage is only implied: the agent must infer that this is the tool for a job whose URL/id is already known, and that linkedin_search_jobs is the discovery path. No when-not-to-use or alternative routing is written out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so "Read-only: returns public data and changes nothing" largely restates what the structured fields say. The credit cost ("Costs 1 credit per request") and the public-data-only scope are genuinely new behavioral facts the annotations do not carry. Missing is anything about failure modes for private/deleted posts or rate limiting.

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 filler, with the action and keying constraint front-loaded and the cost disclosure last. Nothing could be cut without losing information.

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

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

For a one-parameter read tool with full annotation coverage, the definition covers action, input key, safety profile, and cost. The one gap is that with no output schema, nothing tells the agent what a fetched post contains (author, text, metrics), leaving it to discover the return 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?

The single parameter is fully documented at 100% schema coverage, including the accepted urn:li:activity:<id> form and post-link alternative. The description adds only the notion of being keyed by URN, which the schema already states in more detail, 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?

"Fetch a single LinkedIn post by URN" gives a specific verb (fetch), a specific resource (a single post), and a keying constraint (by URN). This implicitly separates it from linkedin_search_posts and the list-style siblings, but the description never names those alternatives, 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 phrase "by URN" implies the tool is for when the caller already holds an activity URN or post link, which is useful selection context. However, there is no explicit statement of when to prefer this over linkedin_search_posts or linkedin_get_posts_from_profile, and no mention of what data is unavailable (e.g., comments, reactions) that would route the agent to linkedin_get_activity_comments or linkedin_get_post_reactions.

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 'read-only... changes nothing' sentence largely restates structured data. However, the credit-cost model ('1 credit per result returned, minimum 1 per request') is genuinely new behavioral context an agent needs before choosing a large `count` value, which is real added value.

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

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

Three short sentences: purpose first, safety second, cost third. Nothing is padded or repeated, 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?

With no output schema, the description must convey what comes back, and it only says 'returns public data' and 'members who reacted' without indicating the fields or whether reaction type is included. Cost and read-only behavior are covered, but the return shape and pagination limits remain unspecified.

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 activityUrn, count and start are already fully documented with formats and ranges, making 3 the baseline. The description adds only an indirect cost implication for `count`, with no mention of how `start` interacts with the credit charge or of a practical pagination ceiling.

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

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

States a specific verb and resource ('List the members who reacted to a LinkedIn post'), which cleanly separates it from linkedin_get_activity_comments and linkedin_get_profile_reactions by resource type. It stops short of naming those siblings explicitly, so the differentiation relies on the tool name rather than the prose.

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

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

The use case is inferable from the name and description, but there is no explicit statement of when to pick this over linkedin_get_profile_reactions or linkedin_get_post_detail, and no prerequisites such as needing a valid activity URN. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so 'Read-only: returns public data and changes nothing' mostly restates them. However, the description adds genuinely new and operationally important behavior not present in the annotations: a cost of 1 credit per result with a minimum of 1 credit per request, which directly affects how an agent should size the count parameter.

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 purpose front-loaded and cost information placed immediately after, so the agent reads the important constraint before calling. The read-only sentence is partly redundant with the annotations, which is the only wasted text.

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

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

With no output schema, the description never indicates what a returned post contains (text, timestamps, engagement counts, pagination cursor behavior), and 'returns public data' is too vague to fill that gap. For an otherwise simple, well-annotated list tool with fully documented parameters, the missing return-value framing is the main shortfall.

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

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

Schema description coverage is 100%, and the schema already documents count (1-100, default 10), start (skip offset) and universalName (accepting either a short name or a full LinkedIn URL). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb and resource: 'List posts published by a LinkedIn company', which is clearly distinct from linkedin_get_posts_from_profile and linkedin_search_posts by entity type. It does not explicitly name those siblings, so it stops short of full differentiation.

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

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

Usage is only implied: an agent can infer this is the tool for pulling posts from a known company, versus linkedin_get_post_detail for a single post or linkedin_search_posts for discovery. There is no explicit when-to-use or when-not-to-use guidance, nor any stated prerequisite (e.g., needing a company identifier rather than a person).

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 "Read-only... changes nothing" sentence mostly restates them. The genuinely additive piece is the billing trait – 1 credit per result with a minimum of 1 per request – which is cost behavior no annotation conveys.

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 purpose, then safety, then cost – no filler or hedging. Each sentence contributes a distinct piece of information an agent needs before calling.

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 for describing what comes back, and it only says "returns public data" without indicating the post fields or the presence of nextCursor. The credit and paging mechanics are covered by the schema and billing sentence, but the return payload remains underspecified for a list tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the example publicId format and the cursor chaining instruction. The description adds no further meaning about parameter interactions (e.g., cost scaling with count) beyond what the schema and billing sentence imply.

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 ("List posts published by a LinkedIn profile"), which an agent can immediately separate from linkedin_get_posts_from_company or linkedin_search_posts by the "profile" scope. It stops short of naming those alternatives explicitly, so the differentiation is inferable 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?

Usage is only implied: the agent can infer this is for pulling a known profile's post history, and the cost sentence hints at deliberate scoping. There is no explicit when-not clause, no mention of switching to linkedin_get_post_detail for a single post, and no guidance on choosing count or paging depth.

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, destructive, and openWorld, so the safety profile is known. The description adds genuinely new behavioral facts: the operation reads public data only, and it costs 1 credit per result with a 1-credit minimum per request — a cost model an agent cannot find anywhere in the structured fields.

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

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

Three short sentences: purpose first, then the read-only guarantee, then the pricing constraint. Nothing is redundant or buried, and each sentence contributes a distinct fact.

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

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

For a three-parameter, read-only list tool with no output schema, the description covers purpose, safety, and billing, while the schema fully documents inputs and pagination. It stops short of describing what a returned comment contains (post context, timestamps, counts), which would help an agent judge result usefulness.

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, and publicId all self-documented including range, default, and pagination advice. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List comments made by a LinkedIn profile'), which lets an agent distinguish it from linkedin_get_post_detail or linkedin_get_posts_from_profile. It does not, however, explicitly separate itself from the closely-named sibling linkedin_get_activity_comments, so the agent must infer the difference.

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 agent must infer from the name that this is for comments authored by a user rather than comments on a given post, which is a real ambiguity among the LinkedIn 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 'read-only: returns public data and changes nothing' largely restates them. The one genuinely additive fact is 'Costs 1 credit per request', an operational cost trait that structured fields do not carry. Return shape and failure modes (e.g. private/invalid slug) remain undisclosed.

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

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

Three short sentences, front-loaded with the purpose, then safety, then cost. Nothing is wasted and there is no redundant phrasing.

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

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

For a single-parameter, non-destructive read with full schema coverage, the definition covers purpose, safety posture and cost. The main remaining gap is that no output schema exists and 'public data' is vague about which fields come back, which slightly weakens agent planning.

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

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

Schema coverage is 100% and the parameter description already explains that either a bare slug or a full linkedin.com/in/ URL is accepted. The description only echoes 'slug' and adds no format, validation, or encoding guidance beyond the schema, so baseline 3 applies.

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

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

The description names a specific verb (fetch) and resource (LinkedIn profile) and constrains the input to a profile slug, which naturally separates it from the sibling linkedin_get_company_from_url. It does not explicitly call out that sibling, so the differentiation is inferential 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?

Usage is implied by the phrase 'by profile slug' — an agent knows this applies when it already has an identity. There is no explicit guidance on when to prefer this over linkedin_search_all or the activity/post siblings, and no exclusions or prerequisites are stated.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description nonetheless adds genuinely new behavioral context: the credit cost model ('1 credit per result, minimum 1 per request') and that only public data is returned, which directly affects how an agent sizes the 'count' parameter.

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 purpose, then safety, then cost. Every sentence carries information the agent needs, and there is no redundant restatement of the title or schema.

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

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

With no output schema, the description should convey what a result looks like, but it only says 'returns public data' without indicating that the response is a paginated list of post objects with a nextCursor. The cost and safety context is complete, but the return shape is a gap for a tool with no output 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%, with all three parameters fully documented, including the cursor pagination contract and publicId format examples. The description adds nothing about parameter meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'List posts a LinkedIn member reacted to.' This is distinguishable from siblings like linkedin_get_posts_from_profile (authored posts) and linkedin_get_profile_comments (comments), though it does not explicitly name those alternatives. An agent can still infer the difference from the wording.

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

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

Usage is implied by the name and description but never stated: there is no explicit 'use this when you need reactions rather than authored posts or comments' guidance, and no mention of prerequisites such as whether the target profile must be public. Adequate for a simple lookup, but the routing logic against sibling tools 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?

The read-only/idempotent/non-destructive behavior is already fully declared by the annotations, so "Read-only: returns public data and changes nothing" is largely redundant. The credit pricing (1 credit per result, minimum 1 per request) is genuinely new and useful behavioral context not present in the annotations. However, nothing is said about pagination behavior, result caps beyond the schema, or rate limiting.

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 read-only guarantee is front-loaded. It is efficient, though the middle sentence duplicates the annotations rather than spending those words on scope.

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 tool named "search_all" with no output schema, the description must explain what entity types come back, and it does not. The agent is left guessing whether results are profiles, companies, posts or a heterogeneous mix. The pricing note is helpful, but the core scope gap makes the definition incomplete for a 3-parameter cross-entity search.

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 keyword, count (1–10, default 10) and start (skip offset). The description adds no meaning beyond that – no guidance on keyword syntax, boolean operators, or how start interacts with the count cap of 10. Baseline 3 applies when the schema carries the load.

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

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

"Global LinkedIn search" names a verb and platform but never states what is being searched or returned. With siblings like linkedin_search_companies, linkedin_search_jobs, linkedin_search_posts and linkedin_search_schools, the agent cannot tell whether this returns people, posts, or a mix of everything. The scope word "global" hints at breadth but does not resolve the ambiguity.

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

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

There is no when-to-use guidance and no alternative named. Nothing tells the agent whether to prefer this over the many entity-specific LinkedIn search tools, or what query shape suits it. Usage is only implied by the word "search".

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds real value by disclosing the billing model (1 credit per result, minimum 1 credit per request). It does not disclose pagination behavior via `start` or whether results repeat across pages.

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

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

Three short, front-loaded sentences with no filler, and the cost constraint is surfaced early. The opening sentence merely restates the title, which is the only wasted text.

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

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

For a simple three-parameter search with full schema coverage and complete annotations, the description covers purpose, safety and cost, which is nearly enough. It stops short on pagination/paging limits and on how results differ from sibling search tools, which an agent would need to sequence calls 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 keyword, count (1–10, default 10) and start are already documented in the schema; baseline is 3. The description adds only the indirect implication that credit cost scales with `count`, and nothing about search syntax or paging semantics 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 ("Search LinkedIn companies") that an agent can distinguish from read-oriented siblings like linkedin_get_company_from_url. It does not explicitly name the near-neighbor alternatives (search_all, get_company_from_url), so it falls just short of full sibling differentiation.

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

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

The description offers no when-to-use or when-not-to-use guidance: nothing says when to choose this over linkedin_search_all (which likely also returns companies) or over getting a specific company by URL. Usage is only implied by the tool name and the keyword parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered and restating "read-only" earns little. The description does add genuinely new behavior: a credit cost of 1 per result with a 1-credit minimum per request, which affects how an agent should set the count parameter. It stops short of describing pagination or result contents.

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

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

Three short sentences with zero redundancy: purpose first, then safety, then cost. Each sentence carries distinct information an agent needs before calling the tool.

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

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

For a three-parameter read-only search with full schema coverage and rich annotations, the description covers purpose, safety and a cost model that the structured fields do not express. The remaining gap is minor: it does not say what a returned course record looks like or whether the credit cost interacts with the start offset for pagination.

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

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

Schema description coverage is 100%, and each parameter (keyword, count, start) is documented with type, bounds and an example in the schema itself. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

"Search LinkedIn courses" gives a specific verb plus a specific resource, so the agent can tell it apart from linkedin_search_jobs or linkedin_search_companies by subject matter. It does not explicitly differentiate itself from the broader linkedin_search_all, which is the main ambiguity in a dense sibling namespace.

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 states no condition for choosing this tool over linkedin_search_all or any other linkedin_search_* sibling, and offers no exclusions or prerequisites. Usage is only implied by the word "courses".

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 readOnly, idempotent, open-world, and non-destructive behavior, so the description's read-only sentence is largely redundant. What it genuinely adds is the cost model — 1 credit per result with a 1-credit minimum per request — which is operationally important information absent from any structured field.

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, purpose first, then safety, then cost — nothing extraneous and no wasted framing. The read-only sentence duplicates an annotation, but it costs only one short clause and does not bloat the definition.

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

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

For a simple three-parameter search with full schema coverage and no output schema, the description covers purpose, safety, and billing, which is most of what an agent needs. It omits any hint about what an event result contains or how pagination via start behaves, leaving a small 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 keyword, count (1–10, default 10), and start are already fully documented; the baseline of 3 applies. The description adds no parameter-level meaning beyond noting that credits scale with results returned, which indirectly bears on choosing count.

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

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

The description names a specific verb and resource ("Search LinkedIn events"), which is enough to separate it from linkedin_search_posts, linkedin_search_jobs, and linkedin_search_all by resource type. It stops short of explicitly naming a sibling or contrasting scope, so it sits below 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 guidance, no exclusion of alternatives such as linkedin_search_all or linkedin_search_companies, and no stated prerequisite (e.g., that a keyword is required and results are capped at 10). An agent must infer the routing decision and the keyword-only interface entirely from the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the 'read-only, changes nothing' sentence largely restates structured data. The genuinely additive part is the billing behavior — 1 credit per result returned with a 1-credit minimum per request — which is a quota trait unavailable in any structured field and directly relevant to choosing a small count.

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

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

Three short sentences with zero filler, and the identity statement is front-loaded ahead of the safety and cost clauses. Nothing repeats and no sentence is wasted.

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

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

For a simple read-only search with fully documented parameters and rich annotations, the definition is callable and the cost model is a useful addition. It stops short on return shape (no output schema exists, yet the agent is told nothing about the fields of a group result) and on pagination expectations when start is combined with the count cap of 10.

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%; keyword, count (1–10, default 10) and start are all documented with examples and bounds in the schema itself. The description adds no syntax, format or interaction detail (e.g., how start interacts with count for pagination), 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 ('Search LinkedIn groups'), which cleanly separates it from the many sibling search tools (linkedin_search_companies, linkedin_search_jobs, linkedin_search_posts, etc.) by resource noun. It does not, however, say anything about what a 'group' result contains or how this differs from a broader linkedin_search_all call.

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: nothing tells the agent when to pick groups over companies/schools/posts, nor when linkedin_search_all would be preferable. The only conditional information is the credit cost, which is pricing rather than 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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description still adds genuinely new information the annotations lack: per-result credit cost with a one-credit minimum, which matters for planning request volume and the 'count' value. It adds little about result shape or pagination, but the billing disclosure is a real contribution.

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 operation and followed immediately by safety and cost. Nothing is padded and no sentence is wasted.

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

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

With eight well-described parameters, rich annotations, and no output schema, the definition covers what an agent needs to call it and to anticipate cost. The only gap is that result contents and pagination expectations are not described, though 'start' in the schema partially implies paging.

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 eight parameters, including four enums, are documented inline with examples, so the schema does the heavy lifting. The description adds no extra meaning about keyword semantics, filter combination behavior, or how 'count' interacts with 'start' for paging.

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

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

The description states a specific verb and resource ('Search LinkedIn jobs'), so an agent knows exactly what operation this performs. It does not, however, distinguish the tool from nearby siblings such as linkedin_get_job (single job lookup) or linkedin_search_all (broad search), which a stronger definition would name explicitly.

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

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

There is no when-to-use or when-not-to-use guidance. The description never says to prefer this over linkedin_get_job when a job ID is already known, nor how it relates to linkedin_search_all, leaving the agent to infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only sentence is largely confirmation. The genuinely additive disclosure is the pricing model — 1 credit per result with a 1-credit minimum per request — which is cost information an agent cannot get from any structured field and which affects how it should size the `count` parameter.

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 purpose, then safety, then cost — nothing is buried. The middle sentence restates the readOnlyHint annotation almost verbatim, which is minor redundancy but not wasteful enough to undercut the structure.

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

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

With five fully documented parameters, no output schema, and annotations covering the safety profile, the description supplies the one missing operational fact: cost per request. It does not describe what a returned post contains or how pagination via `start` behaves, but there is no output schema to lean on, leaving a small 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%, with every parameter including `count`, `start`, `sortOrder`, `datePosted`, and `keyword` documented inline, including enums and ranges. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Search LinkedIn posts"), so an agent immediately knows the operation. It does not, however, distinguish this tool from close siblings such as linkedin_search_all, linkedin_get_posts_from_company, or linkedin_get_posts_from_profile, which could also surface posts.

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

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

Usage is only implied by the verb "Search" — there is no explicit statement of when this keyword-based post search is preferred over linkedin_search_all or the profile/company post-listing tools. No exclusions, prerequisites, or alternative names are provided.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the restatement "returns public data and changes nothing" adds little. However, the credit cost disclosure (1 credit per result, minimum 1 credit per request) is genuinely useful behavioral context not present in any structured field, and it directly affects how an agent should choose count values. That single addition lifts this above 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 short sentences, front-loaded with purpose then safety then cost. Nothing is padded; every clause either orients the agent or constrains behavior.

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 three-parameter search tool with no output schema, the safety and cost framing is adequate. The gaps are what "products" actually denotes and any hint about result shape or pagination semantics of start; without them the agent knows the price but not the payload.

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%: keyword, count (1–10, default 10), and start are all documented with examples and bounds. The description adds no meaning beyond the schema – notably it never connects its per-result credit cost to the count parameter, which would have been a valuable linkage. 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 verb and resource ("Search LinkedIn products"), but "products" is ambiguous in a LinkedIn context – it could mean company product pages, LinkedIn's own product catalog, or generic results. It offers no differentiation from close siblings like linkedin_search_companies, linkedin_search_services, or linkedin_search_all, so an agent cannot confidently choose it on purpose alone.

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

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

No when-to-use guidance and no mention of alternatives, despite at least ten linkedin_search_* siblings. The reader must infer from the name alone whether this overlaps with linkedin_search_all or the entity-specific searches.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral information not in the annotations: it returns public data only and consumes 1 credit per result with a minimum of 1 credit per request, which matters for cost-aware agents. It stops short of describing result shape or pagination interaction with 'start'.

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 purpose, followed by safety and pricing. Nothing is wasted, though the read-only claim partially restates what the annotations already say.

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

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

There is no output schema, so the description cannot be expected to explain return values in depth. Combined with the fully documented three-parameter schema and complete annotations, the credit-cost disclosure fills the main remaining gap an agent would need before calling it.

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

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

Schema description coverage is 100% and each of keyword, count and start is documented in the schema itself. The description adds no parameter-level meaning 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?

The description states a specific verb and resource ('Search LinkedIn schools'), which an agent can distinguish from siblings like linkedin_search_companies or linkedin_search_jobs by the resource noun alone. It is clear but does not explicitly contrast itself with those siblings.

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

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

There is no when-to-use guidance, no mention of when not to use it, and no reference to the many adjacent search tools (linkedin_search_all, linkedin_search_companies, linkedin_search_courses). The agent must infer selection purely from the noun 'schools'.

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 operational context: public-data-only results and a credit cost of 1 per result with a 1-credit minimum per request. It stops short of describing pagination behavior or result shape, but this is solid supplemental disclosure.

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 purpose and then the behavioral facts. "Returns public data and changes nothing" mildly duplicates readOnlyHint, but nothing is bloated and no sentence is wasted on 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?

The credit-cost disclosure is important for a metered search tool, and annotations cover the safety profile. However, with no output schema the description says nothing about what a result contains, and it omits any differentiation from the many sibling LinkedIn search endpoints. Adequate but with clear gaps for a tool in a crowded family.

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%; keyword, count (1-10, default 10) and start (offset) are fully documented in the schema. The description's "1 credit per result returned" implicitly ties cost to the count parameter, which is a small value add, but it is never explicitly connected to count or to how repeated `start` pages are billed.

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

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

The first sentence, "Search LinkedIn services," essentially restates the tool name and title without defining what a LinkedIn "service" is. With siblings like linkedin_search_companies, linkedin_search_products, and linkedin_search_jobs, the agent gets no basis for distinguishing this resource from those. The verb and surface are clear, but the object is vague.

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 named, despite nine sibling linkedin_search_* tools that plausibly overlap. The agent must infer selection from the tool name alone. Nothing is misleading, but no routing help is 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, openWorldHint=true, and destructiveHint=false, so "read-only: returns public data and changes nothing" mostly restates structured data. The credit cost ("Costs 1 credit per request") is genuine added context not present in annotations. What "with its thread" actually returns — parent post, ancestor comments, replies — is never disclosed, and there is no output schema to fill that gap.

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 action and followed by the two facts an agent most needs (safety and cost). The clause "changes nothing" is redundant with readOnlyHint, but the whole description is tight and wastes little.

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

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

With no output schema, the description carries the burden of explaining what comes back, and "with its thread" is too vague to tell an agent whether it gets the parent post, the ancestor chain, or replies. Cost and read-only semantics are covered, but the shape of the result is not.

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

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

Schema description coverage is 100%, and the schema already explains both the permalink formats (absolute URL or site-relative path) and the sort enum plus its default. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

Names a specific verb and resource ("Fetch a single Reddit comment with its thread"), which separates it from list/search siblings like reddit_list_subreddit_comments and reddit_search_comments. It stops short of explicitly distinguishing itself from reddit_get_post, so the boundary between the two 'get' tools is left implicit.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are named. An agent holding a comment permalink can infer the use case, but nothing tells it whether to reach for reddit_get_comment versus reddit_get_post or reddit_search_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, destructiveHint=false, and openWorldHint, so the sentence 'Read-only: returns public data and changes nothing' largely restates structured data and earns little credit. The one genuinely new piece of behavioral information is the cost model — 'Costs 1 credit per request' — which no annotation or schema field conveys and which matters for an agent deciding whether to call repeatedly.

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

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

Three short sentences, front-loaded with the core action, with no filler or hedging. The second sentence is largely redundant against the annotations, which is the only thing 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?

There is no output schema, so the description is the only place an agent could learn what comes back — yet it says nothing about the shape of the response, such as which post fields are returned, how deeply comments are nested, or whether comment pagination/truncation occurs. For a two-parameter read tool this is an acceptable but noticeable 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%, with both url (including example formats and redd.it short-link support) and sort (enum plus default behavior) fully documented in the schema. The description adds no additional meaning about parameters, 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?

The description states a specific verb and resource — 'Fetch a Reddit post with its comments' — which is clearer than the bare tool name and signals that comments come bundled. It does not, however, explicitly distinguish itself from nearby siblings like reddit_get_comment or reddit_list_subreddit_posts, so the agent must infer the boundary from the name alone.

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

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

Usage is only implied: the required url parameter combined with 'Fetch a Reddit post' suggests this is the tool for retrieving one specific post when you already have its link. There is no explicit when-to-use versus reddit_get_comment, reddit_search_posts, or reddit_get_subreddit, and no stated preconditions or failure cases (private, deleted, or quarantined 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so 'Read-only: returns public data and changes nothing' largely restates structured data. The one genuinely additive fact is the cost model ('Costs 1 credit per request'), which is not encoded anywhere else. Missing: behavior on nonexistent/private/banned subreddits and any rate-limit context.

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

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

Three short sentences with the purpose front-loaded and no filler. The middle sentence duplicates the readOnly/idempotent annotations, which is mild waste given the structured fields already say it.

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

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

There is no output schema, yet the description never indicates what 'metadata' includes (subscriber count, description, creation date, NSFW flag, etc.), leaving the agent unable to predict the return shape. The credit cost and read-only nature are covered, so it is adequate but with a clear gap for a lookup tool whose payload is undefined.

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

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

Schema coverage is 100% and the single parameter's description already covers the 'r/' prefix and full-URL forms with concrete examples. The tool description adds no meaning 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 (fetch subreddit metadata), which is distinguishable from the sibling list/search tools such as reddit_search_communities and reddit_list_subreddit_posts. It does not explicitly name which sibling to use instead when the goal is discovery rather than lookup, so it stops short of full differentiation.

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

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

The description contains no when-to-use or when-not-to-use guidance. It never says to call this after resolving a name via reddit_search_communities, nor does it clarify the boundary with reddit_list_subreddit_posts or reddit_get_post. Usage is only inferable 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the description's 'read-only, changes nothing' mostly restates that. However, it adds genuinely new information not present in structured fields: the request costs 1 credit, and the data returned is public. That credit cost is the key behavioral trait an agent needs for budgeting.

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

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

Two short sentences with zero filler, front-loaded with the operation and followed by the safety and cost facts. Nothing could be removed without losing information.

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

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

For a one-parameter, read-only fetch with no output schema and rich annotations, the description covers what matters: the operation, safety profile, data sensitivity, and credit cost. It lacks any note on failure behavior for unknown or suspended users, which is the only meaningful 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% and the single username parameter is already documented with accepted formats (bare name, 'u/' prefix, or full profile URL). The description adds no extra meaning about that parameter, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Fetch a Reddit user profile'), so an agent immediately knows the operation. It does not explicitly distinguish itself from siblings like reddit_list_user_posts or reddit_search_users, but the verb-noun combination is specific enough that confusion is unlikely.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., needing an exact username), and no routing to alternatives such as reddit_search_users for discovering a username. Usage is only implied by the tool name and title.

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 read-only and non-mutating statements largely repeat the annotations. However, the description adds useful operational context beyond them: the results are public data and each request costs 1 credit.

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-load the purpose and then convey data scope, safety, and cost. The definition is compact and easy to scan without unnecessary parameter recitation.

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 three-parameter read-only listing tool, the description, annotations, and fully documented schema provide enough information to invoke it correctly. Explicit sibling routing and some indication of the response shape would improve completeness, particularly because no output schema is supplied.

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

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

The schema fully documents all three parameters, including accepted subreddit formats, the count range and default, and cursor-based pagination. The description adds no parameter meaning beyond that coverage, so the baseline score 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 opening sentence specifies the action, resource, and scope: listing recent comments within a subreddit. This broadly separates it from post and user-comment tools, but it does not explicitly distinguish it from close alternatives such as reddit_search_comments or reddit_list_user_comments.

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

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

The subreddit and recency scope imply when the tool is useful, but there is no explicit when-to-use or when-not-to-use guidance. The agent must infer when to choose this tool rather than searching comments or listing a user's 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, and the sentence "Read-only: returns public data and changes nothing" largely restates them. The genuinely additive piece is "Costs 1 credit per request," which is real behavioral context not captured anywhere in structured fields; nothing is said about rate limits, auth, or 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 very short sentences are front-loaded and waste little, but the title is repeated verbatim as the first sentence and the read-only line duplicates annotation data, so roughly two of the three sentences add little that structured fields don't already convey.

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

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

With no output schema, the description should hint at what comes back (post objects plus a nextCursor for paging) since the cursor parameter only makes sense in that context. Annotations cover the safety profile and the schema covers inputs, so the tool is usable, but the return-side and cost-per-page implications are 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 sort, time, count, cursor and subreddit are all documented with enums, defaults and bounds in the schema itself. The description adds no meaning beyond that, making the baseline 3 correct.

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?

"List posts in a subreddit feed" gives a specific verb and resource, and the subreddit-scoped nature distinguishes it in practice from reddit_search_posts and reddit_list_user_posts. It never names those siblings, though, so the differentiation must be inferred from the tool name 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 scope implies when to reach for this tool (enumerating a community's feed rather than searching or fetching a single post), but there is no explicit when-to-use, when-not-to-use, or pointer to reddit_search_posts / reddit_get_subreddit. The credit-cost note gives a budgeting cue but not behavioral 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?

The annotations already declare readOnlyHint=true, so the description does not need to re-establish safety. It does add genuinely useful behavior beyond them: an empty list is returned when the user has no tweets, and pagination is cursor-driven. It omits permission/auth requirements, rate limits, and whether deleted or protected accounts alter 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, front-loaded with the core purpose and free of filler. Minor structural weakness: the empty-result and pagination notes are appended as separate fragments rather than consolidated, but nothing is redundant.

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

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

The description never says how the 'specific user' is identified, and the schema exposes no visible parameters, so an agent has no documented way to bind the user or the cursor it is told to use. For a list/pagination tool with no output schema, this leaves the calling contract underspecified.

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

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

With no documented parameters in the schema, the 4 baseline applies and the description does not need to explain parameter meaning. It actually gives one piece of parameter-adjacent guidance by tying `cursor` to pagination. It adds no clarification of how the target user is identified, which is the one detail an agent would want.

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: 'Get tweets posted by a specific user.' That is clearer than the bare name and distinguishes it from reply/media siblings by scoping to posted tweets. It stops short of naming an alternative tool, so it lands at 4 rather than 5.

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

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

The only usage instruction is 'Use `cursor` to paginate through results,' which is mechanical paging advice, not routing guidance. Nothing tells the agent when to prefer this over x_search, x_get_user_replies, or x_get_user_media, and there are no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the sentence 'Read-only: returns public data and changes nothing' largely restates structured data. The one genuinely additive detail is the per-request credit cost. Nothing is said about pagination behavior despite a cursor parameter, or about how posts and comments are interleaved in the result.

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

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

Two short sentences, front-loaded with purpose before the safety and cost notes. Efficient overall, but the read-only clause duplicates the annotation profile and could have been spent on pagination or result-shape information instead.

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 five-parameter listing tool with strong annotations and no output schema, the description is nearly complete. The remaining gap is that it never mentions the cursor-based pagination exposed in the schema or what a result item contains, which matters for a paged mixed feed.

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

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

Schema description coverage is 100%, so all five parameters including sort, time, count and cursor are fully documented in the schema with enums and defaults. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource: lists a Reddit user's mixed post/comment activity. The word 'mixed' implicitly distinguishes it from siblings reddit_list_user_posts and reddit_list_user_comments, which each return one content type, though 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: an agent can infer this is the right tool when it needs both posts and comments for a user in one call rather than the type-specific siblings. There is no explicit when-to-use statement, no exclusion, and no mention of how it relates to reddit_get_user or reddit_search_all.

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 read-only/no-mutation claim merely restates readOnlyHint and destructiveHint=false, earning no credit. The genuinely new disclosure is "Costs 1 credit per request," which is real behavioral context absent from the annotations. Nothing is said about pagination limits or rate limiting beyond the per-request cost.

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 purpose, with no filler or hedging. The read-only sentence is largely redundant with the annotations, which is the only 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?

For a simple list tool with full schema coverage and complete annotations, the essentials are present, and the credit cost is a useful addition. However, with no output schema there is no statement of what post fields come back, and pagination behavior via cursor is 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 (username formats, count bounds, sort/time enums, cursor) is already fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline of 3 when the schema carries the load.

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

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

States a specific verb and resource ("List a Reddit user's posts"), which is enough to separate it from reddit_list_user_comments and reddit_get_user by resource semantics. It does not explicitly name or contrast with any sibling, 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?

No when-to-use, when-not-to-use, or alternative routing is given. An agent must infer on its own whether to pick this versus reddit_list_user_overview, reddit_list_user_comments, or 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the restated "Read-only: returns public data and changes nothing" is largely redundant. The credit-cost disclosure ("1 credit per request") is genuine added context not present in any structured field, which lifts this above the annotation-covered 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?

Two short sentences, front-loaded with purpose, then safety, then cost. No filler or repeated phrasing beyond the mild redundancy of restating read-only.

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

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

For a five-parameter search with full schema coverage and rich annotations, the description covers purpose, safety and cost adequately. The main omission is the absence of any output schema and no hint at result shape or how the three entity types are returned/paginated, though cursor pagination is 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%, including enum values, defaults and the note that subreddit only applies to post search, so the schema does all the parameter work. The description adds no parameter meaning of its own; baseline 3 applies.

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

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

The description names a specific verb and resource ("Search Reddit") and states its scope across posts, communities and users. However, it never distinguishes itself from the closely named siblings reddit_search_posts, reddit_search_comments, reddit_search_communities and reddit_search_users, which an agent must choose between.

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 "across posts, communities and users" implies a broad, cross-entity search versus the narrower sibling searches, but the description never says when to pick this over those alternatives or how results across entity types are combined. Usage guidance is only inferable, not 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 readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only: returns public data and changes nothing" largely restates structured data. The credit-per-request cost note is genuinely useful context not present in annotations, but the description says nothing about pagination behavior or result limits despite exposing a cursor parameter.

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 front-loaded sentences with no waste, and the core verb+resource leads. The middle sentence slightly duplicates what the annotations already declare, 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?

Adequate for a simple search tool with full schema coverage and rich annotations, but incomplete for a paging-capable search: nothing explains result volume, cursor semantics, or how comment results differ from post results. The subreddit parameter's own note that it only applies to post search is left unaddressed by the description.

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?

Baseline is 3 given 100% schema coverage, but the description earns above that by flagging the cost per request, which affects how an agent should use the cursor and query broadly. Additionally, the schema itself carries rich enum and default documentation that the description need not repeat.

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

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

States a specific verb+resource ("Search Reddit comments") that clearly distinguishes it from reddit_get_comment (single comment fetch) and reddit_list_subreddit_comments (enumeration). However, it does not explicitly name any sibling as an alternative, so differentiation is inferred from names alone.

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

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

The description offers no when-to-use guidance, no exclusions, and no routing to alternatives such as reddit_search_posts or reddit_search_all. An agent must infer from the tool name that this searches comment bodies rather than post titles.

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, openWorldHint, and destructiveHint=false, so the sentence 'Read-only: returns public data and changes nothing' largely duplicates structured metadata. The one genuinely additive fact is the credit cost ('Costs 1 credit per request'), which is not expressible in annotations, but nothing is said about result limits, ranking, or 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 short sentences, front-loaded with purpose and then behavior and cost, with no filler. The opening sentence is redundant with the title rather than wasteful in length.

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

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

With a 100%-documented schema and annotations covering the safety profile, the description is complete enough for an agent to call the tool correctly. It lacks any note about the cursor-based pagination flow or what a community result contains, but no output schema exists to lean on, leaving a modest 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 all five parameters, including the sort/time enums and the cursor, are already documented in the schema, which sets the baseline at 3. The description contributes no additional meaning about how query text is matched or how relevance sorting works.

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 sentence 'Search Reddit communities' gives a verb and a resource but is effectively a restatement of the title, so it adds little. It never clarifies that 'communities' means subreddits, nor distinguishes itself from reddit_search_all, reddit_search_posts, or reddit_search_users, which sit right beside it in the sibling list.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative. An agent must infer on its own that reddit_search_all is the broader tool and that reddit_search_posts searches content rather than communities.

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 openWorldHint, so "read-only: returns public data and changes nothing" largely restates structured data. The genuinely additive fact is the per-request credit cost, which is real decision-relevant context but is the only piece of it.

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

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

Three short, front-loaded sentences with no filler, and the cost note is placed where it will be read. The read-only sentence is redundant with annotations, slightly reducing the value of the space it occupies.

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 five well-documented parameters and no output schema, the description covers the basics but omits how results are scoped compared with search_all/search_comments and says nothing about result volume or pagination beyond what the cursor field already states. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and both enums (sort, time) are documented inline, so the schema carries parameter semantics fully. The description adds no further meaning about query syntax, pagination or filtering behavior.

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

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

The description states a specific verb and resource ("Search Reddit posts"), which is unambiguous on its own. However, it never distinguishes itself from close siblings such as reddit_search_all or reddit_list_subreddit_posts, so an agent must infer the boundary from the name alone.

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

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

There is no guidance on when to use this tool versus its many siblings, nor any exclusions or prerequisites. The only contextual cues (subreddit filter, sort order) live in the schema, not the description.

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