Koalr

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds 'Read-only' (redundant) and lists the metrics returned, but it does not disclose additional behavioral aspects such as pagination or rate limits. Given the strong annotations, a 3 is appropriate.

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

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

The description is concise and front-loaded with the primary action. It includes a useful use-case sentence. The only minor issue is the redundant 'Read-only' at the end, which is already covered by annotations, so it is not entirely earning its place.

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

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

For a simple tool with one optional parameter, the description is adequately complete. It lists the specific metrics returned, which compensates for the lack of an output schema. The schema and annotations cover the remaining details such as team filtering and safety.

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

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

The schema description covers 100% of parameters (teamId), and the description does not add any parameter detail beyond what the schema already explains. Per the baseline rule for high schema coverage, a score of 3 is warranted.

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

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

The description clearly states that the tool retrieves AI coding tool adoption metrics and lists specific examples (GitHub Copilot acceptance rate, Cursor active users, etc.). It is specific about the resource and the verb, but it does not explicitly distinguish itself from sibling tools like get_ai_adoption_trend, though the name suggests summary vs. trend.

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 a clear use case: 'Use this to understand how the team is using AI coding assistants and measure their impact on productivity.' It does not explicitly mention alternatives or when not to use it, but the context is sufficient for a focused tool.

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 description adds context beyond the annotations by specifying the metrics returned and the time-series nature of the data. It explicitly states 'Read-only,' which aligns with the readOnlyHint and destructiveHint annotations. No contradictions, and the additional detail about weekly active users and acceptance rates is valuable.

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

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

The description is concise and front-loaded, with two sentences that each serve a purpose: stating what the tool does and why to use it. No unnecessary wording or filler.

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

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

For a simple tool with one optional parameter, no output schema, and clear annotations, the description is sufficiently complete. It explains the return metrics and usage intent. It could mention the default time period, but that's already in the schema, so it's not a 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?

The schema already provides 100% coverage for the single parameter 'days' with a clear description and default. The tool description does not add any additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('trend of AI tool adoption'), and lists the specific metrics returned (weekly active users, acceptance rates, code attribution percentages). It distinguishes itself from the sibling tool 'get_ai_adoption_summary' by focusing on trends over time.

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 usage context: 'Use this to track whether AI tool adoption is growing or declining across the team.' This tells the agent when to use the tool, though it doesn't explicitly mention alternatives or exclusions. Given the nature of the tool, this is adequate.

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 destructiveHint=false, and the description's 'Read-only' reiterates this. Beyond annotations, it adds the specific risk thresholds (3 days, no reviews, 500 lines), giving useful behavioral context for what qualifies as 'at-risk'. This adds meaningful value beyond the structured metadata.

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 two sentences, front-loaded with the action and resource, then provides criteria and usage intent. It is concise with no extraneous explanation; the final 'Read-only' is slightly redundant but does not undermine clarity.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description sufficiently explains what the tool returns, why it exists, and how it should be used. The criteria and use case make selection and invocation straightforward even without an output schema.

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

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

Schema description coverage is 100% for the single repositoryId parameter, which already explains filtering and omission behavior. The tool description adds no additional parameter detail, so it does not exceed the baseline provided by the schema.

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

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

The description clearly states the tool retrieves pull requests at risk of becoming long-running or blocked, with specific criteria (open >3 days, no reviews, >500 lines). This verb+resource+scope structure distinguishes it from sibling tools like get_open_prs, which lists open PRs generally.

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 a clear use case: 'Use this to prompt engineering leads to take action on blocked work before it impacts the team.' However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusion 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 the tool read-only, idempotent, and non-destructive; the description reinforces this with an explicit 'Read-only.' It adds useful behavioral context about the output (per-repository breakdown, trend) beyond what annotations provide, though it doesn't cover details like data freshness or default scope when no repositoryId is provided.

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 two sentences, front-loaded with the action and output, then followed by the use case. Every word adds value, with no redundancy except the 'Read-only' which is acceptable given its importance.

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

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

For a simple read-only summary tool with one optional parameter and no output schema, the description covers the essentials: what it returns, scope, and why you'd use it. It correctly identifies the integration goal (repositories needing review) without needing further detail.

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

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

The input schema has only one optional parameter with 100% description coverage ('Filter to a specific repository by ID. Omit to see all repositories.'). The description mentions 'per repository' but doesn't add meaning beyond the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Get test coverage summary per repository' and details the included metrics (coverage percentage, lines covered, coverage trend). This distinguishes it from sibling summary tools like get_dora_summary or get_ai_adoption_summary.

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 for when to use the tool: 'to understand testing health and identify repositories with low coverage that may warrant additional review attention.' While it doesn't explicitly name alternatives or exclusion criteria, the use case is specific enough for an agent to choose this tool appropriately among similar read-only summaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'Read-only' (redundant with annotations) and lists the metrics returned, but does not disclose additional behavioral traits such as data sources, time ranges, or rate limits. It provides some context beyond annotations but not substantial.

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 two sentences, directly front-loaded with the action and resource, and every clause contributes value. No filler or redundant explanation.

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

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

Given the simple one-parameter schema, strong annotations, and the description's enumeration of output metrics, the description is sufficient for the agent to select and invoke the tool. It does not document return format or time frame, but those are not critical given no output schema requirement.

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

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

The schema has 100% description coverage for the single parameter 'login', including an example. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') with a clear resource ('metrics for an individual developer') and enumerates specific metric types (PR throughput, review activity, cycle time, code contributions). This clearly distinguishes it from sibling tools like get_team or get_repository.

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 explicitly states when to use the tool: 'when asked about a specific engineer's activity or productivity.' It does not explicitly list when not to use it or name alternatives, but the 'specific engineer' qualifier provides clear guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description's 'Read-only' is redundant, but it adds context that the return is 'aggregated metrics for the selected time window,' which informs the agent about result shape. It does not disclose additional behavioral details like pagination or default handling, so a 3 is appropriate given the annotation coverage.

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

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

The description is two sentences, front-loaded with the action and metrics, then a purpose statement and read-only note. Every sentence adds value and there is no fluff.

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

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

With no output schema and only 3 optional parameters, the description adequately covers the essential information: what metrics, scope, read-only nature, and time window. It could be more complete by referencing sibling tools like get_dora_trend for trend analysis, but the current level is sufficient for a summary tool with strong annotations.

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

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

The input schema has 100% coverage for all three parameters (to, from, teamId), so the baseline is 3. The description mentions 'selected time window' and 'organization or a specific team,' which loosely map to the parameters but do not add new meaning beyond the schema.

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

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

The description clearly states the tool retrieves DORA metrics, enumerates the specific metrics (deploy frequency, lead time for changes, change failure rate, MTTR), and specifies scope (organization or team). It does not explicitly contrast with siblings like get_dora_trend, so it misses the full 5.

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

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

The description provides a clear use case: 'Use this to understand overall engineering delivery performance and reliability.' This gives context for when to select the tool, but it does not mention alternatives or exclusions (e.g., get_dora_trend for trends), so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is well covered. The description adds the 'week over week' granularity, which is a useful behavioral detail beyond the annotations, and no contradiction exists.

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 two sentences, front-loaded with the main action ('Get DORA metric trend over time'), and every sentence adds value. No wasted words.

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

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

For a simple read-only trend tool with fully documented schema and strong annotations, the description adequately covers purpose and use case. It lacks an explicit output format description, but given the straightforward nature and the lack of an output schema, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (metric, days, teamId). The description mentions the metric options but adds no new syntax or formatting details beyond what the schema provides, hence the baseline of 3.

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

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

The description clearly states the tool gets a DORA metric trend over time, enumerating the exact metrics (deployment frequency, lead time, change failure rate, MTTR). This distinguishes it from sibling tools like get_dora_summary, which likely provides a snapshot rather than a trend.

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 it is 'useful for spotting regressions or improvements across releases', providing a clear use case. It does not explicitly name alternatives or exclusions, but the 'over time' language implicitly differentiates it from summary tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat that the operation is safe. It adds some context about the output fields but does not disclose potential quirks like pagination or rate limits. This is adequate but not exceptional.

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 three sentences, front-loaded with the core purpose, then a use case, then the optional filter and a safety note. Every sentence earns its place with no redundant fluff (the 'Read-only' is a single word and harmless).

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

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

For a simple read-only list tool with only two optional parameters and no output schema, the description adequately explains what is returned (age, size, reviewers) and how to use it. The use case and filter behavior cover the essential context, making the tool self-contained.

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

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

Schema description coverage is 100%, with detailed descriptions for both parameters (e.g., highRiskOnly specifies >500 lines, >72h, no reviewers). The tool description only summarizes this as 'large, old, or no reviewers' and adds no new semantic information beyond the schema.

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

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

The description clearly states the tool 'List currently open pull requests' and specifies the returned fields (age in hours, size, reviewer assignments). It distinguishes from siblings like get_pr_summary by focusing on a list with detailed metrics.

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 an explicit use case: 'Use this to identify stale or large PRs that may be blocking the team.' It also mentions optional filtering for high-risk PRs, giving clear context. However, it does not explicitly name alternative sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by listing exactly what data is returned (DORA tier, cycle time percentile, test coverage, active teams, incident rate) and framing it as a high-level snapshot. It does not contradict annotations, and the 'Read-only' statement reinforces the safety profile. Minor gap: no mention of rate limits or authoritative source, but annotations cover the main safety traits.

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 two sentences, front-loaded with the action and the full list of metrics, then a concise usage note. Every sentence is purposeful with no redundancy or filler, achieving high efficiency.

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

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

Given the tool has only one optional parameter, rich annotations, and no output schema, the description does a good job enumerating the returned metrics (DORA tier, cycle time percentile, test coverage, active teams, incident rate). It provides a clear high-level usage context. It doesn't specify time frames or exact response formatting, but for a high-level snapshot, this is sufficient. The sibling tools exist for deeper drilling, so completeness is adequate.

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

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

The only parameter teamId is fully described in the schema ('Team ID to scope health metrics to a specific team. Omit for org-wide snapshot.'). The tool description does not add additional param-level detail, but per the calibration rule, high schema coverage (100%) yields a baseline score of 3. The description's mention of 'org-wide snapshot' aligns with the schema, but adds no new semantic information.

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

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

The description uses the specific verb 'Get' with the resource 'comprehensive organization health snapshot' and lists exact metrics (DORA tier, cycle time percentile, test coverage, active teams, incident rate). This clearly distinguishes it from sibling tools like get_dora_summary or get_coverage_summary, which focus on individual metrics.

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 to 'Use this as the first tool to get a high-level picture of engineering health before drilling into specific metrics.' This gives clear when-to-use guidance and implies exclusion of this tool for detailed drills. However, it doesn't name specific alternative sibling tools or state explicit when-not-to-use conditions, thus not a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'Read-only' (redundant with annotations) and clarifies the metric definitions (e.g., cycle time as 'time from first commit to merge'), but no additional behavioral traits such as data freshness, aggregation details, or limitations are disclosed.

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

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

Two sentences, front-loaded with the primary action, and every sentence serves a purpose: the first defines the tool's output, the second gives the intended use case. No unnecessary detail or repetition.

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

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

For a metrics-summary tool with two optional parameters and no output schema, the description is fairly complete: it lists the metric categories and gives a use case. However, it does not explicitly clarify whether the data applies only to merged PRs or includes open ones, nor does it mention that results are time-aggregated, which would be useful context.

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

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

Schema description coverage is 100%, with both 'days' and 'teamId' having meaningful descriptions. The tool description adds no parameter-specific information beyond what the schema provides, so it neither enhances nor detracts from 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 uses a specific verb ('Get') with a clear resource ('pull request metrics') and enumerates concrete metric categories: cycle time, throughput, review health, and PR size trends. This differentiates it from sibling tools like get_dora_summary or get_open_prs, which target different analytics areas.

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 explicitly states a use case: 'assess code review efficiency and identify bottlenecks in your delivery pipeline.' This gives clear context for when to use the tool, but it does not name alternative tools or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by listing exactly what metrics the tool returns and emphasizes 'specific repository', which helps set expectations. It does not describe rate limits or error handling, but given the annotation coverage, this is sufficient for a 4.

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 two sentences, front-loaded with the core purpose, and contains no wasted words. 'Read-only' is slightly redundant with annotations but does not detract from conciseness.

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

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

For a tool with one required parameter, a solid schema, and comprehensive annotations, the description adequately explains what the tool does and when to use it. It even lists return metrics, which partially compensates for the lack of an output schema. It does not mention error scenarios or edge cases, but these are not critical for such a simple read-only operation.

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

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

The input schema has 100% coverage for the single 'name' parameter, with a clear description (repository name optionally with owner). The tool description does not add any further parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Get detailed metrics for a specific repository', enumerates the metrics (deployment frequency, PR cycle time, contributor count, code health indicators), and explicitly says 'Use this when asked about a specific codebase'. This clearly distinguishes it from siblings like list_repositories (which lists all repositories) and get_org_health (which is org-level).

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

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

The description gives explicit context: 'Use this when asked about a specific codebase.' This is clear and differentiates from broader tools, but it does not explicitly name alternatives or provide 'when not to use' guidance. Still, the contextual cue is strong enough to guide an 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context by noting it 'Combines DORA and flow metrics in a single response' and enumerating the included metrics, which informs the agent about the response structure. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the main purpose, followed by usage context and a note about read-only behavior. Every sentence earns its place with no redundancy or fluff.

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

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

For a tool with one simple parameter, strong annotations, and no output schema, the description is sufficiently complete. It explains what the tool does, what metrics it returns, and when to use it. The absence of an output schema is mitigated by the explicit list of metrics included in the response.

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

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

Schema description coverage is 100% for teamId, and the schema already includes a helpful description ('The team ID (use list_teams to find team IDs)'). The tool description does not add additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Get details and metrics for a specific team' and enumerates specific metrics (DORA performance, cycle time, member count). It distinguishes from siblings by emphasizing it targets a specific team's engineering health and combines DORA and flow metrics, unlike list_teams or get_dora_summary.

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?

Provides explicit guidance: 'Use this when asked about a specific team's engineering health.' This clearly indicates the appropriate context. However, it does not explicitly mention alternatives or exclusions (e.g., 'for trends, use get_dora_trend'), though the contrast with list tools is implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description reinforces this with 'Read-only' and adds meaningful context about the nature of the data (the four pillars). It goes beyond the annotations by explaining what the metrics represent, which is valuable for agents.

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 two sentences, front-loads the primary action, and packs the essential details (pillars and usage context) without any superfluous content. Every clause contributes 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?

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It explains what it does, which metrics are involved, and why it should be used. The schema handles the parameter semantics, and the annotations cover safety, so nothing critical is missing.

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

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

Schema coverage is 100% with the property teamId described as 'Team ID to filter well-being data. Omit for org-wide summary.' The tool description does not add new parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves team well-being scores and specifies the exact pillars: focus time, meeting load, context switching, and burnout risk. This concrete detail distinguishes it from sibling tools like get_dora_summary or get_org_health, which cover different metrics.

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 a clear use case: 'Use this to understand developer experience and identify teams under stress before it affects delivery.' It does not explicitly mention when not to use it or name alternative tools, but the context is strong enough to guide appropriate selection.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that data comes from PagerDuty or OpsGenie and specifies the returned fields (severity, MTTR, affected services), which helps set expectations beyond the safety profile.

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

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

Two sentences, front-loaded with the core action and followed by purpose. No filler; the redundant 'Read-only' phrase is minimal and does not detract.

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

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

The tool has no output schema, but the description lists the key output fields and purpose. Parameters are fully documented in the schema, and annotations cover safety. It might benefit from mentioning pagination or default time window, but for a simple read-only list tool, it's sufficiently 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?

Input schema provides full descriptions for both days and limit with default values, so the description doesn't need to add parameter semantics. Baseline of 3 applies because schema coverage is 100%.

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

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

The description uses a specific verb ('List') and resource ('recent production incidents'), names the integrated sources (PagerDuty/OpsGenie), and lists output fields (severity, MTTR, affected services). This clearly differentiates it from sibling tools focused on other metrics.

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 explicitly states when to use the tool: to understand reliability posture or investigate outages in deployment context. It doesn't mention alternatives, but none are closely related among siblings, so the guidance suffices.

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 destructiveHint=false, so the safety profile is covered. The description adds context about the output content (health scores, activity levels) but does not disclose behavior beyond the annotations, such as pagination or ordering. It repeats the read-only nature without adding new behavioral details.

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 two sentences, front-loaded with the core action and details, followed by practical use cases. 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?

For a simple read-only list tool with one parameter and good annotations, the description is sufficient. It mentions the type of data returned and the primary use cases. It does not explain output schema (absent) but that is not required. It could mention ordering or response limits, but the overall context is complete for the tool's complexity.

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

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

The schema provides 100% coverage for the single parameter (limit) with default and max values. The description adds no additional parameter semantics. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool lists all repositories connected to Koalr with specific attributes (health scores, activity levels, basic stats). It uses a specific verb ('list') and resource ('repositories'), and the scope ('all connected') differentiates it from sibling tools like get_repository.

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 explicit use cases: getting an overview of the codebase landscape and finding repository IDs for filtering other tools. It does not explicitly mention alternatives or when not to use, but the stated use cases are clear and actionable.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description repeats 'Read-only' (redundant) and adds return content (GitHub logins and roles), but does not disclose pagination, ordering, or other behavioral details. It adds modest value beyond annotations.

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

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

Two concise sentences, front-loaded with the primary action. Every clause earns its place—the first sentence states what it does and returns, the second gives usage context. No waste.

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

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

For a simple 1-parameter, read-only tool, the description covers the purpose, usage, and return fields (logins and roles) adequately. There is no output schema, but the description fills that gap by naming the return content. It lacks an explicit output shape but is sufficiently complete for its complexity.

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

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

Schema coverage is 100% with a clear description for teamId ('use list_teams to find team IDs'). The tool description adds no additional parameter-level detail beyond the schema. At baseline = 3 because schema does the heavy lifting.

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

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

The description uses a specific verb ('List') and resource ('team members') and clarifies it returns GitHub logins and roles. It clearly distinguishes from sibling tools like list_teams (which lists teams) and get_developer (which gets a single developer).

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?

Provides explicit usage context: 'Use this to understand team composition or find developer logins for the get_developer tool.' It doesn't explicitly state when not to use it, but the context and the sibling list make the alternative clear. The schema also points to list_teams for finding team IDs, which adds to the guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the 'Read-only' mention is redundant. However, the description adds the return shape (array of objects with id, name, slug, memberCount), which is valuable without an output schema. It does not cover pagination or rate limits, but these are less critical for a simple list.

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 three sentences with no fluff, front-loaded with the primary action and outcome. Every sentence contributes either purpose, usage, or output details.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the action, the return value shape, and a practical use case. It is self-sufficient for the agent to understand what it does and why to invoke it.

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

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

Schema description coverage is 100% for the only optional parameter 'search', which is fully described in the schema. The tool description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists all engineering teams with member counts and slugs, using specific verbs and resource. It distinguishes from siblings like get_team (single team) and list_team_members (members of a team) by focusing on the team list itself.

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

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

The description explicitly says 'Use this to discover team IDs needed for filtering other metrics tools,' providing clear context for when to use it. It does not name alternative tools for exclusions, but the use case is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety profile is known. The description adds the ranking criteria and time window, but does not disclose behavior like pagination or return format. This is useful context but not extensive beyond annotations.

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

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

The description is concise, with the purpose and usage in the first two sentences. The trailing 'Read-only' is redundant with annotations but not verbose. Overall, it is front-loaded and efficient.

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

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

For a simple read-only list tool with good annotations and no output schema, the description adequately conveys what it returns (ranked contributors) and why to use it. It lacks explicit return format but the ordering by commits/PRs is stated. This is sufficient for the tool's simplicity.

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

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

Input schema covers 100% of parameters with descriptions for 'days' and 'limit'. The description only mentions 'time window' which maps to 'days', adding no extra meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool's function: 'List the most active contributors ranked by commits and PRs merged over a time window.' The verb 'List' plus the specific resource and ranking scope distinguish it from sibling tools, none of which focus on contributors.

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 use cases: 'Use this to identify key contributors, bus-factor risks, or to recognize top performers.' This provides clear context for when to invoke the tool, though it does not mention alternatives or when not to use 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=true and destructiveHint=false, and the description reinforces this with 'Read-only — scoring does not modify the PR.' It adds context about the 36-signal model and the factor breakdown. No contradiction with annotations, though it doesn't disclose potential external API calls or rate limits.

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

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

Three sentences with no fluff; the primary purpose is in the first sentence, return value in the second, and usage/read-only note in the third. Each sentence contributes meaning without wasting words.

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

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

Given the absence of an output schema, the description explains the return value (0–100 score with factor breakdown) and the analysis inputs. The tool is read-only with clear use cases, and the schema provides parameter details. It is complete for a single-PR scoring tool.

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

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

The input schema covers 100% of parameters with descriptions, so the description need not repeat them. The tool description mentions relevant signals (change entropy, DDL detection, etc.) that map to parameters, but adds no new parameter-specific format or syntax beyond the schema. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool scores a specific pull request for deployment risk, identifying the action ('score'), target ('pull request'), and outcome ('deployment risk'). It also explicitly names the 36-signal model and mentions the return format, distinguishing it from siblings like get_at_risk_prs that likely provide a list of at-risk PRs.

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

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

The description provides explicit use cases ('How risky is this PR?' or 'Should we merge this before the release?'), indicating when to use it. However, it does not explicitly contrast with alternatives like get_at_risk_prs for listing risky PRs, so it lacks exclusions but has clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds 'Read-only,' which is redundant with annotations, and doesn't disclose additional behavioral traits like pagination, result limits, or rate limits. It adds minimal value beyond the safety profile.

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 two sentences long, starts with the primary purpose, and packs in the searchable fields, usage guidance, and read-only note. 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?

Given the tool's simplicity (2 params, one optional enum), the description, combined with rich annotations, is largely complete. It covers what entities are searchable and when to use the tool. A slight gap is not explicitly stating what a result looks like, but this is inferable and the annotations cover the read-only nature.

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 description doesn't add meaning beyond the schema. The entity attributes listed in the description mirror the query examples in the schema. The optional 'type' enum is self-documenting. Description adds no new parameter semantics.

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

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

The description opens with a specific action ('Search across all Koalr entities') and enumerates exactly which entity types are covered and by which attributes. It clearly distinguishes from sibling getters by stating it finds an entity before using a more specific tool, making the purpose unmistakable.

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

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

It explicitly says 'Use this when you need to find an entity before using a more specific tool,' which gives clear usage context and implies an alternative (specific getters). It lacks an explicit when-not statement, but the guidance is strong enough for an agent to know when to invoke this tool first.

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