ZeroWidth Compass

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

Annotations already declare write, non-destructive, closed-world behavior, so the baseline is set. The description adds genuine behavioral context: the mention path 'rings their notification bell', which is a side effect an agent should know about, plus the thread-vs-reply branching. It stops short of noting auth requirements or idempotency.

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 core action and mode selection before the usage example. The closing etiquette line ('never mention someone who didn't ask') is editorializing but arguably still useful guardrail content.

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 write tool with no output schema and annotations covering safety, the description covers purpose, use case, thread/reply behavior, and mention side effects. Missing pieces are minor (approvalId meaning, mention limits, what a successful post returns).

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 only 43%, so the description is expected to compensate. It meaningfully explains mentionedUserIds (workspace member ids) and rootId (reply target), but leaves approvalId, workspace, entityKind semantics, and body constraints unexplained. Partial compensation warrants a baseline 3.

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+resource ('Posts a comment on a workspace entity') and clarifies the two modes — new thread vs reply when rootId is given. An agent can immediately tell what this does without opening the 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?

Gives concrete use cases ('leave findings where the discussion already lives', 'a summary on a long thread') that establish when to reach for it. It does not, however, distinguish this from siblings comments_list or comments_resolve, nor state any when-not conditions.

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 establish the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavioral content: result ordering (open first, then resolved) and the fact that authors and timestamps are included. It stops short of stating pagination, volume limits, or behavior for entities with no threads.

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, front-loaded with the operative fact (what is listed, in what order) before the advisory second sentence. The second sentence is slightly rhetorical ("where disagreement lives before it becomes a decision") but it does convey routing intent, so little 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?

With no output schema, the description compensates by naming the returned content (threads, authors, timestamps, ordering), which is the key information an agent needs. It remains silent on result size/pagination and on empty-result behavior, so it is strong but not fully 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 67%: workspace is well documented in the schema, entityKind has only a terse "What the thread hangs on" description, and entityId has none. The description says only "one workspace entity," adding no format, valid-value, or relationship detail beyond the schema enum, so a baseline 3 is appropriate.

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 concrete verb and resource ("Lists the comment threads on one workspace entity") and adds ordering detail (open first, then resolved). It implicitly separates itself from the write-side siblings comments_create and comments_resolve through the read verb, but never names or contrasts with them outright, so sibling differentiation is inferred rather than stated.

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?

"Read this before weighing in on contested work" gives a thematic when-to-use cue, which is more than nothing. However, no alternatives are named (notably comments_resolve or comments_create, the natural next/previous steps) and there is no when-not-to-use guidance or note on whether resolved threads can be filtered out.

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 this as a non-read-only, destructive mutation. The description adds meaningful policy context beyond that: the operation is a reversible toggle (resolve/reopen), and there is a sequencing constraint requiring justification before resolving. It does not state permission/auth requirements or what happens to existing replies, so it stops short of full disclosure.

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 dense sentences with the mechanical fact (what rootId is) front-loaded, followed by the policy. No filler, no restatement of 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 4-parameter mutation tool with no output schema, the description covers purpose, when-to-use, and the key parameter. The gaps are approvalId (never explained) and workspace/auth expectations, which matter for a destructive operation, but the core agent decision-making path is well served.

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 only 25%, so the description must carry more weight. It usefully defines rootId (the thread's root comment id) and implies resolved=true/false via 'resolve or reopen', but says nothing about workspace (which the schema does describe) or approvalId (undocumented in both places). Partial compensation for a low-coverage 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 states a specific verb (sets the resolved state) and resource (a comment thread), and clarifies the ambiguous rootId by equating it to the thread's root comment id. It clearly covers both directions of the operation (resolve and reopen). It does not explicitly distinguish itself from comments_create/comments_list, though the reply-first instruction implies a division of labor.

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?

Explicit when-to-use rules: resolve only when the human asked or the question is demonstrably settled, and reopen only for new evidence. It also imposes a prerequisite workflow step ('say what settled it in a reply first'), which implicitly routes the agent to comments_create. This is about as prescriptive as usage guidance gets.

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 the description's 'Replace' wording is consistent with a full overwrite. Beyond annotations it adds genuinely useful behavior: the effects are holistic (a whole set is replaced), sub-workflow collapse semantics, and that the call 'May return `needs_confirmation`', which ties to the approvalId parameter. Auth/permission specifics are not stated.

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 front-loaded paragraph that opens with the core action and never repeats the structured fields. It is dense and requires careful parsing, but every clause (effect semantics, sub-workflow collapse, projection step, confirmation) earns its place.

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 destructive, nested-schema mutation tool with no output schema, the description covers input provenance, per-effect semantics, the follow-up projection step, and confirmation behavior. It stops short of auth/permission or reversibility detail, but nothing critical to correct invocation is missing.

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 75% and the description adds real meaning beyond it: it defines the semantic intent of each effect enum value and supplies undocumented defaults (keepShare 0.25 for relax_gate, 0.5 for assist) and what reviewMinutes measures. The remaining covered params (workspace, approvalId, opportunityId) already carry schema descriptions.

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+resource ('Replace a change's effects') and immediately distinguishes itself by naming the sibling that supplies inputs (compass_workflow_steps) and the sibling that consumes the result (compass_workflow_rollup changeIds). An agent can tell this apart from compass_transformations_* and compass_changes_upsert 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?

It establishes the workflow context explicitly: steps come from compass_workflow_steps, effects are set here, then the result is projected with compass_workflow_rollup changeIds. There is no explicit when-not or exclusion, but the sequencing across siblings gives clear operational 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?

Goes well past the annotations: it discloses upsert field-merge semantics (omitted fields left alone), idempotency (nothing duplicates), per-item result shape (created/updated with key, or failed with why), failure isolation ('a failed item doesn't stop the rest'), and the needs_confirmation/approvalId batch-approval flow. This is exactly the behavioral context annotations cannot convey.

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 create-or-update rule and matching key, then layers merge semantics, idempotency, results, and confirmation. Dense but every sentence carries operational information; slightly long, though nothing is padding.

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 batched mutation with no output schema and three params, the description covers creation, update/merge, idempotency, partial-failure behavior, return shape, and the confirmation/approval round trip. An agent has everything needed to call and interpret it correctly.

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 67%, and the description compensates by explaining the `url` match semantics (creates vs updates), that `statusName` is by name with a pointer to compass_statuses_list, and that omitted fields are preserved. It does not clarify the remaining nested item fields (tags, experiment, workflowPageId) beyond schema, but adds real meaning over the raw 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 ('Create or update up to 100 changes in one call'), names the matching key (`url`), and defines the upsert rule against it. An agent can distinguish this batch upsert from siblings like compass_links_create or compass_pages_create 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?

Gives concrete usage context: rerun with identical urls to stay in sync, statuses come by name via compass_statuses_list, and 'Summarize what you're about to bring in before calling.' It does not explicitly name when to prefer this over other creation paths, so it stops short of full when/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 mark this as a non-destructive, non-readOnly, closed-world write. The description adds genuinely useful context beyond that: 'No approval needed — noting your own uncertainty isn't acting on the user's behalf', which explains why an agent may write freely, plus 'the gap registry is your working memory'. It doesn't cover rate limits or response shape, but the approval-free rationale is substantive added value.

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 purpose and the guidance to use it liberally, then moves to required content and the subject attachment. It's appropriately sized, though the question/rationale/resolution sentences partially restate the schema, adding mild redundancy.

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 6-param create tool with no output schema, the description covers purpose, when to use, required content, subject attachment, and the approval-free behavior. It doesn't say what the call returns (e.g., the created gap id) or whether a subject requires a matching subjectType, but nothing essential for correct invocation is missing.

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, but the description earns extra: it maps the required 'question' to a framing rule ('one clear question'), ties 'rationale' to 'what answering it unblocks', and — critically for the thin schema entries — explains subjectType/subjectId as the mechanism for tying a gap to a specific page or person. That last point adds meaning not present in the schema text.

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 — 'Records something you don't yet know' against the 'gap registry' — and reframes the resource as 'open question (gap)', so an agent knows this is the create side of the compass_gaps_* family. The framing is distinguishable from compass_gaps_list/resolve/update without opening the 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?

Gives concrete when-to-use context: 'use it liberally while mapping or interviewing', and conditions the subject attachment on whether the gap is ABOUT a specific page or person. It stops short of naming alternatives explicitly (e.g., compass_gaps_update to amend, compass_gaps_resolve to close), so it's clear context but not full routing 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 already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the default-to-OPEN filtering behavior and the registry framing, but says nothing about result size, pagination, or workspace/auth scoping beyond what the schema states. Adequate but not rich.

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, front-loaded with what the tool lists before moving to guidance. The colloquial aside ('This is where you keep your head') is colorful rather than wasteful, though it dilutes precision slightly.

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 four-optional-parameter read tool with no output schema and full schema coverage, the description covers what it returns (open questions/gaps), the default filter, and the workflow it supports. Nothing critical is missing, though return shape is left implicit.

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 100%, so all four parameters (status, subjectId, workspace, subjectType) are already documented, including the OPEN default and the workspace-token rules. The description only echoes the default status behavior, adding nothing new. Baseline 3 is correct.

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?

Specific verb+resource: 'Lists the workspace's open questions — the gap registry: what the map doesn't know yet.' The metaphor is anchored to a concrete concept (gaps), so an agent knows what it retrieves. It does not explicitly distinguish itself from siblings compass_gaps_create/resolve/update, so it stops short of a 5.

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 real usage context: 'check it before asking the user something you may already have flagged, and compose interview briefs from a subject's open questions.' That tells the agent when to reach for it. It does not name an alternative tool or state exclusions, so no 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 already declare a destructive, non-read-only mutation, and the description adds genuinely non-obvious behavior on top: gaps the agent raised close without a card, while a person-authored question requires their approval (matching the approvalId re-call flow). It stops short of saying whether a resolution can be undone or corrected later.

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 purpose and the two statuses are front-loaded in the first sentence. The middle sentence is a long run-on mixing invariant ('the resolution alone isn't the map') with follow-up page-writing instructions, slightly diluting focus, but overall it is tight and every clause is substantive.

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 five-parameter mutation with no output schema, the description covers the approval-gating behavior and the expectation that the answer be propagated to the relevant page. What is missing is the response shape (e.g. whether the call can return needs_confirmation) and whether DISMISSED requires a resolution.

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?

With 100% schema description coverage on all five parameters (including the status enum and the approvalId flow), the schema already carries parameter meaning. The description restates the ANSWERED/DISMISSED distinction and the 'resolution' pairing but adds no syntax, constraints, or guidance beyond what is documented.

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 specific verb and resource ('Closes a gap') and enumerates the two terminal states (ANSWERED with resolution, DISMISSED), which lets an agent distinguish it from compass_gaps_create and compass_gaps_list. It never states, however, how it differs from the sibling compass_gaps_update, which overlaps conceptually with 'resolve'.

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 a clear trigger ('once you've learned the answer ... or decided it doesn't matter') and even a cadence recommendation ('resolve gaps as their answers land'). It does not explicitly exclude the closely-related compass_gaps_update or explain which to prefer when a gap merely changes status.

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, so the mutation risk is covered. The description adds real behavioral context beyond that by flagging the two-phase confirmation flow ('May return `needs_confirmation`'), which changes how an agent must sequence calls. It stops short of saying whether prior wording is recoverable or what permissions are needed.

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, front-loaded with the action, then the alternative and prerequisite, then the return caveat. Every clause carries information 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 mutation tool with no output schema, it covers purpose, routing, id sourcing, and the needs_confirmation return path with annotations carrying the safety profile. Minor gaps remain around permission requirements and partial-update behavior, but nothing critical for correct invocation is missing.

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 100%, so the schema already documents all six parameters, including the workspace and approvalId mechanics. The description only restates which content fields are editable (wording/rationale/resolution) already implied by the schema, adding little new meaning. 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?

States a specific verb and resource ('Edits an open question's wording, rationale, or suggested resolution') and explicitly contrasts with the nearest sibling: 'Closing a gap is compass_gaps_resolve, not this.' An agent can distinguish this from compass_gaps_resolve and compass_gaps_create without opening their 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?

Gives the when ('sharpening a vague question or fixing one you phrased badly'), the when-not with a named alternative ('Closing a gap is compass_gaps_resolve'), and the prerequisite for the id ('Gap ids come from compass_gaps_list'). Nothing is left to inference.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable semantics the annotations cannot: the exact composition of the inbox, that fillIn is excluded from total, and that offsetting cards are pending approvals. It does not describe pagination or ordering, 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?

Front-loaded with the core purpose in the first clause, then sub-lists, then next moves. It is dense and long, but every section earns its place; the routing guidance and owner-lead instructions are not padding.

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?

There is no output schema, and the description compensates by naming the three inbox categories, the uncounted fillIn set, and the recommended follow-up tools for each category. Missing only explicit pagination/ordering and what a total counts, which is minor for a read-only overview 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 100% and the single workspace parameter is fully documented, so the baseline is high. The description adds no parameter detail but does not need to, and it clarifies the return shape and the fillIn/total relationship which supports interpretation of results.

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 exactly what is returned: finished interviews awaiting review, AI-proposed opportunities awaiting accept/dismiss, and pending approval cards, plus the fillIn sub-list. This is a specific verb+resource and distinguishes itself from siblings like compass_opportunities_list and compass_interviews_list by framing all of them as a decision queue.

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?

Explicitly says it is 'THE place to answer what needs me?' and names concrete follow-up alternatives (compass_interviews_get → compass_pages_create, compass_opportunities_accept/delete, compass_links_create with kind owns/part_of). It even states a when-not/guardrail: 'never guess an owner'.

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 annotations covering only read/destructive/openWorld, the description adds substantial behavior: the approval card shows the exact subject+message before send, there is a hard invite+one-reminder rate limit, and completion arrives asynchronously as a notification with draft-page counts (explicitly 'don't poll'). This is exactly the operational context annotations cannot express.

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-loads the core action and framing in the first clause, then layers operational constraints. It is a dense single paragraph and reads as slightly run-on, but nearly every clause carries distinct information, so almost nothing 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 tool that sends real outbound email through an approval flow with no output schema, the description covers the full lifecycle: message authoring, approval gating, rate limit, and async completion signal. Nothing an agent needs to invoke it correctly is missing.

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, but the description adds content guidance for `message` beyond the schema — short, human, explains why THEIR knowledge matters, ~15 minutes, no account needed — which tells the agent what to actually write, not just where it goes.

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 ('Emails the guest link for an existing interview') and pins the framing ('from the REQUESTING USER'). The word 'existing' cleanly separates it from compass_interviews_create, so an agent can distinguish it from siblings 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?

Gives clear context: use it while framing a message in the requesting user's voice, respect the invite-plus-one-reminder limit, and expect a notification rather than polling. It never names a sibling alternative or an explicit when-not condition, which is the only thing keeping it below 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?

Beyond the annotations it discloses real side effects: creates a guest-facing link, drafts pages flow back into Compass, and the call may return `needs_confirmation` requiring the agent to explain and wait. That two-phase approval loop is the kind of thing annotations cannot convey. It stops short of invite lifecycle behavior (expiry, whether repeated calls create multiple invites, revocability via compass_interviews_revoke).

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 definition in sentence one, then usage, then mechanics, then the approval caveat — a sensible descending-priority order. Dense rather than padded, though the all-caps 'THE KNOWLEDGE-GAP MOVE' framing and stacked parentheticals add a little rhetorical weight.

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 7-parameter creation tool with no output schema, the description covers purpose, creation conditions, sequencing to the invite sender, and the confirmation round-trip. The main gap is the success payload — it implies a link is returned ('hand the user the link') but never states what the response contains or what the agent should do with draft-page ids.

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 baseline is 3, but the description adds real selection guidance: focusPrompt should name the SPECIFIC gaps and cite the eval run id, and interviewee should be the owner of the relevant workflow when the map knows one. It doesn't add much for workspace or contextPageIds, which the schema already explains.

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?

Specific verb and resource — 'Mints a stakeholder-interview invite' — immediately qualified by what the artifact actually is: a no-account guest link to an interviewer agent briefed by focusPrompt, with the transcript returning as draft pages. That distinguishes it cleanly from the sibling compass_interview_invite (which sends the link) and from compass_interviews_list/get/revoke.

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?

Explicit when-to-use trigger wired to another tool: 'when caliper_flow_performance shows failures clustered on missing company facts … the fix is usually not a prompt edit.' It also tells the agent when NOT to stop here — if an email exists use compass_interview_invite next, otherwise hand the user the link — so the routing decision is fully resolved.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description is free to add payload-level context, which it does: it discloses that the response is metadata plus the guest's verbatim transcript and that the transcript is the downstream source of truth. It adds no auth, size, or error-handling context, but against read-only annotations this is solid added value.

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 payload, with no filler sentences. The middle sentence is clause-heavy ('the transcript is the source you work from, and your compass skill has the rules for typing and splitting what's in it') and the final clause is slightly indirect, but it still earns its place as workflow context.

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 carries the return-value burden and does so by naming the two payload components (metadata, transcript). Combined with the read-only annotations and a fully documented schema, an agent has what it needs to call this correctly; only permission/auth specifics are left implicit.

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 documented there and 3 is the baseline. The description adds one small piece the schema lacks — that ids may also come from compass_inbox_list, not only compass_interviews_list — but does not otherwise elaborate on parameter meaning.

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 gives a specific verb and resource ('One interview in full — metadata plus the transcript') and states the scope that distinguishes it from compass_interviews_list: this returns the full record including transcript, not a list. An agent can immediately tell what it fetches without opening the 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 a clear use condition ('Read this before summarizing an interview or drafting pages from it') and routes the agent to where ids come from (compass_interviews_list, compass_inbox_list). There is no explicit when-not or note about how this relates to bulk retrieval, so it stops short of full routing 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 cover the safety profile (readOnlyHint, openWorldHint=false, destructiveHint=false); the description adds substantive context beyond that: result ordering, the status lifecycle values, that transcript review is signalled by documentPageId being set, and that invite URLs are only present while the link is live. For a no-output-schema tool this is exactly the behavioral disclosure an agent needs.

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 scope and returned fields, then usage, then the sibling pointer — a logical order with no filler sentences. The field enumeration makes the middle sentence dense, but each clause carries information since no output schema exists.

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 carries the return-shape burden and does so thoroughly: fields, status values, ordering, and liveness caveat. Combined with annotations covering the safety profile and a fully documented single parameter, nothing an agent needs to call this correctly is missing.

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 'workspace' parameter with 100% schema description coverage, so the schema already explains slug/default/API-key semantics fully. The description only implies workspace scoping and adds no format or defaulting detail for the parameter, so the baseline 3 is appropriate.

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 (list stakeholder interviews) and immediately enumerates scope: workspace-wide, newest first, with the exact fields returned. It explicitly distinguishes itself from compass_interviews_get, so an agent can choose between them 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?

Gives concrete when-to-use conditions — 'Check this before inviting someone again' and answering 'who have we already asked?' — plus the reason (interview fatigue) and an explicit route to compass_interviews_get for full-detail reads. Nothing about selection is left to inference.

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 the description builds on that by disclosing idempotency, the exact user-visible consequence (link becomes inactive), and the two-step confirmation flow ('May return needs_confirmation'), which pairs with the approvalId parameter. This is behavior an agent cannot infer from annotations alone.

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 effect, then triggers, then operational notes (idempotency, id source, confirmation). Every sentence carries distinct information with 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 destructive revoke tool with no output schema, the description covers the effect, the trigger cases, idempotency, where ids come from, and the confirmation round-trip. Nothing an agent needs to call it correctly is missing.

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 schema already documents all three fields; the baseline would be 3. The description adds useful provenance for interviewId ('Ids come from compass_interviews_list') and ties the needs_confirmation return to the approvalId field, giving extra value over 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 ('Kills an interview's invite link') and even describes the observable effect ('the guest's next visit sees that the link is no longer active'). An agent can distinguish this from the invite-creating sibling 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?

Gives three concrete trigger scenarios — wrong recipient, changed mind, leaked link — which is strong positive guidance. It stops short of naming the explicit alternative (e.g. re-inviting via compass_interview_invite) or a when-not case, so it lands just below the top tier.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes well beyond that, disclosing the ranking precedence, the skip rule for recent interviewees (interview fatigue), and the empty-result recovery procedure — real behavioral context. Minor gaps only (no pagination/limit behavior), so not a full 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?

Front-loaded with the ranking purpose, then output contents, then the fallback, then the routing instruction — a logical order with little waste. The parentheticals are dense but each carries distinct information, so it is efficient without being terse.

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?

There is no output schema, so the description must describe returns — and it does: each target carries contact email, role, and latest interview. Combined with the ranking order and empty-result guidance, an agent has everything needed to call and interpret this tool correctly.

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 pageId and workspace are already documented in the schema. The description implies pageId means 'the page the knowledge gap is about' but adds no format or syntax detail beyond that. Baseline 3 is correct when the schema does the heavy lifting.

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 — ranks the PEOPLE the map says know about a page — and immediately narrows the domain (workflow, system, pain point). The ranking rule (owns first, then involved_in, then weaker edges) makes it unmistakable versus siblings like compass_interviews_create or compass_step_claims_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?

Explicitly routes the agent: 'Use before compass_interviews_create to pick the interviewee.' It also names the alternative action when the result is empty (ask the user, create PERSON page + owns link), so both the happy path and the fallback are covered.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing idempotency on an open (from, to, kind) edge and the needs_confirmation/approvalId round-trip that requires pausing for human approval. These are non-obvious behavioral traits that directly affect how the agent calls the 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?

Purpose is front-loaded and nearly every sentence carries domain knowledge that earns its place. However, it is a single dense paragraph mixing kind semantics, temporal guidance, provenance, and the confirmation flow, which makes it harder to scan than a structured layout would be.

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 mutation tool with no output schema, the description covers the domain rules (canonical directions, one-parent constraints on PRIORITY and UNIT, idempotency) and the return-side confirmation behavior, leaving no material gap an agent needs before calling it.

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, but the description adds real meaning the schema lacks: it explains the semantic direction of each `kind` enum value (e.g. PERSON owns WORKFLOW, PAIN_POINT affects WORKFLOW), the purpose of validFrom/validTo, and the sourceKind/sourceId pairing. This lifts it above 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?

The opening sentence gives a specific verb and resource — 'Creates a typed, directed edge between two pages' — and frames it as the graph's connective tissue. This is immediately distinguishable from the sibling mutation/read tools (compass_links_update, compass_links_delete, compass_page_links_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?

The description is unusually rich on when-to-use: it enumerates canonical directions per kind and gives a clear preference rule ('Prefer attaching responsibilities to the ROLE... the role outlasts whoever is in it'). It also tells the agent when to pass validFrom/validTo and sourceKind/sourceId. It does not explicitly name when to reach for compass_links_update instead, so it stops short of full alternatives coverage.

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, but the description adds materially important behavior beyond them: the delete is edge-only (pages survive), the edge can be revived by re-creating it, and the call may return `needs_confirmation` (matching the approvalId flow in the schema). Reversibility and the confirmation gate are exactly the traits an agent needs before invoking a destructive 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-loads the core action and scope, then the decision rule, then the id source and reversibility note. Every sentence carries distinct, actionable information with no padding.

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 destructive, 3-param tool with full schema coverage, destructive annotations, and no output schema, the description covers the decision criteria, the confirmation/approval path, and reversibility. Nothing an agent needs to call it safely is missing.

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 100%, so all three parameters (linkId, workspace, approvalId) are already fully documented in the schema. The description only restates that link ids come from compass_page_links_list, which the schema already says — 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?

States a precise verb and resource — 'Deletes one edge from the graph' — and immediately disambiguates scope with '(the pages stay)'. It is clearly distinguishable from its siblings compass_links_create, compass_links_update, and compass_page_links_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?

Gives an explicit when-to-use condition ('only when a connection was never true... recorded by mistake') and an explicit when-NOT-to-use case, naming the alternative tool and its parameter ('end it with compass_links_update validTo instead, so the history stays'). This is textbook routing 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?

Goes well beyond the annotations by disclosing that history is preserved (the old edge stays as history), that a conflict error is raised when the new reading already exists, and that the call may return needs_confirmation. This is meaningful mutation/error/approval context for a destructive write 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 core action and dense with useful detail; every clause is actionable. It is on the long side with two inline examples, but 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?

For a 7-parameter mutation tool with no output schema, the description supplies the missing return/error behavior (conflict, needs_confirmation) and the lifecycle semantics an agent needs to call it correctly. Nothing substantive is left unexplained.

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, but the description adds real semantic meaning: it frames kind as a correction mechanism and validTo as a relationship terminator with an example. It does not, however, clarify validFrom or the approvalId/workspace plumbing beyond what the schema already documents.

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 (Edits) and resource (an existing edge between two pages) and enumerates the mutable aspects (kind, note, validFrom/validTo). It is clearly distinguished from siblings compass_links_create and compass_links_delete, which handle the creation and removal ends of the lifecycle.

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?

Explicitly prescribes when to use each field: kind to CORRECT a mistyped connection, validTo to END a relationship that used to be true. It names the alternative behavior ('Don't delete a relationship that ended; end it' and 'delete this one instead' on conflict) and points to compass_page_links_list for link ids.

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 establish read-only and non-destructive behavior, but the description adds substantial context beyond them: it explains the rendered image contents, the text summary fields, how unconnected pages and drafts are drawn, and the critical presentation rule not to put the image in a markdown reply. This is unusually complete behavioral guidance.

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 long but front-loaded and mostly earns its length by explaining how to interpret the visual output and how to present mapUrl. The detailed legend is useful for this visual tool, though some phrasing could be tightened.

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 compensates by explaining both return components: the rendered image and the text summary with counts, links, unconnected pages, and mapUrl. It also tells the agent what to do with each, so nothing critical is missing.

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 only one parameter, workspace, and schema description coverage is 100%, so the schema already explains its default/override behavior and limitations. The description adds no workspace-specific semantics beyond what the schema provides, making the baseline 3 appropriate.

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 action (renders the workspace's visual map to an image) and precisely what the result represents: a transit-style map with named tiles, figures, squares, link styles, and regions. It clearly distinguishes this visual/spatial tool from page-listing or search 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?

Explicitly says when to use it: when the user asks about the shape of their map, where things cluster, what connects to what, or anything spatial. It also tells the agent how to present the result afterward, including linking mapUrl rather than embedding the image.

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 annotations, the description discloses important behavior: default lane when status is omitted, special lane semantics for BACKLOG and EXPERIMENTING, the not_proposed failure for non-AI proposals, and the needs_confirmation two-step flow. These are exactly the kind of operational details annotations do not cover.

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: purpose first, then sibling contrast, status semantics, failure mode, id source, and confirmation behavior. Every clause contributes useful information, though the single long paragraph is heavier than strictly necessary.

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 mutation tool with no output schema, the description covers the essential context an agent needs: the proposal-only constraint, the optional status lane, failure behavior, id sources, and the confirmation flow. Nothing critical appears missing.

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 baseline is 3; the description adds meaning by explaining what the status lanes do (BACKLOG parks, EXPERIMENTING starts, omitted lands in NEW) and by identifying where opportunityId values come from. It does not fully explain the workspace or approvalId parameters, but those are already documented 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?

The description states a specific verb and resource ('promotes an AI-PROPOSED opportunity ... into the workspace's own pipeline') and explicitly distinguishes it from the nearest sibling, compass_opportunities_set_status. An agent can identify what this tool uniquely does without opening the 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 explicitly says when to use this tool versus compass_opportunities_set_status ('set_status does NOT do this — a proposal stays in the Inbox until accepted'), names where ids come from, and states the failure condition (not_proposed) and confirmation flow. This is near-complete routing 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?

With annotations only declaring readOnly=false, openWorld=false, destructive=false, the description adds real behavioral context: the record lands in the board's first status by default, and the call may return `needs_confirmation` requiring the agent to summarize and wait for approval. That approval-loop disclosure is meaningful and not derivable from 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?

Four tight sentences, each carrying distinct information (what to record, anchoring rule, default status, experiment condition, approval flow), with the core action front-loaded. No filler or 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 9-param creation tool with no output schema, the description covers the essential behaviors: default status placement, anchoring, the experiment flag, and the needs_confirmation return path. It is largely complete, though it could say more about what an accepted opportunity returns or how it relates to compass_opportunities_propose.

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, but the description adds semantic nuance beyond the schema: the default status behavior for statusName, and the intent condition for `experiment` (only when measured against the Ledger). It does not add meaning for label, tags, links, or description, which rely entirely on 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+resource ("Record a change") and enumerates the kinds of changes (fix, chore, new step, experiment), which is more concrete than the title alone. It does not, however, clearly differentiate this create tool from close siblings like compass_opportunities_propose or compass_changes_upsert, leaving the agent to infer the boundary.

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 actionable conditions: anchor to a workflow page "when one fits," otherwise leave unanchored, and set `experiment` only when the user wants it measured against the Ledger. It routes to compass_pages_list and compass_statuses_list for lookups. It stops short of explaining when to prefer this over compass_opportunities_propose/accept, so no explicit alternative selection is stated.

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 the safety profile is covered. The description adds value beyond that by disclosing that the delete is a soft delete (record preservation) and that the call may return `needs_confirmation`, hinting at an approval flow that the annotations do not express.

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 core action and its soft-delete qualifier are front-loaded, followed by routing guidance and the id source. Sentences earn their place, though the 'dismiss verb / remove verb' metaphor phrasing is slightly more elaborate than a terse statement would require.

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?

There is no output schema, so the description correctly carries the behavioral burden: it explains the soft-delete semantics, the confirmation flow, and correct usage relative to siblings. It is nearly complete, only omitting any detail about downstream effects on linked records or workspace scoping.

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?

With 100% schema description coverage the baseline is 3, but the description adds provenance for opportunityId ("Ids come from compass_opportunities_list") and ties the needs_confirmation behavior to the approvalId parameter's purpose, adding meaning beyond the raw field docs.

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 (removes) and resource (opportunity) and immediately qualifies it as a soft delete, which materially changes what the agent expects. It also names the sibling it must not be confused with (compass_opportunities_set_status) and the verb-family nuance against other opportunity 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?

Provides explicit routing: use this as the dismiss verb for unwanted AI proposals, the remove verb for duplicate/mistaken captured experiments, and prefer set_status REJECTED when concluding a real experiment without evidence. This is exactly the when/when-not/alternative guidance the dimension rewards.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes well beyond that, disclosing the shape of returned items: statusName vs statusCategory semantics, the legacy `status` lane key, the `experiment`/`ledgerEntryId` null-means-no-expectation rule, and `ledger.verdict` values after settlement. This is meaningful behavioral context that an agent would otherwise have to discover empirically.

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 text is information-dense but not front-loaded: the opening sentence describes the resource rather than stating what the tool does, so an agent scanning the first clause does not immediately learn the operation. Most sentences carry real payload, but the heavy backtick-heavy prose and lack of a clear action-first structure hurt scanability.

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 carries the full burden of describing returns and does so well — item fields, status semantics, experiment/ledger linkage, optional scores and workflow anchor. It is nearly complete for a zero-required-param list tool, though it omits pagination, result limits/ordering, and default-scope behavior.

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 100%, so the baseline is 3. The description adds some value by explaining that `status` holds a 'lane key' and by mapping statusCategory stages (TRIAGE/BACKLOG/ACTIVE/DONE/CANCELED), but it does not clarify the relationship between the schema's lane enum values (NEW, QUALIFYING, EXPERIMENTING, SETTLED, REJECTED) and those categories, nor add format detail 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?

The description defines the returned resource ('the workspace's changes — fixes, chores, new steps, experiments') in rich detail, but never states the action itself — the fact that this enumerates opportunities is carried only by the name/title. It also does not differentiate this list operation from siblings such as compass_opportunities_propose or compass_opportunities_create. Purpose is inferable from the title but the description alone is vague about the verb.

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 concrete filtering guidance ('Filter by lane key in `status` or by workflowPageId') and points to a companion tool for status names ('compass_statuses_list has the status names'), which is genuinely useful routing. However there is no when-to-use versus when-not-to-use statement, no mention of what it excludes, and no indication of when a caller should prefer a different listing tool (e.g. compass_pages_list) instead.

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 it as a non-destructive mutation. The description adds crucial behavioral context beyond annotations: the record is irreversible ('cannot move afterward'), it attaches to the linked Ledger entry as evidence, and it may return `needs_confirmation`, implying an approval flow. These are important for correct use.

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 four sentences, each carrying useful information. It is mostly front-loaded, though the opening phrase 'The measurement window's boundary' is slightly abstract before the concrete action is stated. No wasteful content.

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?

Given this is a mutation with irreversible effects and an approval flow, the description covers the core action, trigger, irreversibility, side effect (attaching evidence), and potential return value (`needs_confirmation`). It is complete enough for an agent to call correctly, though it does not explain every parameter's effect.

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 100%, so the schema already fully documents all parameters. The description does not add parameter-specific meaning beyond the general concept of recording a date, so the baseline score of 3 is appropriate.

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 a specific action: recording the landing date of an experiment's change, framed as the measurement window boundary. It clearly distinguishes this from status changes or accept/propose siblings by focusing on the irreversible landing date and its baseline/effect implications. However, it does not explicitly name sibling tools.

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?

The trigger is clear: 'when the user says the experiment's change actually shipped / went live / rolled out.' It also advises confirming the date because it cannot move afterward. No alternatives or exclusions are mentioned, but the context is sufficiently defined for correct invocation.

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real post-write context beyond them: the record lands in the Compass Inbox and Needs-you for accept/dismiss, and approval is not required because the proposal itself is the gate. It stops short of auth/rate-limit detail but meaningfully explains consequences.

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, front-loaded with the core purpose and the sibling distinction before moving to prerequisites and parameter guidance. Dense but every sentence carries actionable information; em-dash clauses are slightly packed but not wasteful.

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-param mutation tool with no output schema, the description covers purpose, when-to-use, dedup precondition, anchoring, and scoring semantics. The main residual gap is that it never states what the call returns (e.g., an ID), which an agent would need despite the inbox description.

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 only 63%, and the description compensates for the gap: valueScore/feasibilityScore/riskScore have no schema descriptions, yet the description explains them as 1–5 scores, and it explains workflowPageId as an optional anchor 'when one fits'. This adds meaning the schema does not carry, above the baseline 3.

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?

Specific verb (file/propose) + resource (AI-PROPOSED opportunity) with an explicit scope note that it targets the review queue. It directly differentiates itself from the sibling compass_opportunities_create, so an agent can distinguish the two 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?

Explicitly frames when to use this versus the alternative ('Unlike compass_opportunities_create this needs NO approval') and gives a precondition ('Check compass_opportunities_list first so you never duplicate'). Both the alternative and the exclusion condition are named.

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 cover the safety profile (readOnly=false, destructive=false). The description adds real behavioral context beyond that: it creates a linked Ledger decision entry, readings flow in automatically as evidence, revisions happen by superseding, and it may return needs_confirmation. It doesn't fully explain the confirmation/approval round-trip, keeping it from 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?

Front-loads the core purpose in the first clause, then layers conditions and mechanics in tight, waste-free sentences. No filler, and the honesty framing is placed where an agent reads first.

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 does cover the notable return case (needs_confirmation) plus the downstream evidence behavior. For a 9-parameter tool with a nested object and an approval flow, it is nearly complete, lacking only explicit guidance on the approvalId sequencing.

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 high (89%), so baseline is 3, but the description adds meaning beyond the schema by tying metricId + comparator + target together as a binding unit and clarifying the evidence flow. The per-parameter details (target, deadline, fromRollup) are already well documented 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?

States a specific verb (pre-register/write) and resource (an experiment's expectation on an opportunity), and frames the unique value proposition ('the honesty mechanism') that no sibling offers. An agent can distinguish it from compass_opportunities_create or ledger_entries_create 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?

Gives clear timing ('BEFORE evidence exists', 'never backfill') and names the related tools (ledger_metrics_list) needed to make the expectation measurable, plus the one-per-opportunity rule with the supersede-in-Ledger alternative. It stops short of explicitly stating when to prefer this over a plain ledger entry or opportunity update, so it is clear context but without full exclusions.

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, so the mutation risk is known; the description adds real value by disclosing the needs_confirmation/approvalId flow and the conditional Ledger side effects that follow a status move. It stops short of describing reversibility or permissions, but the annotation coverage lowers the burden.

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 action, then branches into status-name sourcing, legacy keys, Ledger conditionals, and the confirmation signal. Every sentence carries distinct operational information with 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 destructive mutation with no output schema, the description covers the confirmation handshake and downstream tool routing well. It does not state what a successful response contains, but in the absence of an output schema this is a minor 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 the baseline is 3, but the description meaningfully clarifies the status/statusName relationship ('the old lane keys still work and land on that lane's default status') and directs where status names come from. This is more than the schema conveys about defaulting behavior.

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 precise verb (move) and resource (a change/opportunity) plus the target (a workspace status), and names the sibling compass_statuses_list for obtaining status names. A reader can distinguish it from compass_opportunities_update and other siblings 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?

Gives explicit routing: use statusName from compass_statuses_list, legacy lane keys still work; only experiments follow the Ledger, with named follow-ups (compass_opportunities_register_expectation, ledger_entries_settle) and the exact conditions that trigger them, while 'Other changes just move.' It tells the agent when to reach for other tools and when to do nothing further.

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 openWorldHint=false, so the write profile is covered. The description adds genuinely useful behavior beyond that: partial-update semantics ('fields you omit are untouched') and the confirmation round-trip. It stops short of noting that tags/notes are replaced rather than merged, which the schema covers instead.

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-loads the field list, then the constraints (partial update, sibling exclusion, id source, confirmation), with no filler. The single dense sentence is efficient, though slightly list-heavy.

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 mutation with no output schema, the description covers partial-update behavior, id sourcing, the status-tool boundary, and the confirmation flow. Only the replacement-vs-merge nuance for tags/notes is left to the schema.

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 83%, so the schema already documents nearly every parameter. The description's field list largely mirrors the schema and adds little new syntax, though flagging ownerPageId as 'a PERSON page' is a helpful clarification. Baseline 3 is appropriate.

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 (corrects/edits) and resource (an opportunity's content) and enumerates the editable fields, so the scope is unambiguous. It explicitly distinguishes itself from compass_opportunities_set_status by declaring the lane is NOT handled here.

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 explicit routing: use compass_opportunities_set_status to move the lane, and get ids from compass_opportunities_list. It also prescribes the interaction protocol for the needs_confirmation response (say what you're changing and wait).

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 readOnly=true, so safety is covered; the description goes further with edge directionality, hydration with endpoint summaries, and the temporal filtering rule for includeEnded (validTo in the past). This is meaningful behavioral 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?

Two dense sentences with zero filler. Return shape and the includeEnded toggle are front-loaded appropriately.

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 partially explains return content (edges hydrated with endpoint summaries), which is what an agent needs. Minor: it doesn't detail pagination or the summary fields, but that is a small gap for a read 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 100%, so baseline is 3, but the description adds meaning to includeEnded beyond the schema's terse wording—clarifying that ended relationships have validTo in the past and are useful for historical questions.

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 (list the typed edges touching one page), explicitly notes scope (both directions, hydrated with the other endpoint). An agent can distinguish this from compass_links_create/update/delete at a glance.

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 concrete usage context: 'understand a subject's neighborhood before adding to it' and 'who handled this before' for includeEnded. No alternative sibling is explicitly named, so it stops short of a 5, but the when-to-use scenarios are clear.

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 readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the description isn't needed for the safety profile. It adds real non-annotated behavior: the possible needs_confirmation response, the requirement to get user approval and re-call with approvalId, and a data-fidelity constraint ('only record what the human has actually told you'). It doesn't describe the created return shape, but no output schema exists so a full 5 isn't warranted.

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, front-loaded with the create action, followed by the dedupe check, the approval flow, and the fidelity constraint. Every sentence earns its place with no repetition of schema content.

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 7-param create tool with no output schema, the description covers purpose, routing, and the non-obvious confirmation round-trip well enough to call correctly. It stops short of explaining downstream effects of the created page or the full type taxonomy usage, but the schema fills those gaps.

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 all seven parameters (including the enum for visibility and the type taxonomy) are already fully documented. The description only ties the approvalId to the confirmation flow, which the schema explains anyway, so it adds little beyond structured fields. 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?

States a specific verb (creates) plus resource and scope (a typed page in the workspace's Compass compendium), which cleanly separates it from compass_pages_update/list/search. It even names compass_pages_list as the sibling to consult first, so an agent can route correctly 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?

Explicit when-to-use and when-not guidance: 'Check compass_pages_list first — don't create a page for a subject the map already has; link to it instead.' It also documents the confirmation flow and what to do when needs_confirmation is returned.

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 the description adds substantial context beyond that: it is a soft delete, connections and anchored opportunities are cascaded with it, restore reverses the whole set, and it may return needs_confirmation requiring the page to be named and approval awaited. That is rich behavioral disclosure covering scope of destruction and reversibility.

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-loads the core behavior (trash/soft delete) before the routing guidance, and every clause earns its place: scope of cascade, alternative tool, id provenance, confirmation protocol. 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 destructive tool with no output schema, the description covers what an agent needs: the mutation's effect, cascading scope, reversibility, id source, and the needs_confirmation approval loop. Nothing material is missing.

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 schema already documents pageId, workspace, and approvalId, and the description adds provenance ('Page ids come from compass_pages_list / compass_pages_search') plus the confirmation/approval flow context. Useful beyond the schema, though it does not restate the workspace-scoping semantics.

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+resource ('Moves a page to the trash') and immediately qualifies it as a soft delete. It explicitly contrasts itself with siblings compass_pages_restore and compass_pages_update, so an agent can route correctly 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?

Gives explicit when-to-use ('REMOVE a page you or an extraction created wrongly, or one the user says no longer belongs') and an explicit alternative ('to fix a wrong title or body, use compass_pages_update instead'). Nothing is left to inference.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses the payload contents (full Markdown body, header fields, attached sketches), which tells the agent what to expect in the response.

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 sentence that is front-loaded with the core action and result contents. The trailing em-dash aside about napkin_boards_view is useful but slightly crowded into the same sentence, costing a point on structure.

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 carries the burden of explaining returns, and it does so adequately (body, header fields, sketches). Annotations cover the safety profile and the schema covers both parameters, so the remaining gaps (error behavior, page-not-found handling) are minor.

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 (pageId and workspace) are already fully documented in the schema, including the per-call workspace override rules. The description only restates 'by id' and references boardId for a sibling tool, adding little beyond the schema. Baseline 3 is appropriate.

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 (fetches) and resource (one Compass page by id), and enumerates what is returned (Markdown body, header fields, attached Napkin sketches). This clearly distinguishes it from compass_pages_list and compass_pages_search, which handle collections or querying rather than single-page retrieval.

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 a concrete usage cue — view an attached sketch via napkin_boards_view before discussing it — which routes the agent to the right sibling for the sketch sub-task. It does not, however, state when to use this vs. compass_pages_list or compass_pages_search, so primary-tool selection is left to inference.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are summaries (not full pages), paginated at 50 with limit/offset, and the response carries total and nextOffset. It does not mention workspace-scoping behavior, but the schema covers that.

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 purpose and scope, then the type filter, then pagination and routing. No sentence is expendable.

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?

Although there is no output schema, the description compensates by stating that the return is summaries with total/nextOffset, so an agent knows both the shape and the paging loop. Nothing needed to call it correctly is missing.

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 100%, so the baseline is 3. The description restates the type enum and the limit/offset pagination model, which largely duplicates the schema rather than adding format or syntax detail beyond it.

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 ('Lists pages in the active workspace's Compass compendium') and immediately distinguishes the tool from compass_pages_get (full body) and compass_pages_search (better first call when you know the target). An agent can select it confidently without opening the 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?

Explicit routing: use compass_pages_search when you know what you're looking for, use compass_pages_get to fetch a full body, and this tool otherwise. Both alternatives are named with the conditions that favor them.

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 declare readOnly=false, destructive=false, openWorld=false, which says little about what this write does. The description adds the crucial cascade behavior (connections and opportunities are restored along with the page), the not_found failure mode for already-live or nonexistent pages, and the needs_confirmation return path — all behavior beyond structured fields.

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, each earning its place: the action and its cascade, the use condition, and the failure/confirmation semantics. Front-loaded with the operation before the routing advice.

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 mutation tool with no output schema, the description covers the restore semantics, cascade effects, error case, and confirmation path, which is nearly everything an agent needs. The only gap is that the needs_confirmation follow-up (gathering approval) is not spelled out in the description, though the approvalId schema field does cover it.

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, and the description adds real value on top by explaining where pageId originates (a prior compass_pages_delete or the trash) rather than just 'Id of the deleted page'. It does not explain the approvalId follow-up flow, which the schema carries alone.

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 ('puts a trashed page back on the map') and goes further by naming the scope of restoration — the connections and opportunities that the delete removed. An agent can distinguish this from compass_pages_delete and compass_pages_get 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?

Explicitly says when to use it (user wants a deleted page back) and where the pageId comes from (the earlier delete call or the Compass trash). It also implies when not to use it via the not_found conditions, but never names an alternative tool or states an exclusion rule directly.

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 establish the safe read-only, non-destructive, closed-world profile, so the bar is lower. The description adds genuinely useful behavior beyond that: match semantics, pagination, and the fact that results are truncated to a 300-char body snippet with a pointer to fetch full text.

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 tight sentences, front-loaded with the operation and its scope, then the primary use case, then the return-format caveat. Every sentence earns its place with 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?

With no output schema, the description steps in to describe the return shape (summaries with a 300-char snippet) and the path to full content. Combined with the annotations and fully-described schema, an agent has everything needed to call this correctly.

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 100%, so the schema already documents all five parameters (including `workspace` auth nuance and `q` guidance). The description adds nothing parameter-specific beyond noting the search fields and pagination, which is the correct baseline when the schema does the heavy lifting.

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 ('Keyword search over page titles, bodies, and tags') and precisely characterizes matching semantics (case-insensitive substring). It also distinguishes itself from the sibling `compass_pages_get`, so an agent can route 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?

Gives a clear use case ('fast way to check whether a subject already has a page before creating or linking') and an explicit alternative for full text (`compass_pages_get`). It does not differentiate from the other sibling `compass_pages_list`, which is a plausible source of confusion.

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, but the description adds the crucial nuance that title/body/tags replace wholesale (data loss) while headerFields MERGES, plus the needs_confirmation/approvalId flow. This is real behavioral context beyond the annotation. Minor gap: no statement of required permissions/scopes for editing.

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 core action and field list; every clause is informative. Slightly dense with em-dashes and parentheticals, but nothing 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 destructive mutation with no output schema, the description covers the workflow, field-replacement semantics, the confirmation return path, and prerequisite fetches. An agent has everything needed to call it correctly.

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, but the description adds the replace-vs-merge distinction with a concrete example ('set the owner leaves status alone') and explains approvalId re-call semantics. It reinforces and slightly extends the schema documentation.

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 (Edits) and resource (an existing page), enumerates the editable fields, and explicitly distinguishes itself from compass_pages_create by telling the agent to fix rather than duplicate. An agent can select this over siblings 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?

Explicit routing: use this to FIX mistakes instead of creating a duplicate, fetch current state with `compass_pages_get` first, and get page ids from `compass_pages_list`. It also names the alternative and the condition that selects it, leaving nothing to inference.

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?

Adds real behavior beyond the annotations: proposals wait for a human unless a serves link ties the workflow (then kept at once), and dedup/idempotency ('steps already tied or proposed aren't proposed again, so it's safe to run as the map grows'). Annotations only cover read/write and destructiveness, so this human-confirmation workflow is genuinely new information.

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 action, but the long opening sentence is overloaded with nested parentheticals ('(or VALUE)', '(or where the business lives the value)') that hurt readability. The subsequent sentences are efficient, but it is denser than it needs to be.

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 covers the mutation semantics, the confirmation flow, and idempotency well enough for correct invocation. Return format is left implicit, which is the main 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% with both parameters documented, so baseline 3 applies. The description clarifies that pageId is a PRIORITY or VALUE page, which is a marginal semantic addition already implied by the schema description.

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+resource: reads every mapped workflow against one PRIORITY/VALUE and proposes the steps that move it. This is clearly distinguishable from generic page/step siblings, though the parenthetical hedging ('or VALUE', 'or where the business lives the value') slightly muddies the single core action.

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 explicit preconditions: 'Use it after a priority is named and workflows are mapped, or when someone asks what moves a priority.' Clear when-to-use context, but it never names an alternative tool (e.g. why not compass_step_suggestions_build), so it stops short of full routing.

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 annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: it creates the diagram when absent, moves any existing mermaid block verbatim into the diagram and leaves the page body, preserves node ids for step anchoring, enforces one diagram per workflow, and may return needs_confirmation. This goes well beyond the safety hints and explains side effects and approval flow.

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 front-loaded with the core action and scope, then uses each subsequent sentence to add necessary edge-case rules, routing advice, and approval signaling. There is no filler or repetition; every sentence earns its place.

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 mutation tool with no output schema, the description covers the essential return signals (diagram, diagramId, needs_confirmation), idempotent creation, mermaid migration, and multi-user consolidation. The only minor gap is that it does not describe the full return payload shape beyond the diagram and diagramId, but it provides enough for an agent to call and handle the tool correctly.

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 100%, so the schema already documents pageId, workspace, and approvalId in detail. The description adds only indirect context for approvalId via 'May return `needs_confirmation`' and does not elaborate on workspace behavior, leaving this at the baseline level for high-coverage schemas.

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 a specific verb and resource: 'Returns the Napkin diagram that holds a WORKFLOW page's steps, creating it when the page has none.' It distinguishes itself from siblings by describing get-or-create semantics and explicitly routing edits to napkin_diagrams_update, so an agent can tell it apart from napkin_diagrams_create or compass_pages_get 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?

The description gives clear when-to-use guidance: call this to obtain a workflow's steps diagram, then edit the returned diagramId with napkin_diagrams_update. It also names an alternative for checking existence ('compass_pages_get returns processDiagramId when one exists') and instructs adding steps to the single diagram rather than creating a second.

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 readOnly/non-destructive/non-open-world, so the description focuses on payload substance: what each row contains, that unchanged roles are included too, and that totals are appended. It doesn't cover ordering, pagination, or size behavior for very large workspaces, which is a real gap for an 'every role' read.

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 core scope statement is front-loaded, and every clause carries information about the returned fields. The stage enumeration and attention-reason list make the sentence long and dense, but nothing is padding.

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 must carry the return shape and it does: per-role row fields, totals row, inclusion of unchanged roles, and the sibling for drill-down. What's missing is operational detail — result ordering, volume limits, and whether attention reasons are always populated.

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% and the single workspace parameter is fully documented in the schema, so the description adds no syntax or format detail. The phrase 'in the workspace' only echoes scope already stated by the parameter. 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?

States the exact resource (every role in the workspace, one row each) and enumerates the metrics produced: documented hours vs. working month, saved hours, saved-hours by stage, judgment work before/now, new work, and attention reasons. It is immediately distinguishable from compass_role_story, which is explicitly named as the single-role alternative.

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 (compass_role_story) and the selection rule (one role's detail vs. all roles), and adds a framing constraint ('talk about roles, never about people'). It lacks an explicit when-not-to-use or prerequisite statement, but the routing guidance is clear.

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 establish a safe, closed-world read, so the description's job is to add interpretation context — and it does: it warns that saved hours are 'unproven' when under half the month is documented and it flags `hoursAssumed` as a full-time default rather than measured data. Those are real caveats an agent would otherwise get wrong. It says nothing about failure modes (unknown rolePageId, wrong page type) or the cost/size of the response.

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 scope statement is front-loaded, which is good, but the core is a single sprawling sentence built from semicolon-chained nested lists (kinds of work, new-work subtypes, stage values) that is hard to parse on first read. Every element is arguably load-bearing for a tool with no output schema, but the structure could be broken into scannable clauses or a short list.

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, so the description must describe returns, and it does so thoroughly — baseline vs current hours, event timing, adopted work and settlement, role sizing, documentation coverage, and analysis stages with their enum meanings. The main omission is error/edge behavior and confirmation of what identifies a valid ROLE page.

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?

With only two parameters at 100% schema description coverage, the schema already carries the semantics, including the personal-token/workspace rule. The description adds no meaning about rolePageId beyond the schema's 'The ROLE page's id.'. `hoursAssumed` is referenced but it is a response field, not a parameter.

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 title plus opening phrase 'One ROLE page's story' gives a specific resource and scope, and the body enumerates exactly what data the page story contains (hours by work kind, what landed, new work, role size, latest analysis). An agent can tell this is a per-role read rather than a listing tool. It stops short of naming the near neighbors it differs from (compass_roles_overview, compass_pages_get, compass_transformations_read).

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?

There is no statement of when to call this versus compass_roles_overview, compass_pages_get, or compass_transformations_read, and no preconditions (e.g. that rolePageId must reference a ROLE-type page). The closing directives ('say so' when documentation is thin, 'talk about the role, never about a person') guide how to narrate the output, not when to select this tool.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds real behavioral content beyond them: results include changes affecting nested workflows and changes anchored to the workflow with no effects yet, and each entry carries its per-step effect. That materially shapes what the agent expects back.

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, front-loaded with what is returned and followed by the actionable next step. The em-dash clause about nested workflows is slightly tangled but every sentence earns its place; 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?

With no output schema, the description carries the burden of describing return content, and it does so reasonably (changes with per-step effects, including nested and anchored ones). It omits ordering/pagination expectations and any workspace-param caveat, but for a two-parameter read tool this is close to sufficient.

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 100%, so pageId and workspace are already fully documented in the schema. The description adds nothing about either parameter (no format hints for the workflow page id, no workspace behavior), so the 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 names a specific verb+resource (list changes reaching a workflow's steps) and adds scope detail about nested workflows and anchored-but-inert changes, so the agent knows this is a change-discovery query rather than a mutation. It differentiates from siblings partly through the rollup cross-reference, but does not contrast itself with nearby tools like compass_changes_upsert or compass_workflow_steps.

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 a genuine downstream instruction (pass returned ids to compass_workflow_rollup's changeIds to project the workflow), which names a sibling and a concrete next action. However, it never states when to call this tool versus alternatives, nor any prerequisites for the workflow state, so usage is only implied.

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 establish the read-only, non-destructive, closed-world profile, so the bar is lower. Beyond that, the description discloses genuinely useful behavior: the fixed group taxonomy (TRIAGE/BACKLOG/ACTIVE/DONE/CANCELED) and the key invariant that groups are stable across workspaces while names are customisable.

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 definition is densely front-loaded: it states the resource, the return ordering, the group taxonomy, the stability caveat, and the routing pointer in a compact set of sentences. The parenthetical group codes are load-bearing rather than filler, though the sentence is fairly long.

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 simple read-only list with no output schema, the description supplies what an agent needs: what is returned (statuses, their names, their groups and ordering) and how to reason about the values. Nothing material is missing for correct invocation.

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 100% for the single workspace parameter, so the schema already carries the semantics and baseline 3 applies. The description only alludes to workspace scoping indirectly ('this workspace's changes') without adding format or override details.

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 specific verb and resource — listing the change statuses of a workspace — and clarifies that they come back in board order. It also distinguishes itself from the mutating sibling compass_opportunities_set_status, so an agent can pick this tool without ambiguity.

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 clear operational guidance on how to interpret and use the returned values (names when talking to people, groups when reasoning about progress) and routes the agent to compass_opportunities_set_status for the mutating counterpart. It stops short of an explicit when-to-call-this-vs-another-list-tool exclusion, but the context is clear.

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 cover the safety profile (readOnly, non-destructive, closed world), so the description correctly focuses on behavior instead: oldest-first ordering, coexistence of disagreeing claims, source retention, and the AI_PROPOSED review state. These are real traits beyond the annotations, with only pagination/result-size behavior left unstated.

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?

One front-loaded sentence plus a compact colon-delimited field list; every clause carries information about the returned shape. It is dense but not padded, and the ordering guarantee appears early.

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 takes on the burden of describing the return shape, and it does so well (step, subject, relation, source, validity window, origin). Missing only minor operational detail such as result limits or pagination for large claim sets.

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, but the description adds meaning the schema lacks: nodeId of null means 'the workflow as a whole' rather than a specific step, which materially affects how the filter is used. The workspace parameter semantics are left to 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 states a specific verb+resource – listing every claim about a WORKFLOW's steps – and the title reinforces it. It does not explicitly distinguish itself from the sibling compass_step_claims_propose, but the read/list scope is unambiguous.

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 implied rather than stated: the agent can infer this is the read path for claims, and the note that AI_PROPOSED claims await human review hints at where the data comes from. However there is no explicit when-to-use, no mention of the propose sibling as the alternative, and no guidance on when the nodeId filter should be applied.

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?

Goes well beyond the annotations: claims land as proposals pending acceptance, except sourceKind 'user' in a map-questions conversation which is kept immediately, and re-proposing from the same source returns the existing claim (idempotency). This is strong behavioral detail, though it doesn't describe limits like maxItems=50 coupling to error behavior.

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 purpose and highly information-dense; nearly every clause earns its place. The nested parenthetical enumerating relation meanings is dense and slightly run-on, but not wasteful.

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-parameter, no-output-schema mutation tool, the description covers attribution, idempotency, missing-step handling, and the 'user' exception, leaving nothing an agent needs in order to invoke it correctly.

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 80%, yet the description still adds real meaning: it decodes each relation, explains the subjectPageId type mapping per relation, and clarifies sourceKind/sourceId pairing and the 'user' special case. Substantially more than the schema alone conveys.

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 (propose) and resource (step claims about who does what in a workflow), and the parenthetical detail about relations and subject page types makes it unmistakable against siblings like compass_step_claims_list or compass_step_measures_propose.

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?

Explicit when-to-use rules: one call per workflow for who and what together, add the step via napkin_diagrams_update first when a step is missing, record disagreements as their own claim rather than skipping, and prefer ROLE vs PERSON depending on context. Alternatives and exclusions are named.

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 establish this is a write (readOnlyHint=false) that is non-destructive and closed-world, and the description adds meaningful lifecycle context beyond that: proposals 'count once someone accepts them in Compass', i.e. they are staged rather than committed. It doesn't detail auth requirements, limits on item count beyond the schema, or error behavior, but the acceptance-gate disclosure is valuable extra context.

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 intent followed by dense, example-driven bullets that each carry new information (unit, currency, per period, returnRate range). It is long, but the length tracks real complexity of the item union; little 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?

For a 5-parameter, nested-item, no-output-schema mutation tool, the description covers the semantics that matter most for correct invocation and even explains the acceptance lifecycle. Gaps remain on temporal fields (validFrom/validTo) and source attribution params, which prevents a 5.

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 60%, and the description compensates well: it defines the item union semantics (working, waiting, hardCost, frequency), the frequency-with-null-nodeId vs variantId distinction, and explains subjectPageId's pricing-through-role behavior, which the schema leaves undocumented. validFrom/validTo and sourceId/sourceKind get no extra explanation, keeping it from a 5.

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 — proposing estimates (measures/gates) for a workflow's steps — and anchors it to `compass_workflow_steps` for nodeId, so an agent knows the object graph. It does not explicitly differentiate from near siblings like compass_step_claims_propose or compass_step_suggestions_build, which keeps it at a 4 rather than a 5.

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 real usage context: propose ranges (not point estimates), 'ask about waiting separately', pass subjectPageId when the time belongs to one role/person, and 'Always say who said it.' What's missing is explicit when-not or alternative-tool routing against sibling propose/build tools, so it lands at 4.

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 readOnlyHint=false and destructiveHint=false already declared, the description usefully adds that the tool fails if something is already built for the suggestion and that a flow draft may still need work. These are behavioral traits beyond the annotations. It does not mention permissions or auth requirements for a mutation, which keeps it at 4.

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 verb and reasonably sized, but the em-dash clause listing flow contents ('who does it, its times, systems, write-up, attachments, interview notes') is a slog and the 'the way Compass's Build button does' analogy assumes external product knowledge. Information density is good; parseability is not.

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 mutating tool with no output schema, the description covers the return ('what was built and, for a flow, what the draft still needs') and the failure condition. The one real gap is approvalId, which is undefined everywhere, plus no statement of what gets created/overwritten at the workspace 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 75%; suggestionId and pageId already carry descriptions, and the description adds no format or syntax detail beyond pointing at compass_step_suggestions_list (which the schema already does). approvalId remains undocumented in both places. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Names a specific verb ('Builds') and resource ('a step suggestion') and enumerates the three artifacts it can produce (a flow draft with checklist, a shim, or a task), which is far more than a restatement of the title. The middle clause is a tangled run-on that assumes familiarity with 'the Build button,' keeping it from being a crisp 5.

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?

Explicitly routes the agent: 'Use this, not workbench_flows_scaffold, whenever the work came from a step suggestion.' That names the alternative and the selecting condition. It does not spell out when-not to use it beyond the failure precondition, so it stops 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description goes beyond that by explaining what the returned data means — state OPEN waits for a person, APPLIED produced a change with an opportunityId, and `built` reflects what was constructed in Workbench. It omits pagination, result limits, and auth requirements, keeping it from 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?

Every clause carries information, and the sibling routing is placed last where it is most actionable. The opening sentence is a long, heavily parenthesized run-on ('for each suggestion... (nodeIds, labels)... (proposal.doer)... (reach)... (checklist, each item met or not)') that is dense rather than front-loaded, costing some readability.

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?

There is no output schema, so the description must carry the return-value burden, and it does: it enumerates the fields of each suggestion record (nodeIds, labels, proposal.doer, reach, rationale, checklist) and defines the state vocabulary. For a read-only, zero-required-parameter list tool, an agent has everything needed to call it and interpret the result.

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 adds real routing semantics the schema does not convey: pageId and changeId are alternative modes that return different cardinality (all suggestions for a page vs. the single suggestion a change came from). The `workspace` parameter's token-dependent behavior is left entirely to 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 (list) and resource (step suggestions for a workflow), and the title/description both make the resource unambiguous. It explicitly distinguishes itself from the two nearest siblings, naming compass_step_suggestions_build and warning off workbench_flows_scaffold.

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 alternate invocation mode: 'Pass changeId instead of pageId to get the one suggestion a change came from.' It also routes the agent to the correct tool for the follow-up action ('To build one, use compass_step_suggestions_build — not workbench_flows_scaffold'), which is a genuine when-not instruction.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable content beyond annotations: it explains what the response contains (the five levels, whether each fits/is reached/what it needs, time freed, change made), names the recommended level, defines 'settled', and explains 'running' vs null state with the sibling that starts a read. This is rich disclosure about return content.

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 a single dense sentence followed by a shorter state-explanation sentence. It is front-loaded with the core content, but the first sentence is very long and packs many clauses together, which reduces readability. It earns its length given the complexity, but structure could be clearer.

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?

There is no output schema, so the description must explain the return content, and it does so thoroughly: levels, per-level status, changes, time freed, the change made, and the recommended level. It also explains the state values and the companion tool. It is largely complete for a two-parameter read tool, though it could say a bit more about the overall object structure.

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 100%, so both parameters (workspace, priorityPageId) are already documented in the schema. The description adds no parameter-level syntax or semantics beyond what the schema provides, so the baseline of 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 clearly states the resource (the workflows behind a PRIORITY) and the extracted structure (five levels with fit/reached/needs, changes, time freed, change made, recommended level). It is a read tool and the verb is implied by the title 'Read a priority's transformations'. It does not explicitly distinguish itself from compass_transformations_read, though it hints at the relationship via the state field.

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 implied by referencing compass_transformations_read as the tool that 'starts one', giving a hint about the ordering. But there is no explicit when-to-use-this-vs-alternatives guidance, nor any statement of exclusions or prerequisites beyond that one parenthetical.

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 a non-read-only, non-destructive, closed-world write. The description adds real context beyond that: it drafts up to three flows in Workbench ('builds', each 'drafting' until ready), enforces a once-per-level rule, and can return a needs_confirmation envelope. This goes well past what the annotations convey.

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?

Effectively a single dense sentence, front-loaded with the core action ('Creates a Change...'), followed by supporting detail. Compact and largely waste-free, though the run-on nature makes it slightly harder to parse at a glance.

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 non-destructive mutation tool with annotations present, no output schema, and fully documented params, the description covers the key behavioral outcomes (drafting flows, per-level constraint, confirmation return). Nothing critical for correct invocation appears missing.

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 100%, so the schema already documents all four parameters (level enum, workspace, approvalId, priorityPageId). The description reinforces that approvalId ties to a needs_confirmation result and that level drives which flows get built, but adds little syntax beyond the schema. Baseline 3 is correct.

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+resource — 'Creates a Change from one level of a priority's transformations' — with the source level and priority clearly identified. It is distinguishable in intent from siblings like compass_changes_upsert, but it never names or contrasts an alternative explicitly.

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?

Provides an implied usage constraint ('Only a level that fits, once per level') and notes that the tool 'May return needs_confirmation', which hints at the confirmation flow. However, it offers no explicit guidance on when to choose this versus compass_changes_upsert or the transformations_* siblings.

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 readOnlyHint=false, which is surprising for a tool named "read"; the description reconciles this by explaining it kicks off an asynchronous background job. It further discloses the rough latency ("a minute or two") and dedupe behavior for in-flight reads, adding real value beyond the structured hints. It stops short of describing failure modes or what invalidates a run.

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, front-loaded with the action and its async nature, then the precondition, then the follow-up. No filler and nothing buried.

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 async job-starter with no output schema, the description supplies what an agent actually needs: it's a background kickoff, it takes time, don't re-trigger an in-flight read, and poll with compass_transformations_get. Only error/edge-case behavior is left implicit.

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 100%, so both parameters are already documented in the schema. The description references the PRIORITY target that maps to priorityPageId but adds no format or semantics beyond the schema, so the 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 a specific action ("Starts reading the five levels for a PRIORITY in the background") that is distinct from the sibling compass_transformations_get, which it names as the polling counterpart. The terminology ("five levels", "transformations") is domain-specific but the verb+resource pairing is clear enough to identify intent.

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 a concrete precondition ("Needs at least one kept step that impacts the priority") and explains the concurrency rule ("A read under way is left to finish"). It also names the follow-up tool explicitly, though it doesn't contrast itself against the mutation siblings like transformations_make_change.

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 declare write/non-destructive/closed-world; the description goes well beyond by disclosing the actual side effects: Compass derives a level label, stores facts on the steps they concern (visible to every later reading of those workflows), raises open questions, and re-reads the priority. That is exactly the propagation and post-write behavior an agent needs to know before calling a mutation.

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?

Purpose is front-loaded in the first clause, and the sentence structure separates input, background processing, and usage trigger. The middle list of examples ('work still done on paper, and so on') is slightly loose but each item aids recognition, so little 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?

With no output schema, the description carries the burden of explaining what happens after the call, and it does: labels, step-attached facts, open questions, and a priority re-read. It stops short of stating return shape or error/permission conditions, but nothing essential for correct invocation is missing.

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 100%, so params are already documented (level meaning, said, priorityPageId, workspace). The description adds only a light gloss on 'said' ('in their words or a faithful summary'), which is useful but not beyond the schema's own description. 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 names a specific verb and resource: recording what a person said about one level of a PRIORITY's current transformations, and it enumerates the kinds of content (already do it, what rules it out, work on paper). It does not explicitly distinguish itself from near siblings like compass_transformations_make_change or compass_transformations_read, so an agent must infer the boundary, but the purpose itself is unambiguous.

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 a clear trigger: 'Use it whenever a conversation settles something about a level,' plus the rationale that the result lands on the priority's page rather than only the chat. It does not name alternatives or exclusions (e.g., when to use make_change instead), 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.

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

Annotations already declare the safe-read profile, and the description adds genuinely non-structured behavior: newest-first ordering, the composition of the feed (step additions/removals plus claim events with replacement text), inclusion of source per item, and the key distinction that timestamps reflect when something was LEARNED versus when it was true (validFrom/validTo). It omits pagination/limit behavior.

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 content and ordering lead, with only two sentences and no filler. The em-dash-heavy run-on in the first sentence is dense and slightly hard to parse, but every clause adds information rather than restating the name or annotations.

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 carries the full burden of explaining return values, and it does so in reasonable detail (event types, sources, ordering, temporal framing). It is nearly complete; only absent details like pagination or the default behavior of `since` keep it from a 5.

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, but the description earns above baseline by disambiguating the temporal semantics of the `since` filter—clarifying it bounds learning-time, not claim validity. That directly resolves the ambiguity the schema's one-line parameter description leaves open.

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 concretely states what the tool returns: a newest-first feed of steps added/dropped and claim lifecycle events (said, corrected, withdrawn, accepted), each with its source. That is a specific resource and clearly more than a restatement of the name. It stops short of naming the overlapping siblings (compass_step_claims_list, compass_workflow_steps, compass_scenario_changes), so an agent must infer the boundary.

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 two concrete use cases—briefing someone on what changed, and seeing what an interview added—which implies when to reach for it. However it never contrasts with the natural alternatives (a plain step list or claims list), and there are no when-not-to-use notes. Usage is implied rather than dictated.

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 readOnlyHint/destructiveHint/openWorldHint already covering the safety profile, the description adds substantive behavior: nested-workflow recursion ('a step that is itself a workflow uses that workflow's roll-up unless it has its own estimate'), the meaning of coverage, and the unpricedRoles edge case where time counts but cost does not. These are non-obvious computation semantics an agent could not infer from annotations or schema.

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 output spec is front-loaded and the caveats follow in a logical order, so an agent can parse intent from the first sentence. The prose is dense with em-dashes and parentheticals, but every sentence carries content (recursion, coverage, unpriced roles, interpretation). Slightly heavy, but 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?

There is no output schema, so the description carries the return-value burden and does so: it enumerates the metric families, the low-high range format, per-step shares, gates, coverage, and unpricedRoles. What it does not sketch is the top-level response shape or how per-run vs per-month sections are organized, a modest remaining gap for a six-parameter analytical 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 description coverage is 100%, so the baseline is 3. The description restates 'at' and 'variantId' in prose ('at reads the estimates as of a date; variantId rolls up one variant'), which is roughly equivalent to what the schema already documents, and adds no syntax or default detail beyond it. It does not compensate for anything, but nothing is missing either.

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 gives a precise spec of the resource and its output: per run and per month, hands-on minutes, waiting minutes, labor cost, and hard costs as ranges with per-step shares and gates. It is unmistakably the cost/time rollup rather than the step list or learning tools. It never names a sibling explicitly, so it stops short of the 5 bar of differentiating itself from compass_workflow_steps or caliper_flow_performance.

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 reporting rules ('always say how much of the total rests on estimates before quoting it, and never present a range as one number') and interpretive direction ('where the waiting dwarfs the hands-on time... is usually where the improvement is'). What is missing is explicit routing: nothing says when to call this versus compass_workflow_steps, compass_flow_performance, or compass_workflow_learning. Usage is implied rather than stated.

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 readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered; the description adds the non-obvious behavior that it 'Returns no steps when the workflow has no diagram yet' and resolves subWorkflowPageId nesting. No mention of pagination or result-size limits, but for a scoped read-only list this is solid.

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-loads the primary noun phrase (steps in diagram order) before field semantics, and each following sentence earns its place by decoding output fields. It is one dense run-on block rather than cleanly segmented, but with no output schema the field explanations are justified.

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