GitHub inbox

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

With no annotations, the description carries the full behavioral burden, and it does disclose the notable side effect that results are pushed to the Bar display by default. However, it omits whether the call hits the GitHub API (latency, auth requirements, rate limits), whether the Bar display persists after the call, and what happens if no Bar is connected.

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

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

Two short sentences: the payload is front-loaded and the conditional display behavior follows immediately. Nothing is redundant and there is 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 single-boolean tool with no output schema, the description adequately characterizes the return value as three named counts and explains the only option. The remaining gap is operational context (data source, auth, failure modes), which matters somewhat less for a read-only summary 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 0%, so the description must explain the lone parameter, and it does: 'show' controls whether counts are rendered on the Bar, with the default treated as display-on. It stops short of saying what is returned when show=false, but the muting behavior is otherwise unambiguous.

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 concrete resource with three specific data categories (PRs awaiting your review, your open PRs, assigned issues), which is far more specific than the title 'GitHub inbox'. It distinguishes itself implicitly from the only other GitHub sibling (github_ci), though it never names that sibling to make the boundary explicit.

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

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

Usage is only implied: an agent can infer you call this to get a personal GitHub work summary, but there is no explicit when-to-use statement, no mention of when to prefer github_ci, and no prerequisite or exclusion guidance. The single hint offered ('Shows them on the Bar unless show=false') governs a parameter, not tool selection.

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