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

The annotations flag destructiveHint=true and non-idempotent, which would otherwise be surprising for an onboarding call; the description earns credit for explaining why: 'Any call may also log usage, expire transient records and upload owed checkpoints.' It also discloses the untrusted-data security stance, which no structured field carries. It stops short of saying what 'expire transient records' destroys or whether checkpoints gate other calls.

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 core capability, then sibling differentiation, then side effects, then the security note. Dense telegraphic style but no wasted sentences. Slightly clipped in places ('agentFeedback files a feedback row'), yet every sentence carries 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?

No output schema exists, and the description compensates by enumerating the sections returned, so an agent knows what it gets. It covers side effects and prompt-injection safety. It does not state prerequisites such as auth or what happens when a project root cannot be inferred, which is the remaining 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 coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds only 'agentFeedback files a feedback row' and says nothing about projectRoot inference or feedback side effects. Minimal value 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 ('Cold-start onboarding in one call') and enumerates exactly what it returns: project identity, server health, session, work queue, recent decisions, next actions. It also explicitly distinguishes itself from sibling rbook_review ('the shorter everyday start'), so an agent can choose without opening either 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?

Names the alternative (rbook_review) and the condition that selects it: cold start versus everyday start. It also states that agentFeedback files a feedback row, implying when to pass it. Missing an explicit exclusion (e.g., 'do not use mid-session'), which keeps it 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.

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

Annotations declare destructiveHint=true and readOnlyHint=false tool-wide, but the description adds per-action granularity the annotations cannot: login, login_complete, rotate and reissue store credentials while logout and revoke remove them. That tells an agent which actions are irreversible without inspecting the schema. It does not mention permission requirements or where credentials are persisted, so not a 5.

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?

Dense and front-loaded: sign-in flow first, then sign-out, then project keys, then the persistence rule. The telegraphic style fits an 8-action tool, but "logout signs out" is near-tautological and the persistence sentence repeats the action names already listed, costing a small amount of space.

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 an 8-parameter, multi-action tool with no output schema, the description covers the action set, the login polling workflow, and which actions mutate credentials — enough to call it correctly. Return values are only partially covered (login_init's URL/code is stated, list's output is not), which keeps it short of 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?

Schema description coverage is 88%, and the per-parameter notes (graceSeconds "old key lives on", maxWaitSeconds "pending means retry same code", keyId defaults per action) already carry the semantics. The description adds no parameter-level detail beyond "poll login_complete", so the baseline 3 for high-coverage schemas 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 maps the tool's purpose (dashboard auth + project-key management) onto concrete action names: login_init/login_complete for sign-in, logout for sign-out, and rotate/revoke/list/reissue for project keys. It is clearly distinct from every sibling (rbook_project, rbook_session, etc.), which cover unrelated resources. It falls short of 5 because the key actions are listed without stating what rotate vs reissue actually do, leaving a little ambiguity inside the action set.

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?

"show login_init URL/code for browser approval; poll login_complete" conveys the required two-step sequencing, and "logout signs out" gives the context for the sign-out action. There is no explicit when-not or alternative-tool routing, but no sibling overlaps this domain, so the omission is minor.

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 flag destructiveHint=true, readOnlyHint=false and idempotentHint=false, yet the description never says which actions overwrite or destroy state, whether condense/snapshot/archive are reversible, or what permissions are needed. It adds only the dryRun default for condense, which the schema already documents. For a destructive multi-action tool this is a material disclosure gap, though nothing in the text contradicts the 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?

A single compact paragraph that front-loads the resource and then the action inventory, with conditional rules clustered at the end – appropriate density for a 33-parameter dispatcher. Minor waste in awkward phrasing such as 'history the context documents', which reads as a verb and costs a beat of comprehension, but overall every clause carries 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 8 actions, 33 parameters and no output schema, the description leaves the agent unable to predict what any action returns (view digest, history range, search hits, constraint review) or what side effects update/condense/archive produce. Only three of the eight actions get any behavioral constraint, and pagination/size semantics (page, pageSize, sizeOnly, compact) are untouched. The complexity demands substantially more than this.

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 88%, so per-parameter meaning is largely handled by the schema and the baseline would be 3. The description earns above baseline by stating cross-parameter coupling that no single field description captures: query is required specifically for search, source specifically for snapshot, and condense is dry-run unless dryRun=true. It does not, however, clarify the action-parameter interactions for update, history, or the nextStepAction/constraintAction sub-dispatchers.

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 the resource ('the record's documents and lists') and enumerates the eight action families (view, update, condense, snapshot, history, next_steps, constraints, search), which lets an agent recognize the tool's scope without opening the schema. It also draws a boundary against rbook_session ('New next steps and constraints come from rbook_session capture'). What keeps it from a 5 is that update/condense/snapshot/history are only restated as verbs, not explained, so the agent learns the names but not what each operation actually accomplishes.

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?

Useful gating rules are given for three actions ('search needs query; snapshot requires source; condense applies unless dryRun=true') and one negative routing hint sends creation of next steps/constraints to rbook_session. However, there is no guidance for the obvious sibling overlaps: why use search here versus rbook_decisions or rbook_learnings, or when to use this tool's next_steps/constraints lists versus the dedicated tools. Usage is implied by the action list rather than explained.

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?

With destructiveHint=true and readOnlyHint=false already declared, the description still adds substantial per-action risk context: 'retention deletes oldest files', 'restore backs up then replaces the local store; shared stores refuse', 'purge deletes only the dashboard mirror', 'prune_snapshots ... empties content, keeps rows'. It also distinguishes the safe operations ('health and conflicts only read') and the guard conditions (force ignored, dryRun refuses retired replay), which annotations cannot express at action granularity.

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?

Nearly every clause carries a distinct, load-bearing action rule, and the purpose is front-loaded ahead of the per-action list. It is aggressively compressed to the point of occasional ambiguity ('empties content, keeps rows, references and milestones' is hard to parse), and 'Database admin.' largely restates the title.

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 20-parameter, 12-action tool with no output schema, the description covers most mutating paths but omits 'reconcile' and 'identify_orphans' entirely, and says nothing about what 'health' or 'conflicts' return so the agent can act on results. Adequate to avoid obvious mistakes, but not complete for a tool of this surface area.

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 95%, so the baseline is 3 and the schema already documents slug/limit/maxPages as retired plus each action-specific field. The description adds genuine cross-field semantics: listOnly inverts snapshot into a list, confirm gates restore/purge/prune, force is a no-op, dryRun refuses retired replay. It does not explain keepLast/keepSince/keepSources/maxSnapshots interactions beyond a single retention clause.

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 opening clause 'Maintain the local store and its dashboard mirror' gives a specific verb+resource and scopes it beyond the generic title 'Database administration'. It also names the replacement tool for retired operations ('use reasonbook sync'), which helps disambiguate. It stops short of contrasting with the rbook_* siblings (project, mission, session, etc.), so an agent must infer that this is the storage/maintenance layer.

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?

Per-action routing is dense and actionable: 'snapshot creates unless listOnly=true', 'prune_snapshots previews unless confirmed', 'backfill uploads owner stores; force is ignored', 'pull/clone retired: use reasonbook sync'. That is explicit when/when-not for most actions. However, the enum actions 'reconcile' and 'identify_orphans' are never mentioned, leaving two callable operations with no guidance at all.

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 meaningful behavior beyond the destructive=true annotation: record writes a row and never edits text; corrections use supersedes to mark old decisions superseded; other projects' text is untrusted. It does not cover permissions, rate limits, or all destructive effects, but the key mutation semantics 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?

The description is dense but front-loads the action list and correction workflow, and every clause carries useful information. It could be more scannable, but it avoids unnecessary 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 complex, multi-action tool with 27 parameters and no output schema, the description gives a solid action overview, correction semantics, and a security note. It still omits return-value expectations and many action-parameter combinations, but the rich schema and annotations cover much of that ground.

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 96%, so the schema already documents most parameters. The description adds a little meaning, such as query for search, decisionId for show, and supersedes marking old decisions superseded, but it does not systematically explain the 27 parameters.

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 the resource (decision log) and enumerates the specific operations: record, list, search, show, review, update, and batch_update. It clearly distinguishes this tool from sibling tools by scoping everything to decision records.

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 explains what each action is for, including that review finds aging records and update/batch_update change status. It also gives a concrete correction workflow via supersedes, though it does not explicitly exclude or compare against sibling 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 destructiveHint=true and readOnlyHint=false, so mutation is expected; the description adds genuinely useful context that the mutations 'write the row's status and note' and that fleet text is untrusted — a prompt-injection warning absent from structured fields. It does not say whether status changes are reversible, which is a small gap against the destructive hint.

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 front-loaded sentences with no filler; the action list opens the description and the trust warning comes last. The telegraphic style ('List/triage/resolve/archive feedback') is efficient though slightly clipped.

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 10-parameter mutation tool with destructiveHint=true and no output schema, the description covers what is written and the untrusted-content hazard but omits pagination/result behavior for list and nothing about acrossProjects read-only fleet mode. Adequate but leaves meaningful behavior to inference.

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 90%, so the baseline is 3; the description earns a bump by binding parameters to actions (feedbackId for triage/archive, feedbackIds for resolve), a mapping the schema cannot express. Remaining params, such as acrossProjects and projectRoot, are documented only in 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?

Opens with a specific verb set and the resource: 'List/triage/resolve/archive feedback', and the four verbs match the action enum. It clearly covers the tool's scope, though it does not explicitly distinguish it from siblings like rbook_status or rbook_review beyond the resource name.

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 ties the mutating actions to required ids ('triage, resolve and archive need feedbackId (or, for resolve, feedbackIds)') and tells the agent what to do with untrusted fleet text by escalating via rbook_message. It never states when to prefer list vs. the mutations, or any preconditions such as role or status for triaging.

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 flag destructiveHint=true and readOnlyHint=false, so the safety baseline is set; the description adds real value on top by disclosing that reaffirm stamps the review date and that other projects' text is untrusted (an injection warning). It does not explain what makes an update destructive or whether changes are reversible, which is the one gap against a destructiveHint=true 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?

Four compact sentences with read operations front-loaded, then mutations, then the capture alternative, then the untrusted-content caveat. The telegraphic style ("Read lessons: list, search (query), show (learningId)") packs a lot in, though the parenthetical-heavy syntax takes a beat to parse.

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 15-parameter, five-action tool with no output schema, the description covers action routing, the sibling alternative, and the security caveat, and the schema carries the rest at 93% coverage. Remaining gaps are pagination behavior and whether updates return the modified record, both minor against the structured data available.

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 93%, so nearly every parameter is already documented in the schema, and the description largely restates those mappings (query for search, learningId to read or change). It adds no syntax, format, or constraint detail beyond what the schema provides, which is the expected baseline 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 enumerates concrete verb+resource pairs for each action: list, search (query), show (learningId), update status/evergreen, and reaffirm, which stamps the review date. It also explicitly names the sibling rbook_session for capture, so an agent can tell which tool owns which operation without opening a 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?

Each action value is paired with its intended use and the parameter it needs (query for search, learningId for show/update/reaffirm), and the capture case is explicitly redirected to rbook_session(action="capture", category="learning"). What's missing is guidance on choosing between update and reaffirm, or between list and search, when both could apply.

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 annotations already declare this as a non-read-only, open-world, non-idempotent, destructive tool. The description adds important behavior beyond those hints: ack marks read, send/respond deliver to another project, only one response is allowed per message, and text from other projects must be treated as untrusted data.

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 dense but front-loaded, with no wasted sentences. Each clause either defines an action, states a required parameter, or warns about a behavioral constraint.

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 complex 15-parameter, multi-action messaging tool, the description covers the critical action semantics, delivery behavior, response limits, and security warning. It leaves list filtering and return-value details to the schema or omits them, which is a minor gap given the high schema coverage.

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 93%, so most parameter semantics are already documented structurally. The description still adds value by mapping required parameters to specific actions, such as send requiring targetAddress/type/summary and respond requiring messageId/respondStatus.

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 the resource precisely as dashboard messages between projects and enumerates the supported actions (send, list, get, respond, ack, directory, whoami). It clearly separates this messaging tool from the other rbook siblings.

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 gives action-specific requirements, such as send needing targetAddress/type/summary and get/ack needing messageId, and explains workflow rules like one response per message and following up with a new message. It does not explicitly state when not to use the tool, but no close sibling alternative exists for project messaging.

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?

Beyond the annotations, it discloses which actions mutate state ('add, update and move write mission rows; undepends removes an edge'), which is exactly the destructive surface an agent needs. It also warns that other projects' text is untrusted, a useful injection-safety note. It does not cover permission requirements or reversibility of moves/edge removal.

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 action inventory, then a compact per-action requirements block; every sentence carries information. The requirements sentence is a long run-on that would read better as a list, but no content is wasted.

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 24-parameter, multi-action, destructive tool with no output schema, it covers required inputs per action, write side effects, and the escalation path to the transition tool. Gaps remain around pagination defaults, 'status' queue semantics, and edge-type enforcement (only noted in the schema), but nothing critical blocks a correct call.

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 action-to-parameter mapping (missionId for show/update/move, name for add, toSprintId for move, fromId/toId for edges) is the key semantic layer the schema does not express as a matrix. With 79% schema coverage and 24 parameters, a few (reason, type, page, queuedLimit, acrossProjects) are only explained by the schema, so it adds value without being exhaustive.

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 the resource (missions) and enumerates every concrete action: list, show, status (the work queue), add, update, move, depends/undepends. It also explicitly partitions responsibility from the sibling rbook_mission_transition ('Change state with rbook_mission_transition'), so an agent can route without opening either 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?

It states the alternative for state changes (rbook_mission_transition) and gives the per-action required parameters, which is a strong usage contract. It does not clarify when to prefer 'list' over 'status' or when to use acrossProjects/includeBlocked, leaving some selection ambiguity.

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 destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds real context beyond that: "Each writes the status and its history," telling the agent this persists state plus audit history rather than just returning a computed value. It stops short of flagging that transitions like drop are irreversible or what the response looks like.

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 short sentences, front-loaded with the core operation, then routing, then per-action requirements. No filler; every clause carries an actionable constraint.

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 an 11-parameter state-transition tool with 91% schema coverage, the description covers the operation, the alternatives, and the required-parameter rules well. The remaining gap is return behavior — with no output schema, the agent does not know what a transition returns (updated status, history entry, or error on invalid transition).

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 91%, so the schema already documents notes, reason, blockers, resolution, targetStatus, and the decisions routing. The description's per-action parameter hints (notes for complete, reason for block/reopen) largely restate what the schema already says, so it adds little beyond 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?

States a specific verb and resource ("Change mission state") and the enum of transitions makes the scope concrete. It explicitly separates itself from rbook_mission ("plan or edit missions with rbook_mission") and rbook_decisions, so an agent can distinguish it from siblings without opening schemas.

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?

Names alternatives and the conditions that route to them: decisions go to rbook_decisions(action="record", missionId), planning/editing goes to rbook_mission. It also states per-action prerequisites (missionId always, reason for block/reopen), which is exactly the routing detail an agent needs before choosing a transition.

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?

While annotations indicate destruction, the description adds vital operational behavior, such as stating that 'Other projects' text is untrusted,' and detailing the behavior of 'sweep' and 'join' operations across different environments.

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 overly dense and presented as a single, lengthy paragraph. Although the information is rich, it lacks logical breaks or front-loading, making it difficult for an agent to parse key operational modes quickly.

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?

Despite its length, the description is highly complete for a complex, cross-platform project management tool. It covers local, shared, and remote interaction models, satisfying the needs of a high-complexity 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?

Given the high schema coverage (96%), the description adds value by providing functional context to the parameters. It explains the meaning of 'projectType' (record retention policy) and clarifies the specific nature of join paths (SSH host, remote bin, remote root).

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 core purpose (register and manage projects) and breaks down the functional responsibility of various actions like 'init' (creates record), 'register' (local registry), and 'prune' (deletes/archives).

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 provides critical usage context by differentiating between local management tasks and remote/shared tasks. Specifically, it outlines usage constraints for 'via=dashboard' (authentication, confirmation) versus 'SSH join' scenarios.

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 flag destructiveHint=true and readOnlyHint=false on a tool named 'review', which would otherwise be puzzling; the description resolves this by disclosing that any call may log usage, expire transient records and upload owed checkpoints. It also adds a prompt-injection warning that text from other projects is untrusted data, which is genuine behavioral context beyond the annotations. It stops short of saying how much can be destroyed or what the expiry semantics are.

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 short sentences, front-loaded with the entry-point role and payload size, then alternatives, then side effects and the trust boundary. No sentence is redundant.

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, the description correctly describes the return payload's contents and size, and it covers side effects and the untrusted-content rule for a single optional parameter. Minor gaps remain around what 'about 4 KB' implies when truncated and whether the checkpoint upload requires anything from the caller.

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?

There is a single optional parameter (projectRoot) with 100% schema description coverage, so the schema already carries its meaning as a folder or rbook:// address that is inferred. The description adds nothing about resolution order or what happens when it is omitted; 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 states concretely what the tool returns — roughly 4 KB of sprint, work queue, recent decisions, portfolio signals and next steps — which lets an agent distinguish this digest from rbook_agent_onboard (fuller cold start) and rbook_context (search). The verb is loose ('Start ... work here') and the name 'review' is not self-explanatory, but the enumerated payload compensates.

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 positions the tool as the entry point for project work and names two alternatives with their roles: rbook_agent_onboard for the fuller cold start and rbook_context for searching the record. The selection conditions are clear, though it does not state when NOT to use it or when the fuller onboard is required over this lighter digest.

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 discloses that capture and complete write rows, which is consistent with destructiveHint=true and readOnlyHint=false. It does not elaborate on what complete does to existing rows, whether writes are reversible, or any permission/auth requirements, so it adds only modest context beyond the 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?

Three sentences, front-loaded with the main capture path, and every clause carries information. The middle sentence packs list and search together and the final sentence is dense, but 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 27-parameter multi-action tool with no output schema, the description covers the core write/read actions but omits list filtering, pagination, and many supporting parameters that appear only in the schema. It is minimally complete, but not rich enough to explain the full action surface or the destructive edge of 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?

Schema coverage is 93%, so the baseline is 3, but the description adds a meaningful default not stated in the schema: category defaults to context. It also maps action to required parameters (content for capture, title for start, summary for complete), though those required markers largely repeat 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 names the specific actions (capture, list, search, start, complete) and what each does, including the key distinction between an implicit session and an explicit one. It is clear what the tool does, but it does not distinguish capture from sibling tools like rbook_learnings or rbook_decisions even though it writes the same row types.

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 gives some useful guidance: capture works without starting a session, and explicit sessions are optional. But it never says when to prefer list versus search, when to use rbook_learnings instead, or when explicit sessions are actually warranted, so usage is only implied for most actions.

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 destructiveHint=true and readOnlyHint=false, yet the description adds real value beyond them: archiving of decisions/learnings only with archive=true, and the non-obvious side effect that add demotes other open sprints. It stops short of saying what happens to decisions/learnings when complete runs with archive=false, which is the key destructive ambiguity.

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?

Four tight sentences with the routing precondition front-loaded and zero filler; every clause carries action-specific information. The telegraphic style ("add needs title") is efficient but occasionally reads as cryptic shorthand rather than clear prose.

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 an 18-parameter, 8-action multiplexed tool with no output schema, the description covers the required-parameter rules per action and the main side effects, which is the bulk of what an agent needs. Gaps remain around pagination, the condensation/targetSizePercent controls, and what each action returns, but the essentials are present.

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 94%, so the baseline is 3; the description earns above that by mapping parameters to actions ("add needs title", "update needs fields", "complete needs summary", "carry_forward sends to targetAddress"). It does not clarify the overloaded semantics of limit (per-page vs comparison window) or status (filter vs value) beyond what the schema already hints.

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?

"Manage sprints" names a specific resource and the description disambiguates the eight action verbs by function (retro reports outcomes, analytics compares sprints, carry_forward sends to targetAddress). It is clearly distinguishable from siblings like rbook_mission or rbook_decisions, though the umbrella verb "manage" is less precise than naming sprint lifecycle operations.

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?

Gives an explicit precondition rule ("Except list/analytics, supply sprintId") and per-action requirements (add needs title, update needs fields, complete needs summary). It also flags which actions are read-only ("list and show only read"), but never states when to choose sprint analytics over retro, or any when-not 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 only flag destructiveHint=true, idempotentHint=false and readOnlyHint=false as bare booleans; the description earns its keep by explaining why — every call may log usage, expire transient records and upload owed checkpoints. That resolves what would otherwise look like a mismatch between 'status/health' framing and a destructive annotation, and it warns the agent that a read-looking call has persistent side effects.

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, no waste: the first sells the payload, the second routes usage and discloses side effects. Front-loaded with the value proposition rather than preamble.

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, the description does the work of telling the agent what comes back by enumerating the state dimensions, and it discloses mutation side effects that the annotations only hint at. The remaining gap is behavioral detail around the inferred projectRoot default, which would matter for a tool that acts on a project.

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 single parameter has 100% schema description coverage, so the schema already carries its meaning and the baseline is 3. The description adds no clarification of the "inferred" default value in projectRoot — e.g. inferred from what context — which is the one parameter question an agent would actually have.

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 resource and enumerates exactly what the answer contains (rbook:// address, dashboard, auth tier, sync, delivery, upload state), so the agent knows the shape of the output. It also explicitly distinguishes itself from rbook_review, which is a plausible source of overlap given the sibling list.

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?

"Use it to diagnose setup, sign-in or sync" gives a concrete trigger, and "rbook_review covers the work itself" names the boundary against one sibling. It stops short of the full sibling set — rbook_auth and rbook_project plausibly overlap with the 'auth tier' and project-level angles, and no exclusion is given for those.

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