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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds real behavior: it combines repo profile data, anti-pattern matching, and success pattern analysis, and discloses the exact response keys and the diff_stat dependency for impact/review. It stops short of noting limits such as cost, latency, or behavior on missing optional inputs.

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

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

Front-loads purpose, alternative, and return shape before the Args list, which is well organized. The Args section partly restates the schema, but each entry adds format or default semantics that justify its place.

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

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

With no output schema, the description supplies the return keys and the diff_stat caveat, plus an example call and response. For an 11-parameter read-only analysis tool this is nearly complete, though it does not describe how optional defaults (e.g. mergeable='MERGEABLE') affect results.

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

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

Schema coverage is 0%, so the description carries the full burden and does it well: it defines formats and sentinel semantics for star_count (0 = unknown), repo_merge_rate (0.0-1.0, 0 = unknown), mergeable enum values, author_association enum values, labels as a string array, and flags diff_stat as the authoritative PR-size signal. This meaningfully exceeds the bare 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 (detailed PR analysis) and immediately differentiates from the sibling coach_pr by intent (deep analysis vs quick pass/fail). Also names what it produces: tier, signals, checklist, recommended_action.

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

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

Explicitly names the alternative (coach_pr) with the selecting condition, and gives a concrete when-to-use scenario: before submitting a PR to a large open-source repo. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds real value beyond that by disclosing what work happens internally (profile analysis + anti-pattern matching + policy checks) and the branch semantics of the return value (pass=true safe to submit, pass=false blocking issues). It does not mention latency, data sources, or failure modes, so it stops short of a 5.

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

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

Front-loaded with the routing sentence and final output semantics before the Args list, which is justified at length given 0% schema coverage. Minor redundancy: 'quick pass/fail gate,' 'go/no-go decision,' and 'final gate' restate the same idea across three sentences, and the Returns line partly duplicates the pass=true/false sentence.

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

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

With no output schema, the description steps in to describe the returned dict (pass, tier, signals, checklist, recommended_action), and it covers all 11 inputs at a useful level. It is complete enough to invoke correctly, though it lacks guidance on required vs optional inputs and on what the 'tier'/'signals' values mean.

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% across 11 parameters, so the description carries the full burden and largely meets it: it gives ranges and accepted values (repo_merge_rate 0.0-1.0, star_count >= 0, mergeable MERGEABLE/CONFLICTING/UNKNOWN, author_association NONE/CONTRIBUTOR/etc.) and explains the role of diff_stat. It falls short of 5 because the body vs description split is ambiguous ('PR body/description' vs 'Extended description') and it never indicates which params drive the decision.

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 ('quick pass/fail gate' for a PR) and immediately distinguishes itself from the sibling analyze_pr by contrasting go/no-go with detailed analysis. It also enumerates the inputs it combines (repo profile analysis, anti-pattern matching, maintainer policy checks), so an agent understands exactly what this tool produces without opening a schema.

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

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

It names the moment to use it ('final gate before opening a PR') and the explicit alternative plus its selection condition ('analyze_pr for detailed analysis'). This is the clearest possible routing guidance in a one-line form.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds useful behavioral context: the deterministic mapping from analyze_pr signals to a fixed set of 5 named action outcomes, plus the version. It does not disclose whether inputs need a live PR, latency, or failure modes, so it is informative but not rich.

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

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

Purpose and output questions are front-loaded, and the Args/Returns sections are scannable. The 15-key Returns list is somewhat long, but with no output schema it is justified rather than padding.

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

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

For a 10-parameter tool with no output schema and no annotation-gap in the safety domain, the description supplies both the argument inventory and the return-key inventory, so an agent knows what it will get back. The main residual gap is the ambiguous body/description parameters and the absence of any live-input requirement note.

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

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

Schema coverage is 0%, so the description must carry the parameter burden, and it does enumerate all 10 args. But most entries are near-tautological (title='PR title', author='PR author username'), and the body vs description distinction ('PR body' vs 'Extended description') is left ambiguous. It adds format hints only for repo (org/name) and author_association, so it partially compensates for the coverage gap.

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 ('action decision for a single PR') and immediately enumerates the exact 5 actions produced. The 'contributor-facing' framing cleanly distinguishes it from the maintainer_view sibling, so an agent can pick between them without opening schemas.

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

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

The quoted questions ('Is my PR ready to submit? What should I fix?') imply when a contributor would call it, and the reference to mapping analyze_pr signals hints at its relationship to that sibling. However there is no explicit when-to-use-vs-alternative or exclusion guidance, leaving the choice between contributor_view, analyze_pr, coach_pr and triage_pr to inference.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds details about the return structure (frontmatter, body, path) and error handling, which are beyond the annotations and schema. It is sufficient for a simple retrieval tool.

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

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

The description is concise, with a one-sentence purpose, a brief context statement, and clearly separated Args/Returns sections. Every sentence adds value, and the structure is front-loaded.

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

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

For a tool with 2 simple parameters and no output schema, the description covers the core functionality and return format. It mentions error handling ('or error if not found'). An example would be nice but is not essential given the simplicity.

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

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

The input schema has no descriptions (0% coverage), so the description compensates by explaining 'repo: Repository in org/name format' and 'pr_number: PR number (integer)'. This adds meaningful guidance beyond the bare schema.

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

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

The description clearly states it retrieves a specific PR case study with full details and rounds, distinguishing it from sibling tools like list_open_prs (which lists PRs) and search_patterns (which searches patterns). The verb 'get' and resource 'case study' are specific and unambiguous.

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

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

The description indicates it is useful for learning from past PR experiences, providing context for when to use. While it lacks explicit when-not-to-use or alternative tools, the purpose is clear enough to differentiate from 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 destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by stating that it returns repository metadata plus agent_guidelines, and that an error is returned if the repo is not found, which goes beyond what the annotations or schema provide.

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

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

The description is front-loaded with a clear one-sentence summary, followed by useful return details and a concise Args/Returns structure. Every sentence contributes meaningful information without redundancy or 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?

With one parameter, no output schema, and comprehensive annotations, the description covers everything needed: input format, what fields are returned, a usage scenario, and error behavior. There are no critical gaps for an agent to call this tool correctly.

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

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

The schema provides only the parameter name and type with no description, but the description fully compensates by specifying the required format: 'Repository in org/name format (e.g. "encode/httpx")'. This is exactly the semantic information an agent needs to invoke the tool correctly.

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

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

The description clearly states a specific verb and resource: it gets a repository profile with maintainer guidelines, AI policy, and merge rate. It names concrete fields returned, making the tool's purpose unmistakable, though it does not explicitly differentiate it from sibling tools.

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

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

The description gives explicit context for when to use the tool: 'Use this to understand a repo's contribution culture before submitting a PR.' It does not mention exclusions or when to prefer a sibling tool, but the context is clear enough for an agent to select it appropriately.

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/non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it clarifies the records are local case-study folders with final_status=open rather than live data, and specifies the return fields. It does not cover pagination or ordering, so it falls just short of the top.

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

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

Front-loaded with the core purpose, then a NOTE for the critical disambiguation, followed by scannable Args/Returns blocks. Every line earns its place with no filler.

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

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

No output schema exists, so the description correctly spells out the returned fields ({repo, pr_number, pr_url, author, folder}). Combined with annotations covering safety and full parameter documentation, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description must carry the burden — and it does, documenting both params: `repo` filters by target repo with format example 'org/name' and '`""` = all', and `author` filters by PR author username with the same empty-string default semantics.

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

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

States a specific verb and resource ('List open PR case-study records in the local knowledge base') and immediately disambiguates the misleading name by clarifying these are NOT live GitHub PRs. An agent can tell it apart from status_prs without opening the schema.

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

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

Explicitly names the alternative for the other case: 'For live GitHub PR health use `status_prs`.' It gives a clear when-to-use boundary and an exclusion, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully discloses the 5 action outcomes and the decision semantics, but adds nothing about latency, whether repo_merge_rate/labels must be pre-fetched, or failure modes for this 10-param tool.

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

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

Front-loaded with the purpose and action list, which is good, but version/phase trivia ('v1.5.1', 'Phase 5.1') and the verbose Args/Returns blocks add noise an agent does not need. Every sentence about parameters does earn some place given 0% schema coverage, so it is not wasteful overall but is not tight.

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 compensates by enumerating the return dict keys (action, reason, blocking_signals, next_step, review_ready, impact, review, author_info, context), and it covers all input params. Sufficient for correct invocation, though it never explains what the required vs optional split means or how missing optional inputs affect the action.

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

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

Schema description coverage is 0%, so the description carries the full burden and does document all 10 args, including non-obvious detail: repo as org/name, author_association values, repo_merge_rate as 0.0-1.0, and a diff_stat format example. It omits semantics for description vs body overlap and the effect of defaults, keeping it short of a 5.

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

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

States a specific action-decision role for a single PR and frames the output question ('What should I do with this PR right now?'), which is distinctive among siblings. It names analyze_pr as the upstream signal source, but does not distinguish itself from triage_pr, coach_pr, or contributor_view, which sound adjacent.

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 'Maintainer-facing action decision' framing implies the maintainer-side use case and mentions the analyze_pr dependency, giving usable context. However, there is no explicit when-to-use/when-not or routing to triage_pr/coach_pr/review_queue for the overlapping workflows, so the agent must infer selection.

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

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

With annotations already covering the safety profile (readOnly, idempotent, non-destructive), the description goes further and enumerates the concrete checks performed (versions, KB readability/coverage, gh CLI, MCP registration, sample analyze, warnings). Since there is no output schema, spelling out the return dict keys is genuinely additive behavioral 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?

Purpose and precondition are front-loaded in two tight sentences. The 'Returns' block is somewhat long, but each key listed is load-bearing given no output schema exists, so the length is largely earned.

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-param diagnostic with no output schema, the description supplies both the invocation precondition and the shape of the result (ok, versions, kb, gh, mcp, sample, warnings). Nothing an agent needs in order to call or interpret it is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument invocation and has no parameter semantics to get wrong.

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 ('Self-test the pr-genius install') and instantly separates itself from the analysis siblings by framing itself as a pre-flight health check. Nothing about what it does is left ambiguous.

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

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

Explicitly prescribes the usage condition: 'Run this before trusting analyze_pr output.' That names the sibling whose reliability it gates, which is exactly the routing signal an agent needs to pick this tool over analyze_pr or status_prs.

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 safety is covered. The description adds value beyond that by disclosing the output structure (field, value, repo, evidence, source, confidence, private) and the auto-mode confidence threshold, which tells the agent what the results mean.

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

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

Front-loads the purpose before the Args/Returns blocks, and every sentence carries information. The Args/Returns formatting slightly duplicates what a schema would normally hold, but given 0% schema coverage it earns its place.

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

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

With no output schema, the Returns section is essential and present. Parameter behavior and thresholds are documented. Only the default mode value and any permission/pagination considerations are missing, which is minor for a two-parameter read tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning — and it does: author is a GitHub username, and mode's two values are defined with the 0.8 confidence cutoff. This compensates well for the empty schema, though it doesn't state the default value ('suggest') that the schema declares.

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 profile writeback suggestions') and names the basis ('PR status analysis'), with an example of the fields suggested. It does not explicitly differentiate itself from siblings like analyze_pr or get_repo_profile, so it stops short of a 5.

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

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

The mode parameter is explained with a concrete selection rule ('suggest' = all, 'auto' = confidence >= 0.8), which implies usage. However, there is no guidance on when to call this tool versus analyze_pr, get_repo_profile, or other profile/PR 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/destructiveHint, so the safety profile is covered. The description adds genuine context beyond that: the grouping behavior (5 action classes), the two output forms, and a full enumeration of the returned dict keys, which matters since there is no output 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?

Well front-loaded and cleanly sectioned into Args/Returns, with the core purpose stated first. The version tag '(v1.5.0)' is minor noise, but overall it is tight and earns its 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?

For a moderately complex digest-builder with no output schema, the description supplies the return keys, the input field list, and the two output destinations. Missing only the specific 5 action classes and the precedence between prs and prs_file, which are minor 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 0%, so the description must carry the load and it largely does: it documents prs as a list of {repo, number, title, body, author, labels, star_count, repo_merge_rate} and prs_file as an alternative path to a JSON PR list. It does not specify the JSON file's expected shape or how the two inputs interact if both are supplied, but it compensates well for the empty schema.

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

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

The description opens with a specific verb+resource ('Build maintainer review queue digest from a list of PRs') and clarifies the mechanism (groups by maintainer action into 5 classes, emits markdown). It is clearly distinguishable from the per-PR sibling maintainer_view, but it never explicitly names or contrasts any sibling.

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

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

Usage is only implied through the stated output targets ('suitable for Actions summary or git-trackable markdown file'). There is no explicit when-to-use vs. maintainer_view/analyze_pr/triage_pr guidance, no prerequisites, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return scope but no further behavioral context such as caching, response shape, or rate limits, so it neither contradicts nor significantly extends the annotations.

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

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

The description is a single front-loaded sentence with no filler. It directly states the tool's output in a compact way that is easy for an agent to parse.

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

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

For a zero-parameter, read-only metadata tool, the description covers the essential information needed to select and call it. It could be slightly more detailed about the format or structure of the returned schema versions and enum values, but nothing critical is missing.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter semantics to explain. The description accurately focuses on what the tool returns, which is sufficient for invocation.

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

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

The description states a specific verb and resource: it returns supported schema versions and enum values. This is clear and distinct from the sibling tools, though it does not explicitly name a sibling to differentiate itself.

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

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

There is no guidance about when to use this tool versus the sibling tools, nor any mention of prerequisites or context. The intended use is only implied by the purpose statement, so an agent gets no explicit routing support.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context (search, filter, return format) but doesn't introduce new traits beyond what annotations imply.

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

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

The description is well-structured with sections for purpose, usage, args, returns, and examples. It is efficient, though slightly verbose with the example lines; still, every sentence adds value.

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 no output schema, the description explains the return format (list of dicts with specific keys) and provides examples. The tool's complexity is low, and the description is adequate for correct invocation.

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

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

Despite 0% schema coverage, the description fully explains each parameter with examples: query (with keyword examples), pattern_type (options: all, anti-pattern, success-pattern), limit (default 10). This adds significant meaning beyond the schema.

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

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

The description clearly states 'Search anti-patterns and success-patterns by keyword,' providing a specific verb and resource. It distinguishes itself from sibling tools like list_open_prs and get_case_study by focusing on patterns.

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

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

Explicitly says 'Use this to find relevant patterns before submitting a PR,' giving clear context of when to use. It also clarifies the two types of patterns but doesn't explicitly state when not to use, though the context is sufficient.

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 useful context beyond that: the save_snapshot side effect (persisting to data/status-snapshots/) and the explicit rationale for defaulting it False (frequent MCP polling would flood the directory). It does not explain the transition-detection semantics of the snapshot beyond a one-line mention.

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

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

Front-loaded with the purpose and the status taxonomy, then organized into Args and Returns sections. The 9-status enumeration is long but earns its place by defining the output vocabulary; the 'Returns' line is useful given there is no output schema.

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

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

With no output schema, the description compensates by naming the return keys (prs, ignored, summary, actions, transitions) and the status categories. Params are covered and the snapshot side effect is disclosed, leaving only minor gaps such as parameter optionality and the meaning of 'transitions'.

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%, so the description must carry the burden, and it does: all four params are explained with meaning and format hints ('GitHub username', 'org/name', stale_days defaulting to profile or 14, and the save_snapshot tradeoff). It omits that every parameter is optional with a null default, which the schema technically encodes but doesn't document.

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 ('Check health of in-flight PRs') and quantifies the output (9 named statuses plus suggested actions), so an agent knows exactly what it gets back. It does not, however, differentiate itself from the many related siblings (list_open_prs, triage_pr, review_queue), leaving overlap ambiguous.

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

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

The description never says when to use this tool versus alternatives, despite a crowded sibling set that includes list_open_prs, triage_pr, and review_queue. The 'outbound PR heartbeat' phrase hints at context but offers no when/when-not condition or prerequisite.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds genuine behavioral context: it reads a per-org/repo policy file, applies hard/soft rules, and enumerates the return fields including verdict levels and recommended_action. Undisclosed are edge cases like what happens when the policy file is missing (only hinted at by policy_loaded) — hence not a 5.

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

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

Front-loaded purpose, then a compact return-value block, then two short examples — efficient and scannable with minimal waste. The examples repeat fields the return block already listed, but structurally the layout is sound and appropriately sized for the tool's complexity.

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

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

With no output schema, the description usefully documents the return shape (verdict, policy_loaded, violations, generic_checks, recommended_action), which is exactly the burden it should carry. Combined with annotations covering the safety profile, it is largely complete; only auth requirements and the behavior when no policy file exists remain 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 0%, so the schema carries no parameter documentation at all. The example call implicitly maps four of the five parameters (title, repo, body, diff_stat) via positional values, but 'labels' is never mentioned and no parameter's format or constraints are described. Partial compensation for a real coverage gap.

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 — 'Policy-aware PR screening' — and elaborates that it reads docs/policies/<org>-<repo>.md and checks the PR against hard/soft rules, which is concrete enough to distinguish it from a generic analyzer. It does not, however, contrast itself against close siblings like analyze_pr or coach_pr, so the 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?

Usage is conveyed only through two worked examples rather than explicit when-to-use/when-not guidance. Given siblings such as analyze_pr, coach_pr, and review_queue that plausibly overlap in PR-evaluation territory, the description leaves the agent to infer when triage_pr is the right choice. This is implied-usage territory, not explicit routing.

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