rms_overview

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

With no annotations, the description carries the full burden and does well: it discloses the fail-closed precondition, the single-project scope, and an explicit data boundary (changed file names, never diff contents). It does not state whether the call is purely read-only or whether index lag reporting can trigger any work, which is the main residual gap for an unannotated tool.

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 usage trigger, then the hard constraint. Information density is high with no filler, though the first sentence is a long run-on list that could be segmented for faster scanning.

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 compensates by enumerating the returned sections precisely. Combined with the precondition, scope limit, and data-boundary caveat, an agent has everything needed to decide to call it and to interpret the result shape at a high level.

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. The description reinforces when an explicit `project` key is required, but that fact is already in the schema, and `recent_limit` (default 10, max 50) is not mentioned at all in the description — no added 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 specific verb and resource ("structured orientation summary") and then enumerates the exact payload: document counts by folder and status, recent notes, active checkpoints, index lag, and git state. The enumeration (plus "never diff contents") makes it distinguishable from siblings like rms_search, rms_doctor, or rms_code_search 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?

"Call this at session start" gives an explicit trigger, and the fail-closed clause states the precondition (bound workspace or explicit `project` key) and the scope limit (never aggregates across projects). It never names an alternative tool (e.g. rms_projects for multi-project views), so the routing guidance is clear but not exhaustive.

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