Skip to main content
Glama

review_brief

Assemble a pull request's full review context — PR state, ticket, builder checks, Codex findings, prior rounds, and repo patterns — so you can review to your own bar.

Instructions

Start every review here: the pull request as GitHub has it (it says STOP when the PR is merged or its head moved past head), the ticket and its working doc, the builder's checks compared with its recorded session (unmatched first: check those yourself), Codex's findings and the waivers to judge, earlier rounds and their open findings, assumptions and decisions, and what keeps coming back in this repo. Then review to your own bar.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ticket": "<ticket>"
    },
    "name": "review_brief"
  }
}

Input Schema

NameRequiredDescriptionDefault
headNo
ticketYes
projectNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.57.0

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description must carry the behavioral load, and it does disclose a concrete guard: it says STOP when the PR is merged or its head moved past `head`, which is essential context for interpreting results. It also flags that unmatched checks require independent verification. It omits whether the call is purely read-only, any auth or rate-limit behavior, and how much data the aggregation may return.

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

Conciseness3/5

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

The 'Start every review here' opening is correctly front-loaded, and each comma-separated item names real content, but the single ~80-word sentence is a dense wall of list items that is hard to scan. 'Then review to your own bar' adds tone more than actionable information.

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

Completeness4/5

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

An output schema exists, so the enumeration of included artifacts is partly redundant, yet it usefully signals breadth and the staleness short-circuit for a high-complexity aggregator. The main gap is the undocumented `project` parameter, which leaves the calling contract incomplete despite otherwise strong coverage.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must define all three parameters, and it does not. `head` is referenced only obliquely as the staleness anchor ('its head moved past `head`') with no format (SHA, branch) given, `ticket` is implied by 'the ticket', and `project` is never mentioned at all.

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

Purpose4/5

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

The description names a specific composite resource: the PR as GitHub has it, the ticket and working doc, builder checks vs recorded session, Codex findings and waivers, earlier rounds, assumptions/decisions, and repo recurring issues. 'Start every review here' frames it as a review-entry aggregator, which separates it from get_ticket or record_review, though the verb is directive rather than descriptive of the fetch itself.

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

Usage Guidelines4/5

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

'Start every review here' is an explicit when-to-use directive, and 'then review to your own bar' clarifies that the tool supplies context rather than verdicts. It also gives handling guidance for unmatched checks ('check those yourself'). It does not state when NOT to use it or name a sibling alternative, 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.