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 closing 'Read-only' merely echoes them. Beyond that, it discloses genuinely useful behavior: data comes from live git and CI rather than documentation, results are conditional (the capacity plan block only appears when docs/plans/capacity-plan.json exists), build drift is reported only when the repo is the one this Gluecron instance serves, and plans are capped at 10.

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 opening clause is well front-loaded, but the body is one sprawling sentence chained with semicolons and nested parentheses, which makes it hard to scan for a specific return field. The content is largely justified by the lack of an output schema, but the packaging could be restructured into a bulleted list of returned sections without losing 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?

With no output schema and a broad aggregate surface, the description correctly takes on the job of enumerating every returned section, including the conditional plan/plans blocks. It is nearly complete for an orientation tool; the only softness is that the plans/idPrefix behavior and the ordering semantics of blockers ('most urgent first') are stated so densely that an agent may need a second read.

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 owner, repo and merged_since_hours are already documented in the input schema. The description restates the 48-hour default for merged_since_hours and adds that plans are read with each ledger's declared idPrefix (default CAP, at most 10), which is contextual rather than parameter-level detail. Under the 100%-coverage baseline, 3 is the correct ceiling 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?

The description uses a clear framing: 'the live state of a repository, read from git and CI rather than from a handoff doc', which states the resource and its authoritative-source angle. It then enumerates the exact sections returned (summary, blockers, CI per workflow, build drift, open PRs, merged PRs, queue, plan/plans), so an agent knows precisely what it gets. It stops short of naming which specific sibling tools (e.g. merjax_ci_health, merjax_pr_status_summary) it supersedes when a narrower query is wanted.

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?

'Start here when picking up work' gives an explicit entry-point cue for the fresh-session/orientation case, which is the key when-to-use signal. What's missing is the inverse: no statement of when a narrower sibling (ci_health, pr_status_summary, list_prs) is the better call, so an agent must infer that this tool is the heavyweight aggregate option.

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