Coderbuds

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

Goes well beyond the lone destructiveHint=false annotation: discloses an access restriction (internal staff only), a state override the caller cannot control ('Everything starts at Sourced regardless of what you pass'), duplicate existence, and the GitLab exclusion that would otherwise produce a bad row. These are exactly the side effects an agent needs before writing.

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 scope rule and the staff-only gate, then the ICP, then the data-quality rules. Every sentence carries information, though the prose is slightly long for a create tool and the 'nobody can act on later' justification is editorial 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 12-parameter create tool with full schema coverage, minimal annotations and no output schema, the description covers audience, qualification criteria, dedupe ordering, state behaviour and data-quality expectations. Missing only what the call returns on success or on a duplicate hit, which is a modest gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding intent beyond the field docs — signal must be why-now, source_url must be recheckable, qualification_needed is where unverified facts go rather than guessing. The only gap is that priority (A/B/C) and next_action get no extra guidance.

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

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

States a concrete verb and resource (add a company or adviser to the outbound pipeline) and immediately scopes it to a specific ICP (CTO/head of engineering/hands-on EM at a 10–30 engineer product company on GitHub or Bitbucket, no GitLab). That is enough to distinguish it from save-prospect-draft-tool, update-prospect-tool and get-prospect-worklist-tool without opening any schema.

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

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

Explicitly gates the tool to internal Coderbuds staff, tells the agent to de-duplicate with get-prospect-worklist first, and prescribes what to put in signal/source_url versus qualification_needed instead of guessing. It even gives a negative example ('looked like a fit') so the agent knows a low-quality invocation when it writes one.

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

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

With only `destructiveHint: false` in annotations, the description carries the behavioral burden well: it explains the four verdict meanings, the default opinionated size standard, repository-scoped queue pressure, discounting of tests/docs/generated/moved content, and that overriding the verdict is allowed but should be recorded. This is rich disclosure beyond 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 front-loaded with purpose and verdicts, then moves into parameter guidance and follow-up recording. It is long for a tool description, but the complexity of 11 parameters and four verdicts justifies most of the length; a few illustrative passages could be trimmed.

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 an output schema, the description does not need to explain return values in detail, and it covers the important decision context: verdict categories, size norms, queue scope, discounting rules, and the required follow-up recording tool. An agent has enough information to invoke and interpret the tool correctly.

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

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

Although schema coverage is already 100%, the description adds meaningful semantics: `numstat` supersedes `test_lines`/`test_files`, test and moved line/file counts are discounted, `review_goals` must describe outcomes rather than implementation layers, and `scope_rationale` preserves context without waiving the standard. These details help an agent choose and populate parameters 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 states a specific pre-flight action (“fit check for a change you are about to open as a pull request”) and explains exactly what Coderbuds returns: a verdict with reasons, team size norms, merge times, and review-queue pressure. It is clearly distinct from the sibling recording tool, which is named later as the follow-up 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?

It gives strong usage context: run it before opening a PR, pass `numstat` when possible, fall back to manual counts, and use `record-change-fit-decision` afterward when the verdict is not `fits`. It does not explicitly compare against other assessment-adjacent siblings, but the core when-to-use guidance is clear.

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

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

The annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is partly covered; the description still adds real value by spelling out what the destruction means ("ships whatever is currently merged; it is not a dry run") and by surfacing the trigger-configuration prerequisite. It omits auth/permission requirements and whether a deploy is idempotent or repeats if called twice.

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

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

Four short sentences, front-loaded with the action, then prerequisite, then identifier format, then the dry-run caveat and alternative. Nothing is padding and there is no duplication of boilerplate.

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 mutation tool with an output schema (return values need not be explained) and annotations covering the safety profile, the description covers purpose, precondition, argument format, and the irreversibility caveat. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single parameter already documents both naming formats and the trigger requirement, so the schema carries the semantics. The description repeats the same examples ("saas", "patchstack/saas") rather than adding new meaning such as case sensitivity or ambiguity resolution across teams.

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: "Trigger a production deploy for one of your team's connected repositories." It is clearly differentiated from read-only siblings such as get-deployments-by-person-tool and get-undeployed-pull-requests-tool, which report rather than act.

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

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

Gives an explicit prerequisite (the repo must have a deploy hook URL or GitHub Actions workflow configured), explains two accepted identifier formats, and names the alternative: "Use GetUndeployedPullRequestsTool first if you want to see what will go out." That is when-to-use, when-not, and the alternative in a few sentences.

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

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

Annotations cover the safety profile (readOnly, idempotent), and the description goes well beyond them: it explains the scoring model (starts at 100, subtracts diff/file/complexity/focus/title penalties), the bounded ±20 AI adjustment and its dimensions, and explicitly disclaims CI and linting so the agent cannot misreport. It also instructs 'Report only the `factors` this tool returns', which is real behavioral guidance.

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

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

The lead sentence front-loads the purpose followed by the return contents and usage triggers, all earning their place. The second paragraph on the scoring algorithm is longer than strictly necessary for tool selection but does support correct interpretation of the output, so the cost is mild.

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 an output schema present, the description needn't document return fields, yet it highlights the key ones and warns about what the score does and does not include. For a two-parameter read tool with full annotation coverage, nothing an agent needs is missing.

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

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

Schema description coverage is 100% for both required parameters, so the schema already documents repository format and PR number. The description adds only an incidental example ('#1186') and no additional semantics, 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 opens with a precise verb and resource: 'Explain why one specific pull request got the quality score and label Coderbuds gave it.' It also enumerates what the response contains (score, label, size counts, penalties with point costs, AI adjustment, stored breakdown), which distinguishes it from aggregate siblings like get-pull-request-metrics-tool without naming them.

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

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

It gives concrete triggering contexts ('why is #1186 marked poor', 'a low score on a PR they opened') and states explicit exclusions: it does not read CI results and does not run a linter. It does not name a specific sibling tool as the alternative for aggregate or list-level questions, which is the only gap.

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

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

Beyond the readOnly and idempotent annotations, the description discloses extensive behavior: six timed stages, eligibility rules for naming a bottleneck, bot PR exclusion, 90-day review-history clamping, backlog treatment, deploy-stage repository scoping, blind spots, and unlock strings for missing data. These are exactly the operational caveats an agent needs to interpret results correctly.

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

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

The description is front-loaded with the core question and stage model, and each paragraph addresses a distinct behavioral caveat. It is long and somewhat verbose for a tool definition, but the length is largely justified by the complexity of the analysis and the edge cases being disclosed.

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 the tool's analytical complexity and the presence of an output schema, the description is complete enough for correct invocation and interpretation. It covers what stages exist, how bottlenecks are chosen, what is excluded, how missing data appears, and how to relay unlock guidance.

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

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

Schema description coverage is 100%, so both window_days and repositories are already documented in the input schema. The description largely reinforces the schema by mentioning the 90-day clamp and the interpretability of scoping to a representative repository, but adds little parameter-level detail beyond what is structured.

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 analytical purpose: splitting the path from request to production into six stages, timing each across recently merged pull requests, and naming the single slowest stage with supporting PRs and an intervention. It distinguishes itself from dashboard-style alternatives by framing the result as 'one stage instead of five dashboards.'

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 clearly says to use this tool to answer 'why is our delivery slow' and explains that stage-specific interventions differ, which helps an agent understand the intended context. It does not explicitly name sibling alternatives such as get-dora-metrics or get-pull-request-metrics or state when not to use this tool, so it falls short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety and repeatability are covered. The description adds the team-level scope, which is useful, but leaves 'recent actions' undefined — no time window, no pagination or volume limits — and repeats return contents that the output schema already supplies.

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

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

Two sentences, zero filler, and the resource plus scope are front-loaded before the return summary. Every clause earns its place.

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

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

For a zero-parameter read-only tool with annotations covering the safety profile and a full output schema, the description is nearly sufficient — scope and contents are both stated. The remaining gap is the undefined 'recent' window, which affects how an agent interprets and reports the data.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The stated team scope correctly signals that no user or team identifier needs to be passed.

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 ('Get') and resource ('autonomous agent activity') plus the scope ('authenticated user's team'), and enumerates what comes back (enabled agents, recent actions, per-agent stats, pending approvals). That enumeration distinguishes it from neighbors like get-person-activity-tool, get-ai-adoption-tool, and get-my-insights-tool, though it never names an alternative explicitly.

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

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

There is no statement of when to reach for this tool versus the many overlapping reporting siblings (get-ai-adoption-tool, get-mcp-adoption-tool, get-team-overview-tool, get-my-status-tool). The only guidance is the implicit 'for the authenticated user's team' scoping; no exclusions or prerequisites are given.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral detail: bot and dependabot PRs are excluded from the outcome comparison, first-party reports override inference for the same PRs, the result self-reports when samples are too small or detection hasn't covered the period, and the attribution block grades inferred attribution error rates. That is exactly the caveat context an agent needs before trusting or quoting the numbers.

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?

It front-loads the business question and the returned metrics, then layers caveats in decreasing importance. It is dense but nearly every clause carries information; the attribution paragraph is the longest and slightly buries its point, but is still relevant and not redundant with the schema or 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?

With an output schema present, the description needn't restate return shapes, and it correctly spends its words on interpretation and caveats instead: sample-size warnings, detection coverage gaps, bot exclusion, and attribution confidence. For a two-optional-parameter read tool with full annotations, nothing material is missing.

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

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

Schema coverage is 100%, and the schema itself carries the important nuance (the repository slug resolves team scope but does not filter metrics; period enum defaults to rolling_30d). The description adds no period semantics or hints about choosing between rolling vs calendar windows, so it sits at the baseline rather than adding value.

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 question and then enumerates exactly what the tool returns: adoption rate, contribution intensity, AI-assisted PR rate, detected tools, detection confidence, and an outcome split on lead time and size. This clearly distinguishes it from adjacent siblings such as get-mcp-adoption-tool (MCP-specific) and report-ai-usage-tool (ingestion rather than reporting).

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

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

It gives concrete intent framing — answer "is AI actually in our SDLC yet" and "is it paying off" with one call — and positions the outcome split as the KPI-grade signal versus adoption as a pilot metric. It also flags interaction with report-ai-usage-tool for first-party reports. What it lacks is an explicit exclusion, e.g. when to prefer get-mcp-adoption-tool or the DORA/PR metric tools 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?

Annotations already cover readOnly/idempotent, but the description adds real behavioral context: counting is based on team repositories rather than member list, non-member authors surface as separate fields, unmatched slugs land in `unmatched_repositories` instead of silently returning zero, and opened-time is distinct from merge-time.

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 action and the denominator caveat, and every paragraph carries distinct information. Slightly long — the quoted 'per repo' / 'by repository' phrasing and the 'today, this week, on a repo, or across the team' list are a touch redundant, but nothing is wasted enough to hurt.

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

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

For a read-only counting tool with an output schema and full param coverage, the description supplies everything an agent needs: window semantics, inclusion rules for bots, repository scoping behavior, and the mismatch/edge-case handling. No gaps remain that would cause a wrong call.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the 24-hour-vs-calendar-day caveat and the bare-name matching rule. The description adds no parameter detail beyond what the schema states, 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 ('Count pull requests OPENED'), plus the scope (recent window, default 1 day) and the breakdowns produced (per repository, per author, human vs bot). It explicitly separates itself from get-merged-pull-requests and from a per-person activity breakdown, so an agent can route 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?

Gives concrete triggering questions ('how many PRs were created/opened/raised — today, this week, on a repo, across the team') and an explicit preference rule over a sibling: 'Prefer this over a per-person activity breakdown for any total.' It also names the alternative for merges and warns against reconciling the two.

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

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

Annotations already establish readOnlyHint and idempotentHint, so the description only needs to add context — and it does: the windowing default, the per-person failure surfacing, the sort order (by deploy count), and the inclusion of team totals. It doesn't mention any rate limits or empty-result behavior, but for a read-only aggregate that's a minor 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?

Front-loaded with the core action and scope, followed by the use case and return contents. The inline example ('Bob Marley: 5 deploys (3 failed)') earns its place by conveying output shape, though the final sentence partially duplicates the 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?

For a single-optional-parameter read tool with annotations and an output schema, the description covers purpose, usage trigger, and aggregation behavior. The return-value description is somewhat redundant given the output schema exists, and no sibling differentiation is offered, keeping it just shy of full marks.

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

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

There is only one parameter and schema description coverage is 100% — the schema already documents 'days', the default of 7, and the 1–90 clamp. The description restates the 7-day default but adds no new semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource — listing who triggered production deployments over a window, with failed counts and repos per person — and includes a concrete output example. It's clearly distinguishable by topic from get-dora-metrics-tool or get-person-activity-tool, but it never names those siblings to make the boundary explicit.

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

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

Gives an explicit usage trigger: 'Use this to answer "who has deployed to production this week and how much".' That's a clear context for selection, but there are no exclusions or pointers to alternatives (e.g. when to use get-dora-metrics-tool instead of this attribution view).

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

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

Beyond the readOnly/idempotent annotations, the description discloses the null semantics that would otherwise cause misreads: comparison fields null when history doesn't span the prior period, lead time null with no matched merged PR, recovery time null with no recovery, and the instruction to say nothing rather than infer change. It also explains how the overall rating is computed and its minimum-sample rule (fewer than three measured metrics yields "No Data").

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?

It is front-loaded with the core action and the metric list, then moves to edge-case semantics. Each null-handling sentence carries real weight, though the run of three separate null clauses plus the overall-rating rule makes the back half denser than it needs to be.

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 an output schema present and full param coverage, the description correctly focuses on interpretation rather than return shape: metric definitions, null behavior, categorisation labels, and rating aggregation. It does not address whether the team scope is implicit from auth or whether permissions/team membership affect results, a small remaining gap for a team-scoped 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?

The single period parameter has 100% schema description coverage with a six-value enum and a documented default, so the schema already carries the meaning. The description never mentions the period parameter, its options, or how period choice interacts with the previous-period comparison fields, adding nothing on top of the schema; baseline 3 applies.

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

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

The description states a specific verb and resource ("Get DORA metrics for the authenticated user's team") and enumerates exactly what the four metrics are: deployment frequency, lead time, change failure rate, and MTTR. It stops short of distinguishing itself from overlapping siblings such as get-team-overview-tool or get-my-insights-tool, so the agent must infer where DORA ends and those begin.

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, when-not-to-use, or named-alternative guidance. The only scoping signal is "for the authenticated user's team", and nothing tells the agent when to pick this over get-team-overview-tool, get-team-insight-summary-tool, or get-pull-request-metrics-tool, which plausibly surface related delivery data.

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

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

Annotations already cover read-only and idempotent, yet the description adds substantial behavior beyond them: only enumerations are flagged, passing mentions are never reported, and no-file/BitBucket/unreadable repos return insufficient_data rather than false drift, with archived repos skipped. These false-positive-avoidance rules are exactly the kind of context annotations cannot express.

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

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

The leading question frames the purpose, then rationale, then guidance, then edge-case rules – front-loaded and logically ordered. Slightly long, but nearly every sentence carries distinct information (the 'worse than none' rationale is the only expendable flourish).

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?

An output schema exists so return detail isn't strictly needed, yet the description still summarizes what's returned (file, last change, stale directories with entry counts and examples). Combined with the edge-case rules, nothing an agent needs to decide whether and how to call 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?

Schema coverage is 100% and the single optional parameter is documented there, but the description reinforces the default behavior ('For each connected repository') versus the single-repo override, adding context the bare schema doesn't emphasize.

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 question naming the resource (agent guidance file) and the operation (detecting drift). It clearly distinguishes itself from get-repo-readiness and get-team-context by scope, so an agent can tell the tools apart 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?

It gives explicit call conditions (before trusting a guidance file, when onboarding an agent, when deciding whether to replace a hand-maintained inventory) and names the alternative get-repo-readiness for the 'does a file exist' question. When-to-use and when-not are both present.

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

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

Annotations only declare readOnlyHint and idempotentHint; the description adds substantial context beyond that — that rules are live and supersede any cached/documented version, the seven-group return shape, and how to interpret the `retired`, `evidence: null`, and `proposed` markers. That last point is a real behavioral constraint ('they are not binding — do not draft against them').

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 access restriction and purpose, then the call-to-action, then a bulleted breakdown of the tricky fields. It is on the long side for a zero-argument tool, but nearly every sentence carries operational instruction rather than 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?

There is no output schema, so the description must explain the return value — and it does, enumerating the seven groups and calling out the three semantics that could otherwise be misread. An agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is no schema gap to compensate for. The description instead spends its words on return semantics, which is a reasonable substitute but not strictly a parameter concern.

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

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

States a concrete resource and scope: 'Who Coderbuds sells to and what an opener is allowed to say — the rules behind the Who it is for tab of /admin/prospects.' It is immediately distinguishable from get-prospect-worklist-tool (who to write to) and propose-icp-rule-tool (adding rules), both named directly.

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?

Explicit temporal guidance: 'Call this before writing anything to a prospect, alongside get-prospect-worklist.' It also names the alternative for the out-of-scope case: 'Use propose-icp-rule when outbound teaches you something this list does not say.' Both the when and the when-not are covered.

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, yet the description still adds substantial non-obvious behavior: the exact denominator used for the nudge list (login member still shipping code, deduped across linked identities, excluding tracked contributors and inactive members). It also discloses the attribution rule — a call counts for the team named by the repository slug or ?team= binding, not the web switcher's last selection — which is the kind of semantics an agent cannot infer elsewhere.

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 core answer is front-loaded in the first sentence and the rest is dense, information-bearing prose with no filler. It runs long, and the attribution paragraph sits somewhat apart from the main payload, costing it a point on economy.

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 an output schema present, the description need not spell out return shapes, and it still enumerates the report's sections plus the definitional subtleties (nudge-list denominator, team attribution) that determine whether the agent interprets the numbers correctly. Nothing needed to call or trust the result is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries the days default, clamp, and repository slug format. The description goes beyond that by explaining what repository actually does to attribution when a member belongs to several teams, adding real meaning rather than restating the schema.

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

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

States a specific verb and resource: reports Coderbuds MCP adoption per member over a window, with named sub-outputs (total invocations, per-member usage, per-tool counts, nudge list). An agent knows exactly what question this answers. It does not explicitly separate itself from the nearby get-ai-adoption-tool or get-agent-activity-tool, 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?

Gives concrete triggering questions ("who is using the MCP", "is the team on the MCP yet") and a second use case (finding who needs setup instructions). That is clear context for when to reach for it. It names no exclusions and no sibling alternatives, which is exactly the gap that keeps it at 4.

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

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

Annotations already declare readOnly and idempotent, so the safety profile is covered; the description adds real behavioral context by disclosing the return shape (total plus per-repository and per-author breakdowns) and the key nuance that the human-vs-bot split is always reported regardless of include_bots. It does not mention pagination or limits, but for an aggregate count that is a minor 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?

Front-loaded with the core action and window, then the return shape, then the trigger sentence. Four sentences with little waste, though the bot/dependabot point is stated twice (in the split explanation and again at the end).

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

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

For a low-complexity, zero-required-parameter read tool with an output schema and safe annotations, the description covers what to call it for, the defaults, and the shape of results. The main missing piece is which sibling to choose for adjacent PR questions, which is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that the bot split lets you answer both 'including' and 'excluding dependabot' from a single call, and by restating the owner/name scoping with a concrete example. It does not clarify day-range bounds or caps on the repositories list.

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

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

States a specific verb and resource with scope: 'Count merged pull requests over a recent window (default 30 days)'. The 'merged' qualifier inherently separates it from siblings like get-created-pull-requests-tool and get-open-pull-requests-tool, though it never names them. Slight ambiguity from lumping 'merged, shipped, or closed' together, which are not strictly the same event.

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

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

Gives a clear trigger condition: 'Use this when the user asks how many PRs were merged, shipped, or closed on a repo or across the team — including bot/dependabot PRs.' No explicit exclusions or named alternatives (e.g. get-pull-request-metrics-tool, get-open-pull-requests-tool) are offered for adjacent questions.

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 safety is covered elsewhere. The description does add one real behavioral fact — only 'active' insights are returned and results span all teams — but says nothing about ordering, whether dismissed items are excluded by definition, or what happens when limit is exceeded.

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 front-loaded sentences with the scope stated first and the optional filters second. Slightly redundant with the schema's parameter descriptions, but nothing wasteful.

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

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

No output schema exists, and the description never characterizes what an 'insight' contains, so an agent cannot anticipate the return shape. With zero required parameters, 100% schema coverage, and safety covered by annotations, the remaining gap is moderate 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 description coverage is 100%, so the tab enum, the limit range, and unseen_only are all fully documented in the schema. The description merely restates the filter options without adding format, default, or interaction details, which is the correct baseline-3 case.

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 active insights') plus the scope: the authenticated user's insights across all their teams. That scope does implicitly separate it from get-team-insight-summary-tool, but the sibling is never named, so differentiation is inferred rather than explicit.

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 optional tab filter and unseen_only flag hint at usage patterns, but there is no statement of when to choose this over get-team-insight-summary-tool or get-my-status-tool, and no exclusions. Usage is implied by the description 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 and idempotentHint, so safety is covered; the description adds real substance beyond that — bots are excluded from reviewer suggestions, merged work carries 'hours waiting', blockers are categorized into five named states. It also gives an output-consumption instruction ('lead with the `headline`'), which no structured field 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?

Two sentences, front-loaded with what the agent gets, then a compact rendering instruction. Despite being dense with enumerated content, every clause maps to a distinct capability (blockers, reviewer queue, undeployed work, recent ships) rather than restating the name.

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

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

An output schema exists, so return values need not be explained, and the description goes further by telling the agent how to relay the result. Scope, bot exclusion, and the four data sections are all covered; only the session-binding behavior when `repository` is omitted 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 coverage is 100% and both parameters are described in detail in the schema (owner/name slug semantics, default 2 days, clamped to 1-30). The description adds nothing about either parameter, so the baseline 3 applies — the schema is doing all the work here.

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 — a personal, cross-repo status rollup — and enumerates exactly what it bundles: your open PRs with blocker reasons, unblockable reviews, merged-but-undeployed work, and recent shipments. That composition makes it clearly distinct from point tools like get-open-pull-requests-tool or get-merged-pull-requests-tool, though it never names a sibling to sharpen the boundary.

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

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

The phrase 'standup prep and morning brief in one call' gives a concrete usage context that tells the agent when this aggregate is the right entry point. However, it offers no exclusions or routing advice — an agent drilling into one PR or one repo isn't told to prefer get-open-pull-requests-tool or get-peull-request-metrics-tool 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: grouping by author, bot authors collapsed by default, oversized PR thresholds and handling, status_freshness caveats, and exclusion of archived repositories. This is exactly the kind of operational detail an agent needs to interpret results correctly.

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 long but front-loaded: it begins with the core purpose and blocking signals before expanding into oversized PRs, bot handling, and freshness. Some sentences are dense and could be tightened, but every section contributes useful behavioral context. The structure supports scanning, though it is more verbose than strictly necessary.

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 tool is complex (author grouping, blocking signals, bot collapsing, oversized flags, freshness, archived exclusion), and the description covers all of these behavioral nuances. An output schema exists so return values need not be explained. With annotations covering safety and schema covering parameters, the description completes the picture for correct interpretation.

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 fully documents both parameters, including detailed guidance for include_bot_details. The description repeats the same information about repositories scoping and include_bot_details without adding meaning beyond the schema (e.g., the ordering for bot details is already in the schema). Baseline 3 is appropriate 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 clearly states a specific verb and resource: 'List the team's open pull requests grouped by author' with blocking signals. It scopes to open PRs and explains the grouping, which distinguishes it from broad pull-request listing tools. However, it does not explicitly name sibling tools like get-merged-pull-requests-tool as alternatives, so it falls short of the highest clarity.

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

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

The description gives clear usage context: 'Use this to nudge people to merge — lead with the headline' and tells when to set include_bot_details (dependency queue) versus leaving it off (summarising for people). It also advises checking status_freshness before quoting counts. It lacks explicit when-not-to-use rules or named alternatives, but the guidance is sufficient for correct invocation.

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 only cover read-only and idempotent; the description goes well beyond by disclosing the ambiguity contract (returns `candidates` instead of guessing, and the agent should ask which person), the `not_captured` blind-spot list, and an instruction to repeat those limits when reporting someone as quiet. That is exactly the operational context an agent needs to avoid a wrong answer.

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 question it answers, then layered with interpretation and caveats; each paragraph carries distinct value. It is on the long side and repeats the ambiguity handling already stated in the `person` schema, which keeps it from a 5.

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

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

An output schema exists, so return-shape explanation is not required, yet the description usefully tells the agent which field to lead with (`headline`) and what `candidates` and `not_captured` mean in practice. Combined with annotations, there is nothing an agent needs in order to call and correctly present this tool that is missing.

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

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

Schema description coverage is 100%, so the schema already explains `days` (default 56, clamped 7–84), `person` formats and the optional `repository` slug. The description restates the name/login formats and the ambiguity-to-candidates behavior, which duplicates the schema rather than extending it. 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 — what one person has been doing in a recent window — and enumerates exactly what is returned: PRs opened/merged, reviews given, deploys triggered, plus weekly rollup, busiest days and longest quiet run. The line 'three counts read together rather than one in isolation' distinguishes it from the single-metric siblings like get-created-pull-requests-tool and get-deployments-by-person-tool without needing to open either schema.

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

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

Gives concrete triggering questions ('is Dave still shipping?', 'what has Sam been working on?') and explicit interpretation guidance — lead with `headline`, don't read a PR count alone. It stops short of naming sibling tools as alternatives, so the routing against get-agent-activity-tool or get-my-insights-tool is implied rather than stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial operational context: internal staff restriction, list semantics, needs_action_reason and answer fields, gate verdict behavior, stage_tests as definition of done, and caveats about lead qualification. No contradiction with annotations.

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

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

The description is long but organized with front-loaded purpose, bulleted lists, and clearly separated guidance sections. Every section carries useful context, though it could be tightened in places without losing meaning.

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

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

With no output schema, the description still fully explains the shape of the response (five lists), key fields to inspect, gate and stage_tests semantics, and caveats. An agent has enough information to call and interpret the tool correctly.

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

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

Schema coverage is 100% for the two parameters, and the schema descriptions already explain limit capping and quiet_days. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description states exactly what the tool returns: the outbound prospect pipeline worklist behind /admin/prospects, broken into five ordered lists. It distinguishes this read/list operation from sibling mutation tools like update-prospect and record-prospect-outreach.

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 explicitly says to call this at the start of every outbound session, gives the order in which to work the five lists, specifies when not to re-ask a question, and explains the gate stop condition. Alternatives and follow-up actions are named directly.

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 safety is covered; the description still adds value by disclosing the return contents and, importantly, that results include period-over-period comparison — a behavioral trait not visible in the annotations or schema. It stops short of noting cost, latency, or empty-data behavior for a team with no PRs.

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

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

Two sentences, front-loaded with the verb and scope, followed by an efficient enumeration of returned metrics. Slightly redundant to re-list return values when an output schema exists, but the listing is compact and no sentence is filler.

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

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

Since an output schema exists, the return-value enumeration is arguably unnecessary, and what is genuinely missing is routing context: which of the many similarly named PR/metric siblings this replaces and what 'team' means for the authenticated user. Adequate to call correctly, but thin for a tool in a dense sibling cluster.

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 'period' enum already documents all six values and the default, so the description is not required to compensate. The phrase 'period-over-period comparison' hints at how the period argument drives output, but adds no syntax or formatting detail beyond the schema.

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

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

States a specific verb + resource ('Get pull request activity metrics') and scopes it to the authenticated user's team, then enumerates the aggregates returned. This separates it from the per-PR list siblings (get-merged-pull-requests-tool, get-open-pull-requests-tool) at least implicitly, but it never explicitly contrasts with metric siblings like get-dora-metrics-tool or get-my-insights-tool.

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

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

The aggregate-metrics framing implies when to use it (team-level rollup rather than per-PR listing), but there is no explicit 'use this when X, use get-dora-metrics-tool when Y' guidance despite a crowded metric-tool sibling set. Nothing is stated about prerequisites or when not to call it.

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

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

Goes well beyond readOnly/idempotent annotations by disclosing nuanced behavior: insufficient-data checks are excluded and never counted against a repo, Coderbuds opt-out behavior, BitBucket's GitHub-only API limitation, archived repository skipping, and dormant repository handling. These are material behavioral traits an agent could not infer 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?

The description is long and dense, but it is front-loaded with the core question and structured around specific checks, edge cases, and exclusions. Most sentences earn their place, though the length could be trimmed slightly without losing essential meaning.

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

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

Given a complex readiness evaluation with an output schema present, the description covers what is evaluated, how pass/fail/insufficient_data are treated, edge cases like opt-out, BitBucket, archived/dormant repos, and the team rollup. It is complete enough for correct invocation and interpretation.

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 zero parameters and 100% schema description coverage, there are no parameter semantics to clarify. The baseline for zero-parameter tools is 4, and nothing in the description suggests otherwise.

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: judging repository readiness, not the change itself. It explicitly distinguishes itself from a sibling concept by saying it judges the repository 'a coding agent is dropped into — not the change it makes,' which helps differentiate it from assess-change-fit-tool.

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

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

Directly advises when to call it: 'Call this to find what is holding a repo back before pointing an agent at it.' The framing around repository readiness versus change fit gives clear usage context without needing to infer alternatives.

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

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

Annotations only declare readOnlyHint=true, while the description adds substantial operational context: internal staff only, findings are raised by nightly checks and a weekly critic, a person decides which are worth fixing, and each finding carries a ready-made prompt with evidence and definition of done. This is rich behavioral disclosure beyond annotations and does not contradict them.

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

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

The description is front-loaded with the key constraint ('Internal Coderbuds staff only') and purpose, then proceeds through default behavior and workflow. It is somewhat long but every paragraph carries useful selection or invocation guidance, with little 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 read-only tool with two optional parameters and no output schema, the description covers the important missing context: who can call it, what findings represent, what each result contains, the default status, and the follow-up workflow. An agent has enough information to call it correctly and avoid the main misuse case.

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 already 100%, so the baseline is 3, but the description adds meaningful context for status: accepted is the default and represents findings a person approved for fixing, while proposed findings should not be started because they are not yet agreed to be real. It does not add much for finding_id beyond the schema's 'Read one finding, whatever its status.'

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 ('Read Coderbuds' self-review findings') and defines exactly what a finding is: a customer-facing statement contradicted by data Coderbuds already holds. It also distinguishes this read tool from the follow-up action tool, record-self-review-fix.

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

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

It gives explicit workflow guidance: default status is accepted, work one finding at a time, fix it in this repository, open a PR, then call record-self-review-fix. It also includes a clear prohibition: do not start on a proposed finding because nobody has agreed it is real yet.

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, yet the description still adds substantial context beyond them: unreliable rates over tiny samples are flagged, three milestones lack medians because nothing records their timing, and the per-account list is capped while rates cover the whole cohort. It also ties results to a specific dashboard for verification.

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?

Access restriction and the one-line summary are front-loaded, then two labeled bullets organize the funnel stages, and caveats close it. It is long, and the closing caveat paragraph restates some of what the journey_limit schema already says, but the density is warranted by a two-funnel, multi-metric 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?

An output schema exists, yet the description still tells the agent what categories of results to expect (milestone shares, medians, blockers, trial splits, per-account journeys) and how to read them. For a complex analytics tool this leaves nothing an agent needs missing.

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

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

Schema coverage is 100% and both parameters are well documented there, so the baseline is 3. The description still adds rationale — why 365 is the default (shorter windows yield only two or three signups and degenerate rates) and that journey_limit bounds only the list, not the rates — which strengthens the choice of values.

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 the signup and conversion funnel) and enumerates the two funnel stages, front door and activation, with the exact metrics each covers. No sibling tool covers signup/conversion funnel data, and the description makes that scope boundary 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?

Gives concrete question-shaped guidance ('why signups stall', 'which step loses the most people', 'whether a change to onboarding moved anything', 'who is worth an email this week') and an explicit audience restriction ('Internal Coderbuds staff only'). It never names an alternative tool for narrower questions, but no sibling overlaps this scope, so the omission costs little.

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

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

Annotations cover read-only/idempotent, but the description adds that all data is derived from live shipping data and therefore self-refreshing — a meaningful behavioral trait. It also discloses the response-shape change caused by passing `repository` (focused map with names-only for the rest). It does not discuss data latency window or volume limits beyond the schema's window_days.

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: the first sentence defines the payload before any usage advice. Two tight paragraphs, though the "never goes stale like a hand-maintained repo list in an agent rules file" clause is rhetorical padding that could be cut without loss.

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 an output schema present and annotations declaring read-only, the description only needs to cover scope, when to call it, and routing to siblings — all of which it does. Nothing an agent needs to call this correctly at session start is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by framing `repository` as binding the session to the owning team and explaining the focused-vs-full output consequence, which is the real decision behind the parameter. `window_days` is left entirely to the schema, so it does not fully cover both parameters.

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 the resource precisely (the team's org map) and enumerates what it contains: repositories shipped to, activity/contributor signals, deploy path, readiness flag, repo relationships, and confirmed conventions. It separates itself from siblings by naming get-repo-readiness, link-repositories, and assess-change-fit with their distinct purposes.

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

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

It gives an explicit when-to-use scenario ("the right call at session start in a multi-repo org") and names the alternative behavior (pulling the whole atlas). It routes the agent away to link-repositories for corrections and assess-change-fit for size/review norms, and to get-repo-readiness for detail beyond the compact flag.

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 safety profile is covered and the description doesn't need to repeat it. The description does add useful content beyond that, spelling out which aggregates are returned (per-tab counts, unseen count, personal count) and scoping to 'active' insights, though with no output schema present it could have described the shape more concretely.

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

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

A single sentence with no filler, front-loading the verb and the scope before enumerating the returned counts. Nothing in it is redundant with the name or title.

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

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

With no parameters and no output schema, the description carries the burden of conveying the return contents, and it does so by listing the three count categories. What's missing is guidance on how this fits alongside the other insight and team-summary tools.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The implicit scoping to the authenticated user's team is a mild plus, as it tells the agent the tool needs no team 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 names a specific verb and resource ('Get an aggregate summary of active insights') and enumerates what the summary contains: per-tab counts, unseen count, and personal insight count. It implies team scope, distinguishing it loosely from get-my-insights-tool, but never explicitly contrasts with the closely related siblings (get-my-insights-tool, get-team-overview-tool).

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

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

There is no statement of when to call this instead of get-my-insights-tool or get-team-overview-tool, and no prerequisites or exclusions. Only the phrase 'authenticated user's team' hints at the applicable context, leaving the routing decision entirely to inference.

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

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

Annotations already declare readOnly and idempotent, so safety is covered. The description adds the useful fact that all metrics come back in one call with no filtering semantics beyond period, which tells the agent this is a broad read rather than a drill-down.

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

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

Two sentences: the first front-loads what is returned grouped by framework dimension, the second states usage. No filler or repetition of the title.

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

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

With an output schema present, the description needn't explain return structure, and it still summarizes the metric families so the agent knows what to expect. Annotations cover the safety profile; only the absence of named alternatives keeps it from a 5.

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

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

Schema description coverage is 100% and the single period parameter is fully documented with its enum and default, so the schema does the heavy lifting. The description does not mention period or its accepted values, adding nothing beyond the schema.

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

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

States a specific verb and resource (team health overview) and enumerates what it returns: PRs, deployments, contributors, DORA ratings, collaboration and efficiency metrics. The phrase 'single-call snapshot' distinguishes it in spirit from the granular siblings (get-dora-metrics-tool, get-pull-request-metrics-tool), but no sibling is named explicitly.

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

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

'Use this for a single-call snapshot of team engineering health' gives a clear usage context, implying it is the aggregate entry point versus the per-metric tools. There is no explicit when-not-to-use or named alternative, which keeps it below a 5.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them by disclosing the deployment-correlation rule: PRs merged before the last successful production deploy are treated as shipped and surfaced via `assumed_deployed` rather than as false positives. That is exactly the kind of subtle semantics an agent could otherwise misread as a data bug.

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

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

Three sentences, front-loaded with what is returned and then the use case, with no filler. Slightly dense in the final sentence, but every clause carries information about output shape or the assumed-deployed rule.

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?

An output schema exists so return-value documentation is not required, yet the description still summarizes the payload (wait time per PR, last deploy per repo). With one optional, fully described parameter, nothing an agent needs to invoke this correctly is missing.

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

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

Only one optional parameter and schema coverage is 100%, with the 1–90 clamp and default of 14 documented in the schema itself. The description adds no extra meaning about lookback_days, which is acceptable given the schema does the work.

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 merged pull requests that have not yet shipped to production') plus the grouping dimension ('grouped by repository'), which immediately separates it from the broader get-merged-pull-requests-tool in the sibling list. An agent can pick between them without opening either schema.

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

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

'Use this to spot work that is merged but stuck before deployment' gives a clear selection trigger. It does not explicitly name get-merged-pull-requests-tool as the alternative for a full merged-PR listing, so the when-not side is only implied.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that a summary is scoped to the authenticated user's team and that older periods are retrievable, which is useful context. It does not add anything about freshness/latency or what happens beyond the 4-period limit, and the listed sections largely restate the 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?

Three compact sentences, front-loaded with the core action and resource, then the content breakdown, then the parameter hint. No filler. The content enumeration is slightly listy but still earns its place by telling the agent what the output covers.

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 optional parameter read-only tool with an output schema and annotations, the description covers purpose, scope (team, latest period), content, and how to go back in time. The only meaningful gap is that it does not point the agent to the more specific sibling tools when a narrower summary is needed.

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 coverage, the schema already documents the default of 0 and the max of 4. The description only repeats the retrieval intent ('Use weeks_ago to retrieve older summaries') without adding format or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema carries the 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 ('Get the latest weekly changelog summary for the authenticated user's team') and enumerates what the summary contains (TL;DR, executive summary, feature highlights, fixes, team highlights). That makes the deliverable concrete. It does not explicitly differentiate itself from near siblings like get-team-insight-summary-tool or get-team-overview-tool, 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?

'Use weeks_ago to retrieve older summaries' gives parameter-level usage but no when-to-use versus alternatives guidance. There is no statement of when this summary is preferable to get-team-insight-summary-tool or get-my-insights-tool. Usage is implied by the purpose rather than spelled out.

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

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

Annotations cover idempotency and non-destructiveness, and the description adds real context beyond them: links are team-visible, attributed to the caller, and re-teaching refreshes rather than duplicates. It does not discuss failure modes (e.g., to_repository off-team) beyond the schema's 'Must be on the same team.'

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

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

Front-loaded with purpose, then relations, then triggers, then behavioral notes. Every clause earns its place, though the parenthetical definitions add some length that could be tightened.

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?

An output schema exists so return values need no explanation; the description still covers relation semantics, when to call, team binding, visibility, and refresh behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic depth to the enum: depends_on as 'consumes that one — an SDK, package, or service,' ships_with as coupled changes, unrelated as suppressing derived connections. This meaningfully exceeds the terse enum descriptions.

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

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

Specific verb+resource: 'Teach the team's org map how two repositories relate.' It names the downstream consumer (get-team-context) and defines the four relation types, so it is unmistakable against siblings like set-up-repository-tool or deploy-repository-tool.

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

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

Explicit trigger conditions: 'when you discover a relationship the map is missing, or when the user tells you how repos fit together,' plus the refresh semantics of re-teaching an edge. It lacks an explicit when-not or a named alternative, which keeps it just short of a 5.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description is not burdened with safety disclosure. It usefully explains the downstream effect (suppresses the insight from future queries for the authenticated user), but omits whether marking is reversible/unmarkable and what happens for an invalid or foreign insight_id.

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

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

Two short sentences, front-loaded with the action and effect, with no filler. Slightly better than minimal, though the payoff sentence is somewhat generic.

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 mutation with annotations covering idempotency and non-destructiveness and no output schema, the definition supplies enough to invoke it correctly. The remaining gap — behavior on invalid or non-owned insight_id — is minor.

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

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

There is a single parameter with 100% schema description coverage, so baseline is 3. The description adds no meaning beyond the schema — it does not clarify whether insight_id must belong to the caller or how IDs are obtained (e.g., from get-my-insights-tool).

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 ('Mark a specific insight as seen') plus a scope qualifier ('by the authenticated user'), which distinguishes it from read-oriented siblings like get-my-insights-tool. It does not explicitly name or route against those siblings, keeping it just short of a 5.

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

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

The second sentence implies when to use it — after reviewing an insight, to reduce noise in future queries — but never states when not to use it or points to an alternative tool for retrieving or dismissing insights. Usage is inferred rather than prescribed.

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 only carry destructiveHint=false, so the description does the heavy lifting: it discloses access restriction ('Internal Coderbuds staff only'), the non-binding nature of the write ('does not govern anything until a person adopts it'), where the proposal surfaces, and the consequence of omitting evidence ('shown as ungrounded rather than quietly passing as fact'). That is real behavioral context an agent cannot get from the annotation.

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

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

Front-loaded with scope and the adoption caveat before the when-to-propose rules, and nearly every sentence carries instruction. It runs long across four blocks, and the evidence explanation partially duplicates the schema's own wording, so it is dense rather than maximally 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 does explain the outcome (a proposal on the admin tab, ungrounded flagging when evidence is absent), which is the main thing an agent needs. It never says what the call returns (an id, a link, a confirmation), which is the one remaining gap for a create-style tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning — it explains what makes evidence valid ('the reply you read, the measurement, the count of rows'), the cost of leaving it out, and the required form of statement (an instruction the next draft can follow, not an observation, with a usable vs unusable example). 'kind' and 'source_url' get no treatment in the prose.

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 — proposing a rule about who Coderbuds is for or what an opener may say — and pins down the destination (the Who it is for tab of /admin/prospects as a proposal). It implicitly separates itself from writing/adopting rules, but never names the sibling read or standard-setting tools (get-icp-tool, set-change-fit-standard-tool) an agent might otherwise reach for.

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

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

Gives an explicit trigger ('propose when outbound has taught you something the current rules do not say: a reply that contradicts a wedge, a disqualifier that keeps recurring, a signal that keeps producing rows nobody writes to') and two explicit exclusions: no tidier rewording of an existing rule, and no re-proposing anything in 'retired'. When/when-not guidance is complete.

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

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

Beyond the lone destructiveHint=false annotation, it discloses the audience restriction (internal Coderbuds staff only), the landing surface (/admin/self-review), and crucially that the write is staged as 'proposed' with nothing happening until a human accepts it — exactly the state-transition context an agent needs before writing. It does not cover what happens on accept/reject or whether duplicate proposals are rejected server-side.

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 audience gate and the definition, then usage rules, then parameter notes — the ordering matches how an agent decides. It is slightly redundant in re-explaining `claim` and `evidence` already covered by the 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?

For a six-parameter mutation with no output schema, the description covers who may call it, what it creates, the pending-state lifecycle, and when not to call it. The remaining gap is what the tool returns and whether it deduplicates against existing findings, which the agent must infer.

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 six parameters are already documented in structured data, setting the baseline at 3. The description's restatement of `claim` and `evidence` ('leave it out rather than invent it') mirrors the schema text rather than adding new semantics such as expected evidence format or severity selection guidance.

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 (propose) and defines the resource precisely: a claim Coderbuds makes that its own data contradicts, or a material omission. That definition distinguishes it cleanly from get-self-review-findings-tool (read) and record-self-review-fix-tool (fix tracking) without needing schema inspection.

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

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

It gives an explicit positive trigger ('when your work in this repository or on production data shows Coderbuds' output is wrong in a way that will recur'), two explicit exclusions ('do not propose one-off bugs you can simply fix', 'do not propose a tidier wording of an open finding'), and names the prerequisite read tool to call first.

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

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

Beyond the idempotent/non-destructive annotations, it discloses default resolution ('most recent undecided check'), that the response may carry a standard_adjustment, and that the record is team-visible and read back. It does not cover failure modes (e.g. no undecided check to bind to) or any permission/auth requirements, which keeps it short of a 5.

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

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

The operative guidance is front-loaded and clear, but the closing three paragraphs repeat one point — don't re-explain the standard to the user — using two separate metaphors (argument made twice, being nagged about). That's redundant prose in a description that is already long.

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?

An output schema exists, yet the description usefully flags the one field an agent must act on (standard_adjustment) and sets post-call social behavior. What's missing is what happens when there is no recent undecided check to default to — an agent calling with only `decision` has no stated failure behavior.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description earns more: it explains the default resolution of check_id and gives a worked example of the kind of reason text worth writing. The repository parameter's purpose is left entirely to 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?

Names a specific verb and resource — recording what you did about an assess-change-fit verdict — and ties it explicitly to the sibling tool assess-change-fit-tool that produces the check. An agent can tell immediately this is the follow-up write, not another assessment.

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

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

States the trigger ('right after you act on one — especially when you override it'), the expected minimal call shape ('usually call it with just decision and reason'), and the condition for being explicit with check_id. It also resolves the ambiguity of what to do when overriding: override is legitimate, just record it.

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

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

Annotations only declare destructiveHint=false, so the description carries real weight and delivers: the state transition (Sourced to Contacted), the side effect of folding and clearing a pending draft to prevent duplicate sends, and the concrete downstream harm of a false record. It also discloses the access restriction (internal staff only), which nothing in the schema states.

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

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

Front-loaded with the access restriction, then the trigger condition, then the alternative route, then the side effect. The repeated emphasis on 'after it has actually been sent' is deliberate and justified for a state-mutating tool whose failure mode is silent data corruption.

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

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

Covers trigger, side effects, authorization, and the sibling to use instead, which is most of what an agent needs. With no output schema it never says what a successful record returns or what happens if prospect_id is invalid or already Contacted — the only remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns an extra point by explaining the cross-field interaction the schema only hints at: the saved draft 'is folded into the record and cleared', which clarifies why note defaults to the draft and what happens to it afterward.

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 ('Record that a message was sent to a prospect') plus the critical ordering qualifier ('after it has actually been sent'). It is clearly separable from save-prospect-draft-tool and update-prospect-tool, which are named or implied in the surrounding tool set.

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

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

Explicit when-to-use ('Only call this when you have been told it went out') and explicit when-not plus the correct alternative ('Sending is not something you can do... save it with save-prospect-draft'). The routing decision is unambiguous.

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 only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses the audience restriction (internal staff), the fact that this is a record-keeping write rather than a state-resolving action, and the actual resolution path (nightly check after two clean production runs, or a human for critic/agent findings). It omits idempotency and return 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?

Front-loads the access restriction, then the action, then the critical caveat. Every sentence carries information, though the final clause about 'the record shows the fix working, not just the fix shipping' is slightly rhetorical and could be tighter.

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

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

With no output schema and only a weak annotation, the description supplies the lifecycle context an agent needs: when to call, who may call, and that success does not mean the finding is closed. It lacks detail on what the record returns or whether repeat calls are safe, which is a minor gap for a 3-param mutation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic constraint by specifying the finding must be 'accepted' — narrowing which finding_id values are valid — and by tying pull_request_number to a PR that fixes it and is already open.

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: record the pull request that fixes an accepted self-review finding. This clearly distinguishes it from the read/list siblings (get-self-review-findings-tool) and the creation sibling (propose-self-review-finding-tool). An agent knows exactly what the operation writes.

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

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

Gives an explicit trigger condition ('Call it once the PR is open') and a scope gate ('Internal Coderbuds staff only'), plus the important negative: this does not resolve the finding. It does not name alternative tools for resolution, but the when-to-use context is concrete.

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 only `destructiveHint: false` provided, the description carries most of the burden and does so well: it discloses the access restriction (internal staff only), that the operation is a record of a past event rather than an action, and the downstream effects (populates the `outreach` field in `get-signup-funnel` and shows as 'contacted' on the admin trials page). It doesn't cover idempotency or what happens on duplicate entry.

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 staff-only restriction and the core action are front-loaded, and the paragraph break separates purpose from usage rules. A few sentences are slightly redundant ('Only call this when you have been told it went out' overlaps with 'Sending is not something this tool does'), but nothing is padding.

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

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

For a 6-parameter mutation with no output schema and minimal annotations, the description supplies access restrictions, the when-to-record rule, the downstream visibility, and the ID source. An agent has enough to call it correctly; only duplicate-handling behavior is unaddressed.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real meaning: it tells the agent where to source `team_id`, and explains why `sent_at` matters ('so the row shows how long the silence has really been'), which is motivation the schema lacks. The remaining parameters are left entirely to their schema text.

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 ('Record') on a well-defined resource ('a person reached out by hand to a signed-up account (a trial or customer team)'), and it explicitly clarifies that sending is out of scope. The parenthetical defining the target as a trial/customer team implicitly separates it from the prospect-side siblings, but it never names `record-prospect-outreach-tool`, 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?

'Only call this when you have been told it went out' is an explicit call condition, and 'Sending is not something this tool does' is an explicit exclusion. It also routes the agent to `get-signup-funnel` for the team `id`, and instructs passing `sent_at` for backdated records. It stops short of naming the closest alternative tool for prospect outreach.

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 only cover idempotentHint and destructiveHint; the description adds substantive behavior beyond them: reports are team-visible and attributed, re-reports refresh the existing record, and the response indicates whether Coderbuds' detector agreed with the report. It also clarifies that an empty review_evidence list is interpreted as 'no evidence' rather than a negative judgment.

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 core instruction (call once per change, use PR number or branch) is front-loaded and the enum guidance is well structured as a list. The opening paragraph spends several sentences on motivation and budget rhetoric, which is persuasive but not strictly needed for correct invocation.

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 9-parameter mutation tool with an output schema, the description covers when to call, how to pick authorship, how to enumerate review evidence, and how the response is used. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: it explains each authorship value operationally, defines what each review_evidence enum physically observed ('approved_each_edit' requires a permission-asking mode), and reinforces the empty-list convention. It stops short of explaining 'repository' binding or the deprecated 'human_reviewed' fallback beyond what the schema says.

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: report that the agent wrote or helped write a change, and how much. It is unmistakably a write/report tool, contrasting cleanly with read-only siblings like get-ai-adoption-tool or get-agent-activity-tool, and the first sentence alone lets an agent place it.

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

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

It gives explicit timing ('once per change, after the work is done'), explicit anchor alternatives ('pull_request_number' once the PR exists, 'branch' before it does), and states that re-reporting refreshes rather than double-counts, so re-invocation is sanctioned. It also tells the agent to set authorship honestly and enumerates the criteria for each choice.

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 only openWorldHint/destructiveHint declared, the description carries the behavioral burden and does so well: it discloses the two side effects (Slack message, PR comment), the reviewer-selection logic (rotation vs. named), and the attribution quirk that Coderbuds comments in its own voice rather than as the user — the kind of detail an agent cannot infer elsewhere.

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 action, and each sentence contributes either mechanism, attribution, or usage timing. Slightly padded by restating the repository naming convention already in the 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?

Output schema exists so return values need not be explained, and the description covers mechanism, side effects, selection logic, attribution, and timing for a 4-parameter tool. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns a bump by explaining the reviewer/rotation fallback behavior and the repository name-vs-full-name forms in prose. It adds meaning beyond the schema but repeats the repository format example verbatim.

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 (request a review on an open pull request) plus the exact mechanism: a Slack post to the team channel and a comment on the PR. No sibling tool does anything comparable, so an agent can route to it unambiguously.

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?

"Use this after opening a pull request, or when a PR has been sitting unreviewed" gives explicit triggering conditions. It doesn't name alternatives, but no sibling overlaps in function, so the omission is minor.

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 only declare destructiveHint=false, so the description carries the real burden and does: it discloses the side effect (the row is flagged as waiting on Elliot), the invariant that sends clear both flags, and the access restriction (Internal Coderbuds staff only). It also states a hard capability limit — nothing can be sent from here — that 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?

The two most decision-critical facts — staff-only access and the cannot-send division of labour — are front-loaded, and each paragraph addresses a distinct concern (permission, division of labour, content quality, side effects). Slightly long, but there is little 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 3-parameter mutation with no output schema, the description covers everything an agent needs: who may call it, what it writes, what state it sets, what clears that state, and how to handle the failure case (park via update-prospect). Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond by adding substantive quality semantics for `draft` — write the message itself, no placeholders, ground every claim in the worklist, state what is unverified. `needs_action_reason` is left entirely to the schema, which is acceptable given it is fully documented there.

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 — save an opener draft against a prospect — and positions it precisely in the workflow (the writing step, as opposed to the sending step). This clearly separates it from record-prospect-outreach-tool (recording an actual send) and update-prospect-tool (parking a row).

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

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

Gives an explicit when-to-use, an explicit when-not-to (if you can't write an honest opener, use `update-prospect` to park the row with the question), and an explicit boundary (you cannot send; Elliot sends). The routing decision to the sibling is spelled out rather than inferred.

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

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

Goes well beyond idempotentHint/destructiveHint by disclosing real consequences: 'off' still measures but never posts, 'preview' records without sending, nudges never DM under 'public', and human-approval in Slack is required regardless of posture. It also clarifies there are no per-capability settings, which prevents an agent from assuming granular override 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?

Front-loaded with the core purpose before the enum walkthrough, and every sentence carries decision-relevant information. It is somewhat long because the enum meanings appear in both the description and the schema, which is mild redundancy rather than 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 mutation tool with an output schema available, the description covers the safety profile, the permission requirement, the approval fallback, and the read sibling. There is nothing an agent needs in order to call it correctly that is missing.

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

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

Schema coverage is 100% and the enum values are already documented in the schema, so the baseline is 3. The description earns extra credit by adding semantics the schema lacks — notably that 'off' still measures and 'preview' records recommendations without sending — but it largely restates the enum list rather than adding format or edge-case 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?

Names a specific verb and resource ('Set how loudly the Coderbuds agent speaks to this team') and immediately frames it as 'the single control over whether it acts at all,' which delineates it from every read-only sibling. An agent can distinguish it from get-agent-activity-tool or the many get-* tools 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 enumerates every posture value with its operational meaning, states the prerequisite (team admin permissions), and explicitly routes to get-agent-activity-tool to inspect current posture and activity. The only mild gap is the absence of an explicit 'when not to use' clause, but the read-vs-write split with the named sibling covers the practical alternative.

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 `destructiveHint: true` and `idempotentHint: true` already declared, the description adds the crucial consequence that annotations cannot: setting the standard pins the number and disables Coderbuds' automatic loosening from then on. It does not clarify whether reverting to the default (omitting `target_lines`) also releases the pin, which is the one behavioral question an agent would still have.

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

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

Front-loaded with the action and its argument, then usage guidance, then the alternative path — a sensible ordering. It runs long and includes some normative framing ('it is not yours to set or to talk them out of') that is more policy than specification, though it does steer agent 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 two-parameter tool with an output schema and annotations, the description covers purpose, preconditions, consequences, and the alternative workflow. The remaining gaps — the repository binding role and whether reverting to default unpins the standard — are narrow but real for a tool that permanently alters team policy.

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

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

Schema coverage is 100%, so both parameters are already documented, including 'Omit it to revert to Coderbuds' default.' The description's 'tighter or looser' framing and 'pass the number they said' add minor semantic nuance but largely restate the schema, and the `repository` parameter is never mentioned in the description at all.

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: setting this team's pull request size standard, including the value shape (`target_lines`) and the omit-to-revert behavior. It is clearly distinct from the sibling `record-change-fit-decision-tool`, which it explicitly names as the preferred alternative path.

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

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

Gives explicit when-to-use ('when someone already knows the number and does not want to wait'), when-not-to-use ('You usually will not need this to make room'), the preferred alternative (recording overrides via record-change-fit-decision), and a hard precondition ('Only call it when a person has actually asked'). This is about as complete a routing instruction as a description can carry.

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

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

Annotations declare idempotent and destructive, and the description adds context the annotations cannot: nothing is enforced on GitHub, the agent always reviews a fixed set of high-risk change categories regardless of policy, and omitting vs passing an empty sensitive_paths list keeps vs clears existing config. That last point directly accounts for the destructive hint and is not a contradiction.

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 core action and constraints are front-loaded and the enum definitions are cleanly bulleted, so it is easy to scan. It is on the long side, with the always-review paragraph arguably more than the agent strictly needs to invoke the tool, which keeps it from a 5.

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

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

Given three parameters, an output schema, and destructive/idempotent annotations, the description covers everything an agent needs: what the policy causes, who may change it, how to preserve vs reset sensitive paths, and the enforcement boundary. No meaningful gap remains.

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

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

Schema coverage is already 100%, but the description goes well beyond it by defining the runtime meaning of each policy enum value and by explaining sensitive_paths syntax (folder form, `*` wildcard reaching into subfolders, omit-to-keep vs empty-to-clear). The schema only says 'The policy the team asked for, or off.'

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 gives a specific verb and resource — choosing how much review the team's PRs need — and the body spells out the resulting behavior (Coderbuds assigns a tier and comments why). It does not explicitly contrast itself with adjacent configuration siblings like set-change-fit-standard-tool or set-agent-posture-tool, so it stops short of full sibling differentiation.

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

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

It states clearly when to call ('Only call this when a person on the team has asked for it, and set what they said') and includes a hard prerequisite ('Only the team owner can change it'). The per-policy breakdown of skip_trivial vs risk_based vs off effectively tells the agent which value to select under which conditions.

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 name implies a mutation, and the description resolves that ambiguity by saying it 'Returns the steps to carry out' — consistent with readOnlyHint=true and idempotentHint=true. It also spells out what the caller will end up doing (writing guidance, committing the MCP connection, opening one PR), which is useful context beyond the annotations. It does not describe the shape or ordering of the returned steps in any detail.

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 trigger condition, then the action sequence, then parameter guidance — a sensible order with no filler. The step enumeration is slightly dense but each clause carries information the agent needs to sequence the work.

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

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

There is no output schema, so the description carries the burden of explaining the return value — and it does, describing the steps returned and the terminal verification call. It also states the expected end state (one pull request), which is what an agent needs to call this correctly and act on the result.

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

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

Schema coverage is 100%, so the schema already documents both parameters and the baseline would be 3. The description adds rationale rather than syntax: `repository` exists 'so the committed connection is pinned to its team,' and `via_plugin` changes what gets committed (plugin vs. a second copy of the server). That is genuine meaning beyond the schema text.

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 (set up / connect / wire) and a specific resource (this repository to Coderbuds), and clarifies that the tool returns instructions rather than performing the setup itself. That framing separates it cleanly from siblings like deploy-repository-tool and link-repositories-tool, which act rather than prescribe.

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

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

Gives an explicit trigger condition: 'Call when the person asks to set up, connect or wire this repository to Coderbuds.' It also names the required follow-up call (get-team-context) to verify success. It stops short of saying when not to use it or explicitly pointing to deploy-repository-tool/link-repositories-tool as alternatives for adjacent requests.

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?

`destructiveHint: true` already tells the agent this overwrites state, and the description adds real side-effect context the annotation cannot express: clearing `answer` removes the row from the queue, and unverified signals get flagged before sending. What it omits is what happens to fields not passed (overwrite vs. merge) and any permission model beyond 'internal staff only' — significant for a 13-parameter mutation.

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 access constraint and the one-line purpose, then segmented by bold rule headers so an agent can scan to the relevant rule. It runs long and re-states some points already carried in the schema descriptions (`checked_on`, `answer`, `answer_options`), which costs it a point.

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 13-parameter destructive update with no output schema, the description covers the domain rules an agent cannot infer: the stage vocabulary and its exceptions, the correction-not-deletion norm for `qualification_needed`, and the appearance of a `answered` list on return. It leaves the full response shape and merge-vs-replace behavior 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 coverage is 100%, so the baseline is 3, and the description earns above it by giving cross-parameter semantics the schema states only piecemeal: `answer_options` become buttons while prose stays a textarea, and `answer: null` is the pair-clearing act rather than a value. It stops short of explaining interaction between `stage`, `closed_reason`, and `qualification_needed`.

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

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

Opens with a specific verb and resource ('Update one prospect') and enumerates the four kinds of change it carries: research findings, stage, next step, and whether a person is needed. It implicitly separates itself from the outreach-recording path ('never set `contacted` yourself — recording a send does that'), though it never names the sibling tool.

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

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

Unusually explicit about when and how to use it: park blocked rows via `needs_action_reason` and carry on, pass options when the question ends in a choice, pass `answer: null` only after acting, never self-set `contacted`, and `closed` requires `closed_reason`. Each rule pairs a condition with the action that satisfies it.

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