Coderbuds

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

No annotations are present, so the description carries the full burden, and it does disclose real behavior: the staff-only restriction and that every row starts at 'Sourced' regardless of passed values. It stops short of saying what happens on a duplicate (rejected, merged, or created anyway) or what is returned, so a small but meaningful gap remains.

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 access restriction is front-loaded and the ICP, exclusion, and data-quality guidance are all actionable. It is slightly verbose with stylistic asides ('a row nobody can act on later'), but every paragraph carries information the agent needs.

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 mutation with no annotations and no output schema, the description supplies the domain rules (ICP, GitLab exclusion, dedupe prerequisite, default status behavior) that schemas cannot express. It is close to complete; only duplicate-handling outcome and return behavior are left unstated.

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

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

Schema description coverage is 100% on all 12 parameters, so the schema already defines kind, signal, source_url, qualification_needed and the rest. The description adds emphasis on signal quality and the significance of qualification_needed, but no syntax, format, or enum detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Add a company or adviser to the outbound pipeline') and the next line disambiguates the sibling space by describing the buyer and the GitLab exclusion. An agent can distinguish this from save-prospect-draft-tool and update-prospect-tool without opening schemas.

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

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

Gives an explicit audience restriction ('Internal Coderbuds staff only'), an explicit exclusion (GitLab-only teams are not prospects), and a named alternative with a condition ('Duplicates are worth checking for first with get-prospect-worklist'). That is when-to-use, when-not-to-use, and the alternative all in 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 no annotations, the description carries the full burden and does so richly: it enumerates all four verdicts and their thresholds, discloses that an opinionated default-on standard overrides team norms (team_norms.target_total_changes), explains how test/docs/generated/binary content is discounted, and warns that reported values are recorded and visible to the 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?

It is well front-loaded, leading with the purpose, verdicts, and the numstat recommendation. However it runs six paragraphs and repeats the discounting rationale for numstat, test_lines, and moved_lines in several places, so not every sentence earns its place.

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

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

An output schema exists so return values need not be explained, and the description still covers the verdict taxonomy, the scoping behavior of repository, the discounting model, and the recording workflow. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it establishes the precedence rule that numstat supersedes test_lines/test_files, explains the review_goals semantics (outcomes not layers, 1/2/3+ thresholds) and the purpose of scope_rationale as preserving context without waiving the standard. This augments rather than repeats the schema.

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

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

The opening sentence states a specific verb and resource: a 'pre-flight fit check' for a change about to be opened as a pull request, with the exact inputs (additions, deletions, changed-file counts). It clearly distinguishes itself from siblings by naming record-change-fit-decision-tool as the follow-up tool for recording the outcome.

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 framing ('change you are about to open as a pull request'), a concrete recommended path (pass numstat and review_goals), and explicit routing to record-change-fit-decision-tool when the verdict is not 'fits'. It also states the alternative input modes (numstat vs manually declaring test_lines/moved_lines) and when each applies.

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 empty annotations, the description carries the full burden and it does: this 'ships whatever is currently merged', is 'not a dry run', and requires a preconfigured deploy trigger. Those are exactly the mutation-effect and precondition facts an agent needs before invoking a write operation.

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

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

Four sentences, each earning its place: action, precondition, identifier format, destructive nature, alternative tool. The most consequential fact ('not a dry run') is present and front-loaded enough to catch the eye.

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 already defining return values, the description covers action, precondition, identifier forms, irreversibility, and the read-first alternative. Nothing an agent needs 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 practical identification guidance — a short name like "saas" versus full name like "patchstack/saas" — plus the team-connection and deploy-trigger requirement. It goes slightly beyond the schema text without adding format details the schema already supplies.

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 ('Trigger a production deploy') and resource ('one of your team's connected repositories'), with the scope narrowed to production. An agent can distinguish it from read-only siblings like get-deployments-by-person-tool or get-undeployed-pull-requests-tool at a glance.

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

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

Explicitly states a precondition (must have a deploy hook URL or GitHub Actions workflow configured), names the sibling to use first (GetUndeployedPullRequestsTool) and gives the condition that selects it ('if you want to see what will go out'). Nothing is left to inference.

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

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

Annotations only cover read-only and idempotent behavior, but the description adds substantial context beyond that: the scoring model (start at 100, subtract size/lines/files/complexity/focus/title-description/cross-area penalties), a bounded AI adjustment of at most ±20, and explicit exclusions (no CI results, no linter). It also constrains reporting to the returned `factors`, preventing fabricated explanations.

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 and a concrete example use case, then a second paragraph on methodology and caveats. Every sentence carries information, though the methodology paragraph is slightly dense and could be trimmed 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?

Output schema exists, so return values need no explanation, yet the description still clarifies the shape of the response and the scoring rationale. The exclusions (CI, linter) and the instruction to report only returned factors close the remaining ambiguity for an explain-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% and both parameters are documented in the schema with format examples ('owner/name', PR number 1186). The description adds no additional parameter-level detail, so the baseline of 3 for a fully-documented schema is appropriate.

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

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

States a specific verb and resource: explain why one specific PR received its score and label. The description also enumerates exactly what it returns (score, label, size counts, penalties with point cost, AI adjustment, breakdown), which clearly separates it from sibling metrics tools like get-pull-request-metrics-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?

Gives explicit trigger scenarios such as someone asking 'why is #1186 marked poor' or wanting to understand a low score on their own PR, and it defines the scope as one specific pull request. It does not, however, name an alternative sibling (e.g. get-pull-request-metrics-tool) for aggregate or cross-PR comparisons.

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 readOnly/idempotent; the description adds substantial behavior beyond them: bot PRs excluded, review history pruned at 90 days, backlog measured but never named, deploy stages scored only against repos with recorded production deployments, per-stage analysed counts, and unlock strings for unmeasurable stages.

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 core question and the six-stage framing, then orders caveats logically. It is unusually long for two parameters, and some caveat prose could be tightened, but nearly every paragraph carries an operational rule an agent needs.

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 explain return values, and it instead covers the interpretive edge cases an agent would otherwise get wrong: excluded bots, clamped window, never-bottleneck backlog stage, deploy-stage eligibility, and how to relay unlock notes.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 1-90 clamp rationale. The description restates the pruning-driven clamp and the blind-spot logic but adds no new syntax or format meaning beyond the schema, so the baseline of 3 applies.

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

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

Names a specific analytical verb sequence (split into six stages, time each, name the slowest) over a specific resource (recently merged pull requests). An agent can distinguish this from get-dora-metrics-tool or get-pull-request-metrics-tool because the description pins the output to a single named bottleneck stage.

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?

Clearly states when to reach for it ('why is our delivery slow' with one stage instead of five dashboards) and when an intervention is stage-dependent. It does not name a sibling tool as the alternative, so it falls short of an explicit routing rule, but the context 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 already signal readOnlyHint=true and idempotentHint=true, so the safe, non-mutating nature is covered. The description adds value by disclosing the team scope and the specific categories of information returned, which is exactly the behavioral context an agent needs beyond the annotations.

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

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

Two sentences with no filler: the first states what the tool does and its scope, and the second lists the return content. Every sentence earns its place and the key action is front-loaded.

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

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

Given zero parameters, read-only and idempotent annotations, and the existence of an output schema, the description is complete. It covers scope, expected output, and the non-mutating nature, leaving no ambiguity about how or why the tool should be called.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The description correctly avoids inventing parameters and focuses on behavior; the schema coverage baseline of 4 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 the specific verb 'Get' and identifies a clear resource: a summary of autonomous agent activity for the authenticated user's team. It further clarifies purpose by enumerating the summary's contents (enabled agents, recent actions, per-agent stats, pending approval counts), which distinguishes it from sibling tools like get-person-activity-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 description provides clear context by scoping to the authenticated user's team and stating the tool returns a summary plus exact output categories. It does not explicitly state when not to use it or name a sibling alternative, but for a zero-parameter read-only summary tool, the context is sufficient.

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

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

Annotations only cover read-only/idempotent, and the description adds substantial behavioral detail beyond that: bot and dependabot PRs are excluded from the outcome comparison, the result explicitly states when samples are too small to compare, and the attribution block separates first-party reports from inferred diffs and grades the inference. This pre-warns the agent about data-quality caveats and error margins before it acts on 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?

The description is front-loaded with the core question and keeps every sentence substantive, with no filler. It runs long (~180 words) and the attribution paragraph could be tightened, but each statement carries operational 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 an output schema exists and annotations cover the safety profile, the description supplies everything else an agent needs: what the metric means, caveats about sample size and detection coverage, exclusion rules, and how to interpret attribution confidence. Nothing material to correct invocation is missing.

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

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

Schema description coverage is 100%, so both the period enum and the repository slug (including the important note that it resolves the team but does not filter metrics) are already documented in the schema. The description adds no parameter syntax, defaults, or format guidance beyond that. Baseline 3 is appropriate when the schema does all 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?

The description names a precise question the tool answers ('how much of this team's shipped work is AI-assisted') and enumerates the specific outputs: adoption rate, contribution intensity, AI-assisted PR rate, detected tools, detection confidence, and an outcome split on lead time and size. It also gestures at differentiation from siblings by naming report-ai-usage-tool as the source of first-party attribution data. An agent can distinguish this from get-mcp-adoption-tool and get-dora-metrics-tool from the description alone.

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

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

It gives explicit use cases ('is AI actually in our SDLC yet' and 'is it paying off') and frames the outcome split as the KPI vs adoption as a pilot metric, which tells the agent when this call is warranted. It also warns that results flag small samples and uncovered detection periods. However, it never states when NOT to use this tool or routes the agent to a specific alternative sibling for partial needs.

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 signal read-only and idempotent behavior, and the description adds substantial context: it counts from team repositories rather than the member list, includes non-members, reports unmatched_repositories instead of silently counting zero, and counts opened by provider-recorded time. It also discloses that the human-vs-bot split is always reported even when include_bots is false.

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?

Although longer than typical, the description is well-structured and front-loaded: a one-sentence summary, then when-to-use guidance, then counting semantics, then the merged-PR caveat. Every paragraph earns its place and helps the agent avoid real mistakes.

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 all parameters documented in the schema and an output schema available, the description supplies the missing context: which authors are counted, how scoping works, what happens with unmatched repository slugs, and how opened differs from merged. An agent has everything needed to select and invoke this tool correctly.

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

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

The input schema covers all three parameters with full descriptions, including defaults and repository slug matching, so the schema is doing the heavy lifting. The description reinforces that repositories is the exact source list and mentions unmatched_repositories, but it does not add substantial parameter-level meaning beyond the schema.

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

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

The description opens with a specific action: Count pull requests OPENED over a recent window, then adds the key breakdown dimensions: per repository, per author, and human-vs-bot/dependabot split. It also distinguishes itself from get-merged-pull-requests by explicitly saying opened is a different set from merged, and from per-person activity tools by explaining what each approach counts.

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

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

The description gives explicit trigger questions such as how many pull requests were created, opened or raised, and contexts like today, this week, on a repo, or across the team. It tells the agent when to prefer this over a per-person activity breakdown and names get-merged-pull-requests as the alternative for merges, adding that the two should never be presented as reconciling.

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, covering the safety profile. The description adds the default window (7 days) and that failed deploys are surfaced per person plus sorting, but doesn't discuss rate limits or return format details. Adequate but not rich.

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

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

Front-loads the core purpose and then gives an example and usage question. Slightly verbose with the example and last sentence, but every sentence adds value.

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

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

Given there is an output schema, the description doesn't need to detail return values, but it still summarizes what is returned (deploy count, failed count, repositories, team totals). For a single-parameter read-only tool with annotations and output schema, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents the 'days' parameter including its default and clamping. The description repeats the default (7 days) but adds no new syntax or format details beyond the schema.

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

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

States a specific verb (list), resource (production deployments by person), and scope (recent window). It distinguishes itself from siblings like get-dora-metrics-tool and get-person-activity-tool by focusing on who triggered deploys and failure counts, with a concrete example output.

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 provides the question it answers ('who has deployed to production this week and how much'), giving clear usage context. No explicit when-not-to-use guidance or named alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that results include period-over-period comparison and Elite/High/Medium/Low categorizations, which is useful context, but it discloses nothing about auth requirements, rate limits, or data freshness beyond the output content.

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

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

Two tight sentences that front-load the purpose and then enumerate the returned metrics; nothing is padded. Slightly dense in the second sentence but well organized.

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 values, and annotations cover read-only/idempotent behavior. Scope and metric coverage are stated; only cross-tool routing guidance is absent.

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 already documents its enum and default. The description contributes no additional meaning about period selection or how it affects the comparison windows, 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 (Get) and a well-defined resource (DORA metrics) scoped to the authenticated user's team, and enumerates the four metrics returned. The purpose is unmistakable, but the description makes no explicit contrast against siblings like get-pull-request-metrics-tool or get-team-overview-tool, so an agent gets no routing signal beyond the name.

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

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

There is no when-to-use guidance and no mention of alternatives; the only scope hint is 'authenticated user's team'. Given several sibling metrics tools, the description leaves all selection reasoning to the agent.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: only enumerations are flagged (passing mentions never reported), insufficient_data is returned for missing/BitBucket/unreadable repos, archived repos are skipped, and false drift is avoided. It stops short of disclosing return format or performance characteristics, but the safety and edge-case behavior is rich.

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

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

The lead sentence is a direct question that front-loads purpose, and each subsequent paragraph adds distinct value (rationale, return shape, scope rules, sibling differentiation). It is longer than strictly necessary, with some reinforcement of the 'rotted guidance is worse than none' point, but no genuinely wasted sentences.

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. Given the high compleixity of a drift-analysis tool, the description still covers scope exclusions, the enumeration-only rule, and the empty-file result, leaving nothing an agent needs in order to invoke 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 optional 'repository' parameter is fully documented there, so the baseline applies. The description adds only the default scope ('for each connected repository'), which mildly reinforces the all-repos default but does not extend syntax or meaning beyond the schema.

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

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

States a precise verb+resource: judging whether a repo's agent guidance file has drifted from the code it describes, with a concrete example (directories under app/Domain). It explicitly distinguishes itself from the nearest sibling, get-repo-readiness, so an agent can route between the two without opening either schema.

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

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

Gives explicit trigger conditions — before trusting a guidance file, when onboarding an agent, or when deciding to replace a hand-maintained inventory — and names both the alternative (get-repo-readiness) and the alternative call (get-team-context) with the condition that selects each.

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 known; the description adds real depth beyond that — an access restriction ('Internal Coderbuds staff only'), a warning that rules drift and must be re-read rather than trusted from old documents, and semantics for the returned groups (retired = abandoned wedges, evidence:null = ungrounded, proposed = non-binding). It doesn't specify output shape beyond the seven groups, but for a no-param read tool 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 access scope and purpose, then the primary usage directive, then a bulleted reading guide for the three tricky fields. It is on the longer side and carries a bit of narrative color about past outbound mistakes, but nearly every line maps to a decision the agent must make when calling.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates the seven returned groups and explains the meaning of retired, evidence:null, and proposed. Combined with the access restriction and the before-writing directive, 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?

The tool takes no parameters (0 params, empty schema), so there is no parameter semantics to describe and the baseline is 4. Nothing in the description is needed to compensate for a schema gap.

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

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

States a specific resource (the ICP / 'who it is for' rules behind /admin/prospects) and what it governs ('what an opener is allowed to say'), with a clear verb of retrieval ('as they stand today'). It also differentiates itself from siblings by naming get-prospect-worklist and propose-icp-rule, so an agent can place it 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?

Explicit guidance: 'Call this before writing anything to a prospect, alongside get-prospect-worklist', clarifying the worklist says who to write to while this says what the message must be. It names the alternative for the complementary case ('Use propose-icp-rule when outbound teaches you something this list does not say'), so both when-to-use and 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 cover the safety profile (readOnly, idempotent), and the description adds genuinely non-obvious behavior: the denominator rules (only login members still shipping code), how linked identities are deduplicated, and that calls are attributed by repository slug or ?team= binding rather than the web switcher's last team. That attribution note materially affects result interpretation and is not derivable from schema or annotations.

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

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

Front-loaded with the purpose and the report contents, then usage triggers, then edge-case semantics. Slightly long and the closing paragraph on call attribution is dense, but every sentence carries substantive information 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?

An output schema exists so return shape needn't be described, yet the description still enumerates what is reported, sets the default window, defines the population counted, and explains attribution — everything an agent needs to call and interpret this correctly.

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

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

Schema coverage is 100%, so both params are already documented, and the description restates the 30-day default and 1–90 clamp. It adds value by explaining what the repository param actually does semantically — binding the session to the owning team — which is more than the schema's mechanical wording.

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 — reporting MCP adoption per team member — and is clearly differentiable from the adjacent get-ai-adoption-tool by its explicit MCP focus. The opening sentence 'Who on the team is actually using the Coderbuds MCP' plus the enumerated contents (invocations, per-member usage, per-tool counts, nudge list) make the output scope 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 explicit trigger phrasings ('who is using the MCP', 'is the team on the MCP yet', finding who needs setup instructions) plus eligibility rules for who counts. It does not explicitly name a sibling alternative such as get-ai-adoption-tool, so the agent must infer the boundary, but the when-to-use guidance is clear and 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?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds real behavioral context beyond them: the result always carries a human-vs-bot split regardless of include_bots, and it returns total plus per-repository and per-author breakdowns. It doesn't mention pagination or window caps, but with annotations carrying the safety profile this is a strong addition.

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

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

Front-loads the core purpose and the key output guarantee in the first sentence, then the trigger condition last. It is somewhat long for three optional parameters and the example slug is slightly redundant with the schema, but no sentence is wasted.

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

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

An output schema exists, so return values needn't be explained, yet the description usefully summarizes the shape (total, per-repo, per-author). Combined with annotations covering read-only/idempotent behavior, an agent has enough to call it correctly; only alternative-tool routing is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description largely restates structured facts ('default 30 days', the include_bots split behavior, 'owner/name' scoping) rather than adding new syntax or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Count merged pull requests over a recent window') plus the two key dimensions it reports (human-vs-bot split, per-repo/per-author breakdowns). An agent can distinguish this from siblings like get-open-pull-requests-tool 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?

Explicitly supplies the trigger phrasing: '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.' That is clear context for invocation, but it never names an alternative sibling (e.g. get-pull-request-metrics-tool) or states when-not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that insights are 'active' and span all teams, but does not clarify what 'active' means (unseen? unresolved?), the return shape, or ordering/pagination.

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 compact sentences with the core purpose front-loaded and the filters following. No wasted filler, though there is no structural signposting beyond the single optional clause.

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

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

For a read-only, zero-required-parameter list tool with a fully documented schema and no output schema, the description covers scope and filtering adequately. The main residual gap is the meaning of 'active' insights and any ordering/limit interaction 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% and all three parameters (tab with enum, limit 1-25, unseen_only) are already documented in the schema. The description merely restates the enum values and the unseen filter, adding no syntax or default details beyond the structured fields.

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'), resource ('active insights'), and scope ('for the authenticated user across all their teams'). The 'my/user-scoped' framing implicitly separates it from team-level siblings like get-team-insight-summary-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?

The description notes two optional filters (tab category and unseen_only), which implies when those knobs are useful, but it gives no guidance on when to prefer this tool over alternatives such as get-team-insight-summary-tool or get-my-status-tool, and no exclusions.

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

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

Annotations cover readOnly and idempotent, so safety is already handled, but the description adds real behavioral detail beyond them: bots are excluded from the reviewer queue, recent merges default to a 2-day window, and the result should be relayed starting from the `headline` field. That is useful, non-obvious context for interpreting and presenting the output.

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 noun phrase is front-loaded and the long parenthetical enumerates exactly what counts as each blocker state, which is high-value rather than filler. The final directive sentence is terse and actionable. It is dense but nearly 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?

An output schema exists, so return shape need not be re-explained, and annotations cover the safety profile. The description still supplies the section breakdown and the 'lead with headline' presentation rule, leaving nothing an agent needs in order to call and relay this tool correctly.

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

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

Schema description coverage is 100%, so both parameters are fully documented in structured data, including the 1-30 clamp and the default. The description does not add any parameter-level meaning (no mention of repository binding or window sizing), so this sits at the baseline 3.

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

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

States a specific resource and scope ('Your personal cross-repo status') and then enumerates the exact sections returned: your open PRs and blockers, reviews you could unblock, merged-but-undeployed work, and recent ships. It is clearly distinguishable from siblings like get-open-pull-requests-tool or get-merged-pull-requests-tool because it is the aggregated personal composite rather than a single-list query.

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 use context — 'standup prep and morning brief in one call' — which tells the agent when this tool is the right pick over narrower siblings. It stops short of naming alternatives or stating when not to use it, so it earns a 4 rather than 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?

Goes far beyond the readOnlyHint/idempotentHint annotations: bot authors are collapsed to counts while humans keep oldest PRs with age, archived repos are excluded, oversized PRs are sorted to front and framed as 'blocked on being split', size.category=unknown means missing data not small, and status_freshness flags stale/missing PRs. These are non-obvious behaviors an agent could not infer from structured fields.

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

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

Purpose and the headline guidance are front-loaded, and the paragraphs are organized by concern (oversized rules, bot details, freshness). It is dense and somewhat long for a two-parameter read tool, but nearly every sentence carries actionable detail 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?

An output schema exists, so return-shape explanation is unnecessary, and the description still ties its guidance to specific output fields (headline, total_oversized, size.category, status_freshness). Nothing an agent needs 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 value: it explains the rationale for repositories scoping (with owner/name example) and the ordering semantics behind include_bot_details (ready-to-merge, then failing checks, then oldest). This exceeds what the schema text alone conveys.

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 (list open pull requests grouped by author) plus the blocking signal it surfaces, and distinguishes itself from get-merged-pull-requests-tool by scope. An agent can route on this without opening the schema.

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

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

Explicitly scopes the tool's purpose ('use this to nudge people to merge — lead with the headline') and gives a clear condition for the include_bot_details switch (working the dependency queue vs summarising a review queue). It stops short of naming a sibling alternative for other query shapes, so it is strong but not textbook when/when-not.

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 only readOnly/idempotent, but the description adds substantial behavioral context: the default 8-week window, the ambiguity-to-candidates fallback, the interpretation warning that a lone PR count misleads, and the not_captured limitations. This is exactly the kind of disclosure annotations cannot carry.

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 longer than average but front-loaded and nearly every sentence carries decision-relevant content (lead with headline, candidate handling, not_captured caveats). The parenthetical examples add some length without new routing value, keeping it just under maximum.

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 document return fields, yet it still orients the agent to key fields (headline, candidates, not_captured). For a read-only analytics tool this is complete enough to call and interpret correctly.

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

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

Schema coverage is already 100%, so baseline is 3, but the description reinforces identifier semantics ('dave', 'Dave Smith', '@dsmith') and explains why repository binds a session to the owning team. The days window rationale is left to the schema, so it does not fully exceed the baseline.

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

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

The description states a specific verb and resource ('what one person on the team has actually been doing, over a recent window') and even gives the concrete questions it answers. It distinguishes itself from siblings like get-agent-activity-tool and get-my-insights-tool by scoping to one named teammate over a recent window with three read-together counts.

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

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

It gives clear triggering questions ('is Dave still shipping?'), the accepted identifier formats, and explicitly tells the agent what to do on ambiguity (ask about candidates rather than guessing). It stops short of naming a sibling alternative or a when-not-to-use condition, so it is strong context without explicit exclusion 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 and idempotentHint, but the description adds substantial behavior the annotations cannot: the ordering of the five lists, the definition of done via stage_tests, the 'gate' fail verdict that says to stop, the max_touches follow-up rule, and the caveat that no row is a qualified lead. This is exactly the extra context annotations cannot carry.

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 staff-only scope and the core action, then structured as a list of five states with their rules. It is somewhat long, but nearly every sentence earns its place by describing a distinct list or rule; a couple of the caveat sentences 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?

For a no-required-parameter read tool with a single primary caller, the description covers the return structure (five named lists), the ordering, the key fields (needs_action_reason, answer, times_contacted, gate, stage_tests), and the caveats. Nothing an agent needs to use 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 schema documents both parameters with meaning, but the description reinforces the cap rationale ('a worklist for one session, not an export') and the quiet_days concept ties to the gone_quiet list. It adds conceptual context without full syntax detail, so a 4 rather than the 5 that extra syntax would merit.

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: returning the outbound prospect worklist behind /admin/prospects, structured as five named lists in working order. It is clearly distinguished from siblings like update-prospect or record-prospect-outreach, which mutate individual rows rather than read the whole pipeline.

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: 'Start every session working this pipeline by calling this,' and it names a failure mode ('without it the obvious move is to write to somebody who was written to on Tuesday'). It also routes to a specific alternative action ('clear the pair with update-prospect'), giving direct next-step guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that results include period-over-period comparison, which is genuine behavioral context, but says nothing about which team is resolved, freshness of the data, or any rate/permission constraints.

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

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

Two tight sentences with the scope front-loaded and no filler. The return-value enumeration slightly duplicates what the existing output schema already conveys, so it is not maximally economical, but nothing is wasted.

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

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

An output schema exists, so return values needn't be spelled out, and the sole parameter is fully documented. What remains missing is disambiguation from sibling PR tools and any statement of whose data ('team') is actually resolved, which keeps it short of 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. The description adds only the indirect hint of 'period-over-period comparison'; it does not explain period semantics (e.g., current vs previous windows), so the baseline 3 applies.

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

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

States a specific verb and resource ('Get pull request activity metrics') and scopes it to the authenticated user's team, then enumerates the metric categories returned. It does not distinguish itself from closely related siblings such as get-merged-pull-requests-tool, get-open-pull-requests-tool, or get-dora-metrics-tool, so an agent cannot cleanly separate it from them by description alone.

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

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

There is no when-to-use guidance and no named alternative. With ~28 siblings in this family, including several other pull-request metric tools, the agent is left to infer that this is the aggregate-metrics option rather than the list-based ones.

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 readOnlyHint/idempotentHint annotations, it discloses rich behavior: insufficient_data is always excluded and never counted against a repo, opt-out turns opinionated checks to insufficient_data, BitBucket repos get insufficient_data on content checks, archived repos are skipped, and dormant repos are exempted from wiring/deploy-recency checks and the rollup top_gaps.

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 core question and the key differentiator before the detail, and the edge-case sentences each carry distinct behavioral rules. It is dense and somewhat long, but for a tool with this many exceptions every sentence is doing 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?

For a complex zero-param tool with an output schema, the description covers what is judged, how results are classified (pass/fail/insufficient_data), what accompanies failures (plain-language gap and recommendation), the team rollup, and all the edge-case handling — leaving no significant gap for an agent 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?

The tool takes no parameters, so the 4 baseline applies. The description adds contextual scope (per connected repository, plus a team rollup) but there are no parameter semantics to elaborate.

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 question it answers ('Is this repo ready for agents?') and enumerates exactly what it judges: deploy automation, deploy recency, PR size discipline, review coverage, agent guidance, CI config, tests directory, and fit-check wiring. It explicitly distinguishes itself from the change-level sibling by noting it judges 'the repository a coding agent is dropped into — not the change it makes.'

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 a clear use context ('Call this to find what is holding a repo back before pointing an agent at it') and implicitly contrasts with change-fit assessment, but it never names the sibling tool (assess-change-fit-tool) or states explicit exclusions for 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?

Annotations already declare readOnlyHint and idempotentHint, yet the description adds substantial behavior beyond them: the staff-only access constraint, three milestones reported without medians, unreliable rates flagged on tiny samples, and a capped per-account list whose surrounding rates still span the whole cohort. These are exactly the caveats an agent needs.

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 access restriction is front-loaded and the two funnels are cleanly segmented with bullets. It is a dense paragraph of its length but nearly every clause earns its place by describing a distinct output or caveat; still, some prose could be trimmed 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?

An output schema already exists, so return values need not be explained; the description instead supplies the interpretive context (funnel stages, cohort window semantics, unreliable-rate caveats) an agent needs to use the results correctly. Nothing material is missing for a two-parameter read-only analytics tool.

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

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

Schema description coverage is 100% and both parameters carry good inline docs, so the baseline is 3. The description reinforces the journey_limit cap ('the per-account list is capped while every rate beside it is over the whole cohort') but adds no syntax or format detail beyond the schema.

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

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

The description states a specific verb and resource (signup and conversion funnel across every account) and differentiates itself from all siblings, which cover DORA, PRs, adoption, deployments, etc. It even distinguishes itself internally from the account funnel it builds on ('This is the only stage the account funnel structurally cannot see').

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 intended questions ('why signups stall, which step loses the most people, whether a change to onboarding moved anything, who is worth an email') and an access restriction (staff only), so the agent knows when to reach for it. However, it names no alternative sibling to use instead in adjacent cases, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds genuinely useful behavioral context: all data is derived from live shipping data and never goes stale, and the focused-map mode degrades non-relevant repos to names only. It does not describe volume/latency or pagination, but the value-add beyond annotations is real.

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

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

Front-loaded with the resource and its contents, then the parameter-driven mode, then alternatives. Dense and mostly earned, though the first paragraph's compound enumeration is long enough to border on overload for a read-only lookup 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 so return values need not be explained, and annotations cover the safety profile. Given the tool's complexity, the description still covers scope, focused vs. full modes, data freshness, and escalation paths to three sibling tools — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the semantic effect of `repository` — binding the session to the owning team and focusing the map — which is more than a restatement of the schema's type/format note.

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 artifact (the team's org map) and enumerates its contents: repositories shipped to, liveness signals, deploy paths, readiness flags, repo relationships, and confirmed conventions. It is clearly distinguishable from siblings like get-team-overview or get-repo-readiness, which it explicitly delegates detailed checks to.

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 the exact selection rule: pass `repository` to get a focused map, described as 'the right call at session start in a multi-repo org, instead of pulling the whole atlas.' It also routes to alternatives by condition — get-repo-readiness for full checks, link-repositories when the map is wrong, and assess-change-fit for size/review norms.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the safety profile is already conveyed. The description adds scope ('authenticated user's team', 'active insights') which tells the agent the data is implicitly scoped with no parameters. Beyond that it doesn't disclose return format, freshness, or how 'active' is defined, so it's adequate but not rich.

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

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

A single well-formed sentence that front-loads the resource ('aggregate summary of active insights') and then lists the components of the summary. No wasted words, no redundancy. Slightly dense with the final enumeration, but appropriate for the scope.

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

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

For a parameterless read tool with annotations covering safety, the description covers the essentials. However, with no output schema the description must at least gesture at the return shape, and it does ('counts per tab', 'unseen count', 'personal insight count') which is reasonable. What's missing is any differentiation from sibling insight/team summary tools, which matters given the crowded namespace.

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 are zero parameters, so there is nothing for the description to document or for the schema to under-cover. Baseline is 4 for a no-param tool. The description correctly indicates the implicit scoping (authenticated user's team) which is the only relevant semantic 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: aggregate summary of active insights scoped to the authenticated user's team, and enumerates what it returns (counts per tab, unseen count, personal insight count). It's clear what the tool does, but it never distinguishes itself from close siblings like get-my-insights-tool or 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 when-to-use guidance, no exclusions, and no reference to alternatives. With siblings such as get-my-insights-tool and get-team-overview-tool that plausibly overlap, the agent is left to guess which tool to invoke. The description only implies context ('team', 'insights') without 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 the safety profile is covered structurally. The description adds the aggregate nature of the call and the metric categories it returns, but no behavioral detail beyond that (e.g. cost, latency, freshness of data). An output schema exists, so return-value disclosure is not needed here.

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

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

Two sentences, no filler, and the core purpose is front-loaded before the usage hint. The middle metric enumeration is dense but earns its place by conveying scope.

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

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

With annotations covering safety, a fully documented single parameter, and an existing output schema, the description supplies enough for an agent to call it correctly. The only shortfall is the absence of explicit sibling disambiguation in a crowded toolset.

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 (period) and schema description coverage is 100%, with the enum values and the rolling_30d default fully documented in the schema. The description adds nothing about period 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?

States a clear verb (Get) and resource (team health overview) and enumerates the metric families it aggregates (activity, DORA, collaboration, efficiency) under an explicit SPACE framework. This gives strong cross-domain scope, but it does not explicitly distinguish itself from adjacent siblings such as get-dora-metrics-tool or get-team-insight-summary-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 phrase 'Use this for a single-call snapshot of team engineering health' gives an implied usage context (aggregate view). However, it names no alternative sibling and provides no when-not guidance, so with many overlapping team/insight tools the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description goes well beyond that, disclosing the key behavioral rule that PRs predating the latest successful production deploy are assumed shipped and surfaced via `assumed_deployed` rather than as false-positive undeployed entries, and that deploys ship the default branch. This kind of edge-case handling is exactly the context an agent needs.

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 core definition and the deploy-lag signal, then closes with the important false-positive caveat. Every sentence earns its place with no filler.

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

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

An output schema exists, so return-value explanation is unnecessary. Given the tool's moderate complexity, the description covers purpose, usage context, and the non-obvious deploy-assumption behavior, leaving no meaningful gap.

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

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

Schema description coverage is 100%, and lookback_days is fully documented in the schema (default 14, clamped 1-90). The description adds no parameter detail, so the baseline of 3 applies since 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 ('List merged pull requests that have not yet shipped to production') plus scope ('grouped by repository'). By filtering on 'not yet shipped to production', it implicitly distinguishes itself from the sibling get-merged-pull-requests-tool and get-open-pull-requests-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?

Explicitly states the use case: 'Use this to spot work that is merged but stuck before deployment.' That gives clear context for when to reach for it. However, it never names an alternative (e.g., use get-merged-pull-requests-tool for all merged PRs), so there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that output covers the user's team specifically and enumerates the summary sections, which is useful context, but says nothing about auth requirements, caching, or freshness beyond 'latest'.

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 in the first sentence, followed by content enumeration and a short paging hint. Every sentence carries information, though the content list is somewhat verbose given an output schema already exists.

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

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

For a zero-required-param, read-only retrieval tool with a full output schema, the description covers purpose, scope, and the paging parameter adequately. The only shortfall is the absence of sibling differentiation among the several summary/insight tools.

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

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

Schema description coverage is 100% and the single parameter already documents the 0 = most recent / max 4 semantics. The description only restates that weeks_ago fetches older summaries, adding no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get the latest weekly changelog summary') scoped to the authenticated user's team, which tells an agent exactly what it returns. It does not distinguish itself from similarly named siblings such as get-team-insight-summary-tool or get-my-insights-tool, leaving potential overlap ambiguous.

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

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

The only usage sentence ('Use weeks_ago to retrieve older summaries') describes how to page backwards, not when this tool is the right choice versus alternatives. No when-not conditions or sibling routing are provided.

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

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

Annotations only provide idempotentHint=true, so the description carries most of the burden and does so well: it discloses that re-teaching refreshes the edge, that links are team-visible and attributed, and that `unrelated` suppresses derived connections. It does not cover failure/auth conditions, keeping it short of a 5.

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

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

Purpose is front-loaded in the first clause and the relation legend follows immediately; every sentence adds usable information. It is on the longer side for a 4-param tool, but 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?

An output schema exists, so return values need not be explained, and the description already covers scope, directionality, idempotency, and visibility. What remains thin is error/prerequisite behavior (e.g. same-team requirement is only implied by the schema), leaving it just short of complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining the reading direction ('repository <relation> to_repository') and giving each enum member concrete semantics (depends_on = consumes an SDK/package/service; ships_with = changes here usually mean changes there). This adds interpretive value beyond the raw enum 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?

Specific verb+resource: it teaches the team's org map how two repositories relate, and it explicitly names the downstream effect on sibling get-team-context-tool. The relation vocabulary is spelled out, so an agent can tell this apart from read-only context tools at a glance.

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?

Clearly states when to use it: 'when you discover a relationship the map is missing, or when the user tells you how repos fit together.' Context is unambiguous, though no explicit when-not-to-use or named alternative is given beyond the get-team-context reference.

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 idempotentHint=true; the description adds that the mark is per-authenticated-user and that it suppresses noise in future queries, which is useful side-effect context beyond the annotations. It does not disclose permission requirements, whether the mark is reversible, or the response shape.

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

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

Two tightly written sentences with the action front-loaded and the rationale second. No wasted words, though the second sentence is soft justification rather than operational detail.

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

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

For a one-parameter, idempotent marker with no output schema, the description covers what the tool does and why it exists. The only real gap is the absence of guidance on when to invoke it versus the read-side insight siblings.

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% (the single insight_id is fully documented), so the schema already carries the parameter meaning. The description adds nothing beyond restating which insight is targeted, which is the expected baseline when 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 (mark), a specific resource (insight), and the resulting state (seen) scoped to the authenticated user. It is clearly distinct from sibling readers like get-my-insights-tool, but it never names or differentiates against those siblings explicitly.

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

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

There is no when-to-use guidance, no prerequisite for what a valid insight might be, and no mention of how this relates to get-my-insights-tool. The clause about reducing noise vaguely implies intent but gives the agent no routing condition.

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?

No annotations are present, so the description carries the burden, and it does disclose real behavior: the proposal 'does not govern anything until a person adopts it', omission of evidence is surfaced as 'ungrounded', and the tool is internal-staff-only. It stops short of describing return shape or idempotency, so not a 5.

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

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

Purpose and the non-governing caveat are front-loaded, and the when/when-not guidance follows. It is on the long side with some prose flourish ('the same division as drafting an opener you cannot send'), but nearly every sentence carries routing or constraint value.

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

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

With no output schema and no annotations, the description supplies what an agent needs: the write is a proposal not a live rule, where it appears, who it is for, and how ungrounded evidence is represented. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains what evidence is ('the reply you read, the measurement, the count of rows'), the consequence of leaving it out, and gives usable vs. unusable examples for statement. It does not elaborate on the 'kind' enum-like values 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 (propose) and resource (a rule about who Coderbuds is for / what an opener may say), plus exactly where it lands ('Who it is for tab of /admin/prospects'). This cleanly separates it from read-side siblings like get-icp-tool and from record-prospect-outreach-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?

Gives an explicit trigger ('Propose when outbound has taught you something the current rules do not say') with concrete examples, and explicit exclusions ('Do not propose a tidier wording of a rule that already exists', 'do not re-propose something in retired'). It also states the staff-only restriction, so the agent knows who may 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?

Annotations carry only idempotentHint, so the description does the heavy lifting: it discloses the default check binding, that the response may carry a `standard_adjustment`, that `reason` is visible to the team, and that the record is permanent and read back by the team. It also sets expectations about what the agent should and should not do after recording.

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 key instruction, but the description runs to six paragraphs with repeated persuasion (the "nagging" argument is made twice). The behavioral coaching earns some of its space, but the same points are restated rather than compressed.

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 enumerated, yet the description still flags the one non-obvious response field (`standard_adjustment`). Combined with defaults, override rationale, and post-call behavior, an agent has everything needed to invoke and follow through 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%, so the baseline is 3, but the description adds real meaning: plain-language glosses for each enum value in context, guidance that `reason` is "required in spirit" when proceeding, and how `check_id` defaults. It does not add format or length guidance beyond the schema's 500-char note.

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: recording what you did about an `assess-change-fit` verdict. It explicitly names the sibling tool that produces the verdict it answers, so an agent can immediately place it in the workflow.

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 timing ("call this right after you act on one — especially when you override it"), names the upstream alternative (assess-change-fit), and explains that overrides are a legitimate, expected case. The default behavior (most recent undecided check, so only `decision` and `reason` needed) is 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?

With no annotations provided, the description carries the full burden and does so: it discloses the state transition (Sourced → Contacted), the side effect on the pending draft ('folded into the record and cleared'), the duplicate-send protection, and the downstream consequence of a false record ('the next session skips it'). It also states the audience restriction ('Internal Coderbuds staff only'). Only return format and failure behavior are unaddressed.

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 critical constraint in bold, then the justification, then the prohibition and the alternative. Four short paragraphs, each earning its place, with no restatement of 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?

No output schema exists, and the description doesn't say what a successful record returns or how it behaves on an invalid prospect_id. Everything an agent needs to decide whether to call the tool is present, so the gap is minor rather than disqualifying.

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 the schema: it explains that a draft waiting on the row is folded into the record and cleared, which is why `note` can be omitted. That interaction between the default and the row state is not visible from the schema alone.

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' — with a temporal qualifier ('after it has actually been sent'). It is immediately distinguishable from save-prospect-draft, which it explicitly contrasts. An agent can select this 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?

Gives an explicit trigger ('Only call this when you have been told it went out') and an explicit negative case ('Sending is not something you can do'). It names the alternative sibling (save-prospect-draft) and the exact workflow that routes there instead. Nothing is left to inference.

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

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

Beyond the idempotentHint annotation, it discloses that reports are team-visible and attributed to the caller, that re-reporting refreshes rather than double-counts, and that the response compares the caller's report against the service's own detector with the caller's value winning. It stops short of stating permission requirements or error behavior.

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

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

Front-loaded with the core action and organized into purpose, timing, field guidance, and behavior. Some of the motivational framing ('a heuristic that decides where a CTO spends budget') and the restatement of the authorship enum definitions duplicate schema text rather than earning their space.

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

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

An output schema exists, so return-value documentation is not required, and the description still explains the salient part of the response. Combined with timing, anchor choice, and enum semantics, it covers what an agent needs; only auth/error detail is absent.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds decision guidance the schema does not: which of pull_request_number vs branch to supply and when, and why human_reviewed should be answered honestly. That is real interpretive value on top of the field definitions.

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

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

The description states a specific verb and resource: report AI authorship of a change, with explicit scope ('wrote or helped write this change, and how much of it'). It is immediately distinguishable from read-side siblings like get-ai-adoption-tool, which surface the aggregate numbers this tool feeds.

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 timing ('once per change, after the work is done'), an anchor-selection rule (pull_request_number once the PR exists, branch before it does), and a re-call policy ('safe to call again as the work evolves'). It also distinguishes the three authorship values with concrete conditions for choosing each.

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

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

With annotations empty, the description carries the full burden and does well: it discloses the Slack post, the reviewer-rotation vs. named-reviewer selection logic, the PR comment, and the important persona detail ('Coderbuds speaks in its own voice; it does not comment as you'). It omits failure modes (e.g. what happens if the rotation is empty or Slack is unlinked), so not a full 5.

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

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

Front-loaded with the core action, then mechanism, then timing, then a naming hint. Every sentence contributes, though the mechanism sentence is somewhat long and could be tightened slightly.

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

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

For a mutation-style side-effecting tool with an output schema (so return values need no explanation), the description covers action, side effects, persona, and timing well. The main remaining gap is what happens on failure (no rotation, unlinked Slack).

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description only restates the repository naming format, adding nothing beyond what the schema provides, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Ask the team for a review on an open pull request') and immediately details the mechanism (Slack post + PR comment). No sibling tool does anything similar, so it is unambiguously distinguishable from the surrounding read-only get-* / assess-* tools.

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

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

It gives clear triggering conditions: 'Use this after opening a pull request, or when a PR has been sitting unreviewed.' There is no explicit when-not guidance, but since no sibling performs this action there is no real alternative to disambiguate against.

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 no annotations, the description carries the burden well: it discloses the staff-only restriction, the side effect of flagging the row, and that a later send record clears the flag. It stops short of saying whether re-saving overwrites an existing draft or what the tool returns, so it is strong but not exhaustive.

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

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

Front-loads the staff-only constraint and the core action, then layers guidance. The bolded 'You cannot send anything' and the closing rationale are slightly repetitive, but nearly every sentence adds operative detail 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?

For a mutation tool with no annotations and no output schema, this covers the essential context: who may call it, what it changes, and which sibling to use instead. Only the return value/confirmation shape is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for `draft` beyond the schema ('write the message itself, not a description of one — no placeholders'). It adds nothing extra for `needs_action_reason`, which the schema already documents including its default.

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 against a prospect'), names the consumer (Elliot) and the side effect (flags the row as waiting on him). An agent can separate this from record-prospect-outreach-tool because the description explicitly says 'Recording the send later clears both.'

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 and when-not-to-use: write here if you can produce an honest opener, otherwise use `update-prospect` to park the row with the question. It also states the division of labour (you research/write, he sends) so the agent knows this tool never sends.

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 idempotentHint annotation, the description details exact behavioral outcomes for every enum value: 'off' still measures but never posts, 'preview' records without sending, 'public' never DMs, and human-required actions still ask for approval. It also discloses the team-admin permission requirement, all of which is valuable context not present in 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 the core purpose, followed by a structured enumeration of the five values, then caveats and prerequisites. Every sentence contributes distinct information, and the organization makes it easy for an agent to scan, even with the density of content.

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

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

Given a single enum parameter, an output schema (presumably returning result/status), and idempotence annotation, the description covers everything needed to invoke correctly: permission level, per-value behavior, cross-tool guidance, and the absence of finer-grained controls. No significant context 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 documented, so the baseline is 3. The description enriches the semantics by clarifying ambiguous terms: 'preview' means 'without performing or sending them', 'public' means 'never to DMs', and 'off' still includes measurement. This adds tangible meaning beyond the schema.

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

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

The description opens with 'Set how loudly the Coderbuds agent speaks to this team', a specific verb and resource, and immediately states it is 'the single control over whether it acts at all.' This clearly distinguishes it from the sibling get-agent-activity-tool and any per-capability setters, so an agent can identify its unique role.

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

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

The description gives explicit usage context: requires team admin permissions, directs the agent to get-agent-activity-tool for viewing current posture, and warns that there are no per-capability settings. This is effectively a when-to-use, when-not-to-use, and alternative-tool instruction set.

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 idempotentHint=true, so the description carries the behavioral burden and does so richly: setting the number pins it, Coderbuds 'stops adjusting this team's standard from then on, including the automatic loosening,' and omitting target_lines reverts to the default. These are non-obvious consequences an agent could not infer from the schema or annotations.

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

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

Front-loaded with the action and its parameter before the rationale and alternatives. Some sentences verge on repetition and moralizing ('it is not yours to set or to talk them out of'), but each still carries actionable routing or precondition information.

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

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

All parameters are optional and fully documented in the schema, an output schema exists so return values need no explanation, and the description supplies the missing piece — the side effects and when-not-to-use. Nothing an agent needs to call this correctly is absent.

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: target_lines is 'their number — tighter or looser,' conveying directional semantics, and it restates the omit-to-revert behavior as an intentional action. The repository parameter's binding purpose is left to the schema, keeping this just above baseline.

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

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

States a specific verb and resource with scope: 'Set this team's pull request size standard.' The team-scoped framing and the contrast with recording overrides clearly separate it from siblings like record-change-fit-decision-tool and 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?

Explicitly routes the agent: 'You usually will not need this to make room,' explains the automatic loosening path, names recording overrides as 'the better path,' and gives the exact condition for using this tool ('when someone already knows the number and does not want to wait'). It also states the precondition 'Only call it when a person has actually asked.'

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 are empty, so the description carries the full burden and largely meets it: it discloses the audience restriction ('Internal Coderbuds staff only'), the side effect of clearing an answer pair (takes the row off the queue), that unchecked signals get flagged before sending, that `closed` requires a readable reason, and that corrections should preserve qualification_needed rather than delete it. These are exactly the mutation semantics an agent needs and cannot get from the schema alone.

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

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

Front-loaded purpose sentence, then bolded lead-ins that make each rule scannable, and every paragraph encodes an operational rule rather than filler. It is long, however, and a few points restate the schema docstrings (e.g. the checked_on rationale appears in both places), so it is not 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?

For a 13-parameter mutation tool with no annotations and no output schema, the description covers stages, transition rules, and queue mechanics well. It never states whether omitted fields are left unchanged (the key behavior for a partial-update endpoint) and says nothing about failure/response shape, which is the main remaining gap.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds genuine semantics beyond the schema: needs_action_reason is framed as the escalation channel, answer_options are explained as buttons versus a prose question that stalls, and `answer: null` is explained as the queue-clearing action rather than a free string. That is real added meaning over the field docstrings.

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

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

Opens with a specific verb+resource ('Update one prospect') and immediately enumerates the kinds of fields it touches (research findings, stage, next action, human escalation). It also distinguishes itself from a sibling mechanism with the rule 'never set `contacted` yourself (recording a send does that)', which routes the agent to record-prospect-outreach-tool rather than this one for that transition.

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 conditions for each non-obvious parameter: park blocked rows via needs_action_reason, send answer_options when a question ends in a choice, clear an answered question with `answer: null`, set checked_on when the signal is actually re-verified today. It also states when-not ('never set contact') and the prerequisite for `closed`.

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