ZeroWidth

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 known. The description adds real value by disclosing that existing items and their ratings are untouched, i.e. the append is purely additive. It does not mention the needs_confirmation/approvalId flow, which is only visible in the 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?

Two tight sentences with the core action front-loaded and the alternative/create contrast immediately after. Every clause 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?

For an append tool with no output schema and full schema coverage, the description supplies the needed framing: additive semantics, shape parity with create, and non-destruction of existing data. It omits return/response behavior and the approval pathway, which are minor but leave small 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 the baseline is 3. The description goes beyond the schema by mapping the items payload to 'the same three shapes as caliper_datasets_create (Q&A, sequence, simulated)', giving useful semantic orientation for how the item fields combine. It adds no per-field detail, so it stops short of 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 precise verb+resource ('Appends items to an existing dataset') and explicitly frames the scope contrast with creating a parallel dataset, which separates it from caliper_datasets_create. An agent can identify the operation 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 an explicit when-to-use condition ('grow coverage — new edge cases, scenarios from a completed interview') and names the alternative behavior it replaces ('instead of creating a parallel dataset'). The routing decision versus the create sibling is unambiguous.

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 safety profile is covered. The description adds one genuine behavioral constraint — simulated items are 'Caliper-run evals only' — but says nothing about the notable approvalId/needs_confirmation flow this mutation triggers, leaving a real gap for a 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 purpose and 'first step' positioning, then structured into the three item shapes. It is long, and phrases like the message-ten anecdote and the Compass-source advice are more persuasive than operational, but most content earns its place for a complex nested schema.

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-parameter tool with a nested items array and no output schema, the description covers the item taxonomy thoroughly and explains how each shape is used in evals. The main omission is any mention of the approval/confirmation handshake that the approvalId parameter implies.

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 goes beyond it by organizing the nested item parameters into three named shapes (Q&A / SEQUENCE / SIMULATED) and clarifying the role of fields like disposition, expectedResponse, and expectedBehavior. This adds conceptual meaning over the flat per-field 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?

States a specific verb+resource ('Creates a dataset of test items') and explicitly positions it as 'THE FIRST STEP of setting up evaluation for a flow', which cleanly separates it from siblings like caliper_datasets_add_items and caliper_datasets_update. An agent knows exactly what this does and where it sits in the workflow.

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 ('first step' of eval setup) and prescriptive guidance on when to use sequence/simulated items versus Q&A, plus where to source realistic inputs (Compass pages). It does not explicitly name the alternative sibling for appending items to an existing dataset, so routing is implied rather than spelled 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?

While annotations already flag destructiveHint=true, the description goes well beyond them by disclosing the downstream blast radius: bound evals stop being runnable (datasetOk: false) and reviews/specs lose their source. It also surfaces the two-step `needs_confirmation` / approvalId flow, which is critical operational context for a two-phase destructive call.

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 ('Deletes a dataset') and then spends the remaining words on consequences, the cross-tool check, and the confirmation flow. No filler sentences; every clause carries actionable 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 destructive, no-output-schema tool with full schema coverage, this is exactly the right content: consequences, a related-tool verification step, and the confirmation handshake. Nothing an agent needs to invoke it safely and 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 all three params are already documented and the baseline is 3. The description earns a point above baseline by explaining that the call 'May return `needs_confirmation`,' which clarifies the purpose of the approvalId parameter and how the two-call confirmation sequence works.

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 (Deletes) and resource (a dataset), making it trivially distinguishable from siblings like caliper_datasets_update, caliper_datasets_remove_item, and caliper_datasets_get. The cascade consequences further pin the scope to whole-dataset deletion.

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 explicit pre-flight step: 'check caliper_evals_list for evals that reference it and say so before proposing.' This names a concrete alternative tool and the condition that invokes it. It does not, however, state when not to delete or the exact criteria for bailing out, so it stops short of full when/when-not 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?

Goes well beyond the annotations: discloses that it SPENDS workspace inference credit (one generator call), sits behind an approval gate producing needs_confirmation, returns only a dataset summary, and requires reading items via caliper_datasets_get before trusting an eval.

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

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

Dense but front-loaded and every clause carries information (routing, credit cost, confirmation flow, follow-up). Sentence length runs long, 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?

For a 13-param, no-output-schema mutation tool, the description supplies the missing pieces: cost, approval lifecycle, return shape, and the recommended follow-up call. An agent can invoke this correctly without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real meaning by explaining that flowId causes the generator to read the flow's prompt/mode/schema, and how description can substitute for or augment flowId.

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 NEW dataset of model-written items') and enumerates the shapes it can produce. It clearly distinguishes itself from the hand-written sibling caliper_datasets_create.

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 ('user wants test cases fast and has none') and when-not-to-use ('prefer caliper_datasets_create with hand-written items when real scenarios are already in hand'). It also flags the approval-gate flow the agent should expect.

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 safety hints (readOnlyHint false, destructiveHint false), while the description adds the economically material facts: it SPENDS workspace inference credit, sits behind an approval gate, and leaves existing items and ratings untouched. These are beyond anything structured fields 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 what the tool does, then routing, then the credit/approval warning, then the non-destructive guarantee. Dense but every sentence earns its place; slight compression of the style-inheritance clause could improve 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?

With 10 parameters, full schema coverage, and no output schema, the description supplies the missing behavioral framing an agent needs: cost, approval flow, how generation derives from existing data, and that prior content is preserved.

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 per-parameter docs already exist. The description still adds meaning the schema doesn't state: existing items act as few-shot examples and the output shape matches theirs unless overridden. It does not explain count defaults or workspace/approvalId semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('appends model-written items to an EXISTING dataset') and immediately qualifies how the generated content is derived from existing items. It reads clearly as distinct from both caliper_datasets_add_items (manual) and caliper_datasets_generate.

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 names the trigger phrasing ('more like these', 'add edge cases') and the alternative (caliper_datasets_add_items) with the condition that selects it ('when the scenarios are known'). It also flags the approval-gate workflow, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description still adds real behavioral context beyond them: page size default (25) via limit/offset, that total is the full count not the page, and that long fields are truncated at ~800 chars with a marker.

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 operation and the read-before-write guidance; every clause carries distinct information (dependency, paging, truncation, id source) 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?

No output schema exists, so the description must cover return shape, and it does: one dataset plus a paged item list, total count, and truncation behavior. Combined with annotations and full schema coverage, 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 baseline is 3 and the schema already documents all four params. The description goes a bit further by framing limit/offset as the paging mechanism and stating the source of datasetId (caliper_datasets_list), tying parameters to workflow rather than restating types.

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 (read) and resource (a Caliper dataset) and adds the scope detail 'with a page of its items', which separates it from caliper_datasets_list (no items) and the item-mutating siblings. An agent can identify the tool 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?

Explicitly says to read this BEFORE editing items and BEFORE extending coverage, and names the dependency (caliper_datasets_update_item needs the item id) plus a preventive reason (avoid adding duplicate cases). When-to-use and the alternative are both spelled 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 declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the exact return shape (id, name, item count) and the negative constraint that items are not included, which prevents an agent from expecting embedded item data. It omits pagination, ordering, and result-size limits.

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

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

Two short sentences, zero filler, with the scope ('active workspace') and the return contract front-loaded. Every clause 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?

With no output schema, the description correctly takes on the burden of describing what is returned, and it does so briefly and accurately. It leaves pagination and ordering unspecified, which is a minor gap for a list tool with a single optional filter.

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 one optional parameter and schema description coverage is 100%; the schema fully documents the workspace slug, including the personal-token vs API-key behavior. The description adds no parameter-level detail beyond the phrase 'active workspace', 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 ('Lists datasets') with a scope qualifier ('in the active workspace'), so the operation is unambiguous. It stops short of naming the sibling it contrasts with (caliper_datasets_get for single-dataset detail), relying on 'items are not included' to imply the distinction rather than stating it.

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

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

Use is implied by 'Lists datasets in the active workspace' and by the caveat that items are excluded, which hints an agent should call caliper_datasets_get for detail. No explicit when-to-use, when-not-to-use, or named alternative is given, so the agent must infer the 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?

Annotations already declare destructiveHint=true, but the description goes well beyond them: it discloses the exact consequence of the mutation (ratings and run results are orphaned — kept in history, removed from the dataset), an invariant (minimum of one item), and a non-trivial response behavior (may return `needs_confirmation`). This is precisely the added context destructive 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?

Three short sentences, front-loaded with the action, then consequences, then constraints/response behavior. Every sentence carries distinct information and no filler is present.

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 the destructive effect, the precondition, and the confirmation round-trip. Minor gaps remain (no mention of permissions or what the return payload looks like beyond needs_confirmation), but the schema covers the remaining parameters.

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: it explains the trigger for `needs_confirmation` and therefore the existence/purpose of the `approvalId` parameter, which the schema only describes circularly. It does not clarify `workspace` scoping, so it is not a full 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?

The first sentence states a specific verb+resource ("Drops one item"), which is clear and scoped. However, it largely restates the tool title ("Remove one item from a Caliper dataset") rather than distinguishing itself from siblings like caliper_datasets_delete (whole dataset) or caliper_datasets_update_item; the differentiation is inferred, not 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?

The description gives operational constraints ("A dataset must keep at least one item") and a confirmation flow, but never says when to reach for this tool versus caliper_datasets_update_item, caliper_datasets_delete, or other siblings. No when-not guidance either.

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 and destructiveHint=true, so safety is partly covered, but the description adds non-obvious behavior: this is a PATCH-style partial update where unspecified fields survive, and the call may return a `needs_confirmation` state requiring a follow-up with an approvalId. It does not explain what is actually destructive here (e.g. a visibility downgrade revoking access), which is the one gap.

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 compact sentences/fragments, front-loaded with the primary action and scope, then the exclusion with alternatives, then the confirmation caveat. No filler and nothing rhetorical.

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 still flags the one non-obvious return path (`needs_confirmation`) and the schema documents the approvalId continuation. For a six-parameter mutation with destructive semantics, it is complete enough, though the lack of any note on which changes are destructive or reversible leaves a minor hole.

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%, including a fully documented visibility enum with a natural-language mapping and the approvalId/workspace auth notes, so the schema does the heavy lifting. The description only echoes the three top-level fields and adds the patch-semantics cue, which does not meaningfully exceed what the schema already states.

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 (changes) plus the exact mutable fields (title, description, visibility) of a named resource (dataset), which matches the title. It also explicitly excludes dataset item content and names the siblings that own those operations, so the agent can separate this from add_items/update_item/remove_item without reading 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?

Supplies an explicit when-not rule ('items are untouched') and names three alternative tools for that case, which is exactly the when/when-not/alternatives pattern. The 'Pass only what changes' instruction also tells the agent how to call it (partial update) versus a full replacement.

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 tell the agent this is a destructive non-read-only write; the description adds the important fallout semantics — the id and its attached ratings/eval results survive, the item KIND is immutable, and the call can return `needs_confirmation`. That is materially more than the annotation set provides and does not contradict it (the destructiveHint refers to overwriting the item's content in place).

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, zero filler: the core action and its id-preservation consequence come first, the kind constraint and shape instruction second, the exclusions and confirmation caveat last. Each sentence carries information an agent needs before invoking.

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 essential gotchas (immutable kind, preserved id/ratings, non-editable item types, possible confirmation response). It would be complete if it explained how the returned `needs_confirmation` maps onto the `approvalId` parameter, since that round-trip is otherwise left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by constraining the `item` payload to the same three shapes returned by caliper_datasets_get and warning that the shape/kind cannot change. The `approvalId`/`needs_confirmation` connection is only hinted at rather than explained, keeping this short of 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?

The description uses a specific verb and resource ("Rewrites one item's content") and pins the scope to a single item within a dataset, which separates it from the dataset-level caliper_datasets_update and from caliper_datasets_add_items. It further clarifies the item retains its id, so an agent knows this is an in-place replacement rather than an add/remove.

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 prerequisites ("pass the same shape you read from caliper_datasets_get") and explicit exclusions ("Chat and raw items can't be edited from here"), plus the kind-preservation constraint. It stops short of naming the alternative tool for those excluded shapes or for replacing an item by delete+add, so it is clear context without 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?

Annotations only declare this is a non-destructive, non-open-world write; the description adds real operational context beyond that: external evals require a workspace API key with the ci_evals preset that 'can't be minted from here,' and it explains the draft-vs-published execution behavior at run time. These are meaningful prerequisites an agent would otherwise not know.

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 lead sentence front-loads the core purpose and lifecycle position, and the remaining text is information-dense rather than filler. It runs long and a couple of clauses are heavily packed, but given 12 parameters and two targets, nearly 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?

With no output schema, the description steps in to state what to do with the result ('hand back the eval id and tell the user to create a workspace API key'), and it covers the branching setup, prerequisites, and next-step tool. 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?

Schema coverage is 92%, so the schema does most of the work (baseline 3). The description still adds relational meaning the schema can't express — flowId is only needed for the workbench target, flowRevisionId applies only to the published stage, and the draft/published distinction is spelled out — lifting 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?

States a specific verb and resource — it 'binds a dataset + rubric to something under test as a repeatable eval' — and positions itself in the lifecycle as 'THE LAST SETUP STEP before scoring.' It also distinguishes its job from caliper_evals_run, which does the scoring, so an agent can separate it from 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?

Explicitly describes the two invocation paths (workbench flow via flowId vs target:'external'), when to pick each, when to use flowStage 'draft' vs 'published', and routes to caliper_rubrics_list when a rubric already exists. It even points at the 'Run evals in CI' docs guide for the external path.

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 known, but the description adds real value beyond them: the schedule is stopped, run history becomes unreachable, and the call may return needs_confirmation. It stops short of stating auth/permission requirements or whether deletion is reversible.

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

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

Three short sentences, each carrying distinct information (what is deleted, what happens to history, what a confirmation response implies), with the primary action front-loaded. 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 3-parameter destructive tool with no output schema, the description covers the salient outcomes an agent needs: the eval is gone, its schedule stops, history is orphaned, and a confirmation round-trip may be required. Only the permission/auth prerequisites are absent.

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 earns above that by explaining the needs_confirmation/approvalId retry cycle, which gives the approvalId parameter meaning the schema alone only partially 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 and resource ('Deletes an eval') and immediately names the collateral effect ('stops its schedule'). It reads clearly against caliper_evals_update/run/get, though it does not explicitly differentiate itself from the closer sibling caliper_evals_runs_cancel.

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 when-to-use or when-not-to-use guidance, no statement of prerequisites, and no pointer to alternatives (e.g., cancel a run vs. delete the eval). The only usage-adjacent signal is the approval flow implied by the closing sentence.

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 this as a safe read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered. The description adds genuine behavioral context beyond that: the rubric criteria are a creation-time snapshot, and datasetOk/flowOk=false means a run would fail at resolution, which is decision-relevant context the 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?

The content is front-loaded and every clause describes a distinct returned field, so nothing is filler. It is a single dense run-on sentence, which slightly hurts scanability for an agent parsing it quickly.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of describing the return payload, and it does so comprehensively: it lists every meaningful field, explains the binding-health semantics, and routes the agent to a follow-up action. Nothing an agent needs to call or interpret this tool 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 both evalId and workspace are already fully documented by the schema, setting the baseline at 3. The description adds only a sourcing hint for evalId (get it from caliper_evals_list / caliper_flow_performance) rather than any new format or constraint 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 enumerates precisely what a single eval record contains (target, dataset/rubric ids, rubric snapshot, schedule, run counts, latest score, binding health), so the agent knows exactly what this returns. The verb itself is only implied via the name/title, and sibling differentiation against caliper_evals_list is present but indirect (it only says where to source the evalId).

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 task-oriented guidance: check binding health and 'say so before proposing caliper_evals_run,' which is a real precondition an agent should act on. It names caliper_evals_list and caliper_flow_performance as where to obtain the id, but states no explicit when-not-to-use condition.

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 adds that results are scoped to the active workspace and include target config, but says nothing about pagination, result ordering, or volume.

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

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

Two sentences, no filler. The resource/scope statement comes first and the routing hint second, so the most decision-relevant information is front-loaded.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing what each listed eval contains (target config with flow and dataset/rubric). For a simple read-only list tool with full schema coverage on its one parameter, this is nearly sufficient; only pagination/ordering behavior is unaddressed.

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?

Single optional workspace parameter with 100% schema description coverage, so the schema carries the semantics (default workspace, override behavior, API-key case). The description's 'active workspace' phrasing aligns with that. Zero-param-adjacent baseline 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 (Lists) plus resource (evals) and narrows the scope to the active workspace, then names the returned content (target config: which Workbench flow, dataset/rubric). This distinguishes it from caliper_evals_get (single eval) and caliper_evals_run, which it routes the agent toward.

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: to find the evalId needed by caliper_evals_run. That is a clear downstream purpose, but it names no alternative for other discovery needs (e.g. caliper_evals_get for a known id) and gives no 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 only cover the safety profile (readOnly=false, destructive=false, openWorld=true); the description adds substantial context beyond them — the run is long-running and re-enters THIS conversation automatically on completion, it consumes workspace LLM budget, and it may return a `needs_confirmation` envelope behind an approval gate. That is exactly the behavioral detail an agent needs to avoid polling or misreporting.

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 well organized, but the mid-section sentence about auto-return, budget, and approval is dense and runs long. Nearly every sentence earns its place, so it stays efficient despite the density.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by explaining that the scores arrive via an automatic follow-up in this conversation, plus the approval-gate response shape. For a cost-bearing async mutation tool, nothing essential for a correct call 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 four parameters (evalId, label, workspace, approvalId) are already documented in the schema; the description's mention of the approval gate loosely motivates approvalId but adds no syntax or format detail. Baseline 3 applies when the schema carries the parameter 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 and resource — 'Queues a new run of an eval' — and immediately defines the operation as inference over the dataset followed by LLM-judge scoring. It is clearly distinguishable from siblings like caliper_evals_runs_get, caliper_evals_runs_list, and caliper_evals_runs_cancel.

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 positions the tool as 'THE VERIFY STEP of the improvement loop' and gives the trigger condition: after an approved workbench_flows_edit_text, run the eval again and report the score delta. It also tells the agent not to poll and what to tell the user, which fully closes the usage loop.

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 destructiveHint=true annotation by disclosing exactly how destruction is scoped: the queue stops immediately, an in-flight item finishes on its own timeout, the run settles as FAILED with a 'cancelled' reason, and completed items are retained. It also surfaces the run_not_live failure mode and a possible needs_confirmation response that requires a follow-up call.

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 operation and its eligible states, then layers consequence, error, and confirmation behavior in short sentences with no filler. Every sentence carries information an agent needs before calling.

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, but the description compensates by covering the terminal state of the run, what is preserved, and both the error and confirmation paths. Combined with destructiveHint annotations and fully documented params, 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 description coverage is 100%, so runId, evalId, workspace, and approvalId are all documented in the schema; the description adds only the indirect hint that needs_confirmation implies a second call carrying an approvalId. Baseline 3 is appropriate given 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 ('Stops') and resource ('a run') with an explicit eligible-state set (PENDING / RUNNING / SCORING), which distinguishes it from read-only siblings like caliper_evals_runs_get and caliper_evals_runs_list. An agent can identify the operation 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 motivating contexts — a run spending more than expected, or started by mistake — and an implicit exclusion via 'A run that already finished returns run_not_live.' It does not name an alternative tool for the already-finished case, but no sibling offers a competing cancellation path, so little 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 it is a safe, read-only, non-destructive, closed operation, so the safety profile is covered. The description adds genuine output-shape context: by default returns the ten lowest-scoring items, 'all' is large, 'none' yields totals only, and it works for CI-submitted runs.

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 return content ('One run: status, overall score...') and stays compact, though the capitalized 'THE ANSWER' aside is slightly editorial. Every sentence carries information about output or usage.

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 convey return values, and it does: status, overall score, per-item per-criterion scores, judge reasoning, and the items/limit default behavior. An agent has enough to call it correctly 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 description coverage is 100%, so the baseline is 3. The description restates the items behavior (all/none) that the schema already documents and adds only the 'explain a drop' framing, adding little beyond the structured fields.

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 with scope: reads one eval run, returning status, overall score, and by default the lowest-scoring items with per-criterion scores and judge reasoning. It clarifies the run types it covers (Caliper-run and CI-submitted), though it never names sibling tools like caliper_evals_runs_list to differentiate by task.

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 usage context: 'THE ANSWER to why did the score drop — read this, then name the criterion that slipped,' and an explicit exclusion, 'Still no polling loops; read it when the user asks.' It does not name an alternative tool to use instead when the user just wants a run list.

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 this is a non-destructive read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond that: not_found for external-eval items, transport-level step capping, and a pointer to the full record on the Caliper run page. It does not discuss auth or pagination semantics for the capped step list, so it falls short of 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?

Three sentences, all load-bearing: what it returns, when to reach for it, and the two failure/limitation caveats. It is front-loaded with the payload description. Minor redundancy between the schema's runItemId note and the description's id-vs-itemId warning costs it a point.

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 burden of describing returns — and it does, enumerating ordered steps (utterances, tool calls with arguments, tool results), final answer, status, duration and cost. Combined with the not_found and truncation caveats, 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 description coverage is 100%, so the schema already documents all four parameters, including the note that runItemId is the item's `id` rather than its dataset itemId. The description's "pass the run item's `id` (NOT `itemId`) from caliper_evals_runs_get" largely restates that schema text, adding only reinforcement and the sibling that produces the value. 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?

The description states a specific verb and resource: it returns what the flow actually DID on one run item — ordered steps, tool calls with arguments, tool results, final answer, plus status, duration and cost. This is clearly distinguishable from caliper_evals_runs_get (which yields scores/metadata) and caliper_traces_get, so an agent can pick it 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?

It gives an explicit trigger ("Read this when a low score needs explaining beyond the judge's reasoning") and explains the diagnostic value (a wrong tool call or empty result is usually the cause, and the fix differs from a prompt fix). It also names a when-not case: externally supplied outputs have no trace and return not_found.

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 safe-read profile (readOnlyHint, destructiveHint=false). The description goes well beyond them: newest-first ordering, the PENDING/RUNNING/SCORING/DONE/FAILED lifecycle, that a score exists only once DONE, and an anti-polling behavioral constraint. That is substantial behavioral context layered on top of 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?

Front-loaded with the resource and return fields, then the routing guidance. Dense but every clause carries information; the em-dash-heavy final sentence runs slightly long but nothing 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?

There is no output schema, so the description correctly enumerates the returned fields (status, score once DONE, label, timestamps, ordering) and pairs that with the delta-comparison workflow. Nothing an agent needs to call and interpret this tool 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% for both parameters, so evalId and workspace are already fully documented. The description adds only the single-eval scoping ('for one eval') and does not elaborate on the workspace/permission nuances beyond what the schema states. 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 ('Recent runs for one eval') plus scope ('newest first') and the exact fields returned (status, score, label, timestamps). An agent can immediately distinguish this from caliper_evals_get and caliper_evals_runs_get 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?

Explicitly frames itself as 'THE CHECK-BACK for caliper_evals_run', names the triggering condition ('when the user asks how the run went'), and adds a when-not rule ('don't poll in a loop; check when the user asks or when reporting'). This is exactly the when/when-not/related-tool guidance the dimension asks for.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is already partly covered; the description still adds real value by disclosing the approval flow ('May return needs_confirmation'), the ongoing credit cost of scheduled/on-publish runs, and which fields are permanently fixed after creation. It never explains what 'destructive' means here (e.g., that null clears description/schedule), leaving one gap.

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 mutable fields in the first sentence, then immutability, then confirmation/credit notes — a logical order with little waste. The parenthetical glosses on each field make it slightly long, but every clause carries actionable information.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-param mutation tool with no output schema, the description covers mutation scope, immutability of non-editable fields, the confirmation/approval round-trip, and the cost side effects of enabling schedules — everything an agent needs 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 description coverage is 100%, so the schema already documents every parameter (including 'null turns alerts off' and the timezone/HH:MM formats). The description restates a few of these (threshold semantics, runOnPublish trigger) without adding new syntax or format detail, 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?

States a specific verb (Changes/Update) plus the resource (a Caliper eval) and enumerates exactly which attributes are mutable (title, description, visibility, schedule, runOnPublish, regressionThreshold). The immutable-field callout sharpens the boundary versus caliper_evals_create.

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 rules ('Pass only what changes') and an explicit alternative with condition ('The dataset, rubric snapshot, and target are fixed at creation — create a new eval to change those'). It also instructs the agent to surface credit spend when enabling scheduled/on-publish runs.

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 safety is covered. The description adds real behavioral value beyond that: it discloses the composite/aggregated nature of the output (deltas, per-criterion decomposition, judge reasoning) and gives interpretive guidance on failure clustering.

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 'with receipts' framing, then progresses through outputs, usage trigger, and diagnostics in a logical order. Dense but each clause carries information; slightly verbose with the long colon-separated inventory, keeping it from a 5.

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-value burden, and it does so thoroughly (eval coverage, run history, per-criterion averages, deltas, judge reasoning). Combined with the 100% schema coverage on inputs, an agent has everything needed to call and interpret 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 description coverage is 100%, so flowId and workspace are already documented in the schema. The description adds no additional semantics about the parameters themselves (its 'runId' mention is about output citation, not an input). 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+resource ('how a Workbench flow is actually doing') and enumerates the exact contents of the report: eval coverage, recent runs with scores, per-criterion averages, delta vs previous run, and worst items with judge reasoning. This distinguishes it clearly from raw siblings like caliper_evals_runs_list or caliper_evals_runs_get.

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 trigger ('Use this BEFORE claiming a flow works or proposing changes') and a follow-through requirement (cite runId + scores). It also explains how to interpret worst items diagnostically. It does not name alternative sibling tools (e.g., evals_runs_list for raw run data), so it falls just 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=false, destructiveHint=false, and openWorldHint=false, so the create-and-safe profile is covered. The description adds the default scale (1-5) and the semantics of each criteria kind, but does not mention the approval/confirmation flow implied by approvalId or any workspace scoping 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 the guiding heuristic is well placed, but the middle sentence is a dash-chained dump of every check type that reproduces the schema enum verbatim. It is dense without being fully wasteful, but those enumerated values do not earn their place in the description.

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 plus the fairly rich input schema together cover the required title/criteria and their structure well. Remaining gaps (approvalId, visibility, workspace) are already documented in the schema, so the description is nearly complete for this create operation.

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%, so the schema documents most fields. The description restates the kind values (scale, pass_fail, check) and enumerates the check types, largely duplicating schema enum descriptions rather than adding syntax or constraints. Baseline 3 is appropriate for mid-level coverage where the description re-explains rather than extends.

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 (creates the scoring rubric) and pins down its domain role ('an eval's LLM judge uses'), plus the concrete shape (1-10 criteria, three kinds). It is clearly distinguishable from rubrics_get/list/update/delete 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?

Offers real guidance on how to author criteria ('about the FLOW'S JOB ... not generic quality'), which is valuable. However, it never says when to reach for this tool versus caliper_rubrics_update or how it relates to evals_create — 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 declare destructiveHint=true, and the description adds real value beyond them: existing evals retain a snapshot and keep running, nothing new can bind to the rubric, and a `needs_confirmation` response may occur (linking to the approvalId param). This is exactly the consequence-level context a destructive tool 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?

Three short, front-loaded sentences with no waste; the core action leads and the consequences and confirmation behavior follow compactly.

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, no-output-schema tool, the description covers the key behavioral facts (retention, binding block, confirmation flow). Minor omissions remain, such as explicit irreversibility wording, but nothing an agent critically needs 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 are already documented (including the approvalId/needs_confirmation linkage). The description adds nothing beyond what the schema provides for parameters, 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?

States a specific verb+resource ('Deletes a rubric'), which is unambiguous against the sibling set (rubrics_create/get/list/update). It does not explicitly differentiate itself from alternative lifecycle operations, but the operation is clear from the phrasing.

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 explains consequences of deleting but gives no guidance on when to delete versus alternatives (e.g., update vs delete), nor any prerequisites for invoking it. Usage is only implied by the verb.

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 a closed world, so the safety profile is covered. The description adds real value by describing the returned structure (criteria, judge focus, scale), which matters because there is no output schema, though it says nothing about pagination or size limits.

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 tight sentences with no filler; contents are front-loaded, followed by usage conditions and the id source. Every clause 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 read-only fetch with no output schema, the description covers return shape, usage context, and prerequisite sourcing of the required id. An agent has everything needed to select and 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 goes further by telling the agent where to source the required rubricId (rubrics_list or an eval's rubricId) and notes the read-before-update relationship. That provenance guidance is genuine added meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('One rubric with its criteria') and enumerates the payload contents (criterion name, what the judge looks for, score scale). It is cleanly distinguishable from caliper_rubrics_list and caliper_rubrics_update in the sibling set.

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

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

Explicitly gives two when-to-use conditions ('to explain a score' and 'before caliper_rubrics_update') and names the alternatives for obtaining the required id ('caliper_rubrics_list or an eval's rubricId'). 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 destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the listing is scoped to the active workspace and returns id, name, description, and criterion count, which helps an agent interpret results.

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

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

Three short sentences, each earning its place: what it returns, when to call it relative to create, and where to read criteria. The workflow-critical instruction is front-loaded.

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, but the description compensates by naming the returned fields, and the single optional parameter is fully documented. An agent has everything needed to call it and act on 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 description coverage is 100% and there is a single optional parameter, so the schema already carries the full load. The description adds no syntax or format detail about the workspace parameter beyond what the schema states.

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 (Lists) and resource (rubrics), scopes it to the active workspace, and enumerates the returned fields. It is clearly distinguishable from sibling tools like caliper_rubrics_get and caliper_rubrics_create.

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 to check here BEFORE caliper_rubrics_create and gives the reason (reuse an existing rubric id in caliper_evals_create), and routes deep reading to caliper_rubrics_get. When-to-use and alternative tool are both 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?

Goes well beyond destructiveHint=true by disclosing that criteria are replaced wholesale with fresh ids, that existing evals keep scoring against their snapshotted criteria, and that a needs_confirmation response may come back. This is meaningful behavioral context for a mutation 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?

The what-it-does clause is front-loaded and the criteria-replacement warning follows immediately. The embedded instruction to 'say so, and offer to create a new eval' is slightly meta but earns its place as routing guidance.

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 the eval-snapshot consequence, while parameters are fully documented in the schema. Only the mechanics of the needs_confirmation response 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 the baseline is 3, but the description adds real semantics the schema doesn't carry: that criteria ids are regenerated on replacement and that the eval snapshot behavior affects whether the change is safe to make.

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+field set: changes a rubric's title, description, visibility, or replaces its criteria. An agent can immediately distinguish this from caliper_rubrics_create/delete/get/list 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 for when the operation applies (changing mutable rubric fields, wholesale criteria replacement) and workflow guidance around eval snapshots, but never states explicit exclusions versus the create/delete 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 already establish readOnlyHint=true and destructiveHint=false, so safety is covered. With no output schema, the description usefully discloses the return shape (dataset, purpose, matching pick, sampling, count landed, running/stopped status), which is genuine behavioral context beyond the annotations. It omits pagination/rate-limit behavior, 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?

A single front-loaded sentence with a compact colon list of returned fields. Dense but every clause carries information; 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 read-only list tool with no output schema, the description compensates by enumerating the returned fields, and the annotations cover the safety profile while the schema covers both parameters. Nothing essential to invoking 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%, with sourceId and workspace fully documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

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 identifies the resource: datasets a source keeps appending to as conversations arrive, i.e. the source's live feeds. This is specific and distinguishable from generic dataset listing, but it never names or contrasts with siblings like caliper_source_feeds_stop or caliper_datasets_list, so the boundary must be inferred.

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 explicit when-to-use guidance, no prerequisites, and no mention of the alternative caliper_source_feeds_stop or how this differs from caliper_datasets_list. The agent must infer context from the name alone.

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, but the description adds real behavioral value beyond them: it clarifies the destruction is scoped to future additions only ('What it already added stays') and warns that the call 'May return needs_confirmation', which maps to the approvalId two-step flow. It stops short of explaining the confirmation response shape.

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

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

Three short sentences, zero filler, with the effect of the operation front-loaded before the parameter hint and the confirmation caveat. Every sentence carries distinct information.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and an approval flow, the description covers effect, scope of data retention, prerequisite id, and the possible confirmation response. It could say slightly more about how to proceed after needs_confirmation, but the approvalId parameter fills that 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 all four parameters including workspace and approvalId are already documented in the schema. The description only reinforces the feedId provenance, adding no format or constraint detail beyond what the schema states. 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 with precise scope: 'Stops a source from adding new conversations to a dataset.' The follow-up 'What it already added stays' distinguishes it from removal-style siblings like caliper_datasets_remove_item, so an agent can differentiate 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?

It supplies a precondition for invoking the tool ('Get the feedId from caliper_source_feeds_list'), which is useful routing context. However, it never states when to stop a feed versus deleting the dataset or removing items, and gives no exclusions, 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description only needs to add context — which it does: sort order ('busiest first'), the 14-day window for trace counts, and the shape of the payload. It omits pagination/limits and auth expectations, keeping it just short of 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 resource definition and packed with useful detail in two sentences. Density is high and the nested em-dash clauses ask for careful reading, but no sentence 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?

No output schema exists, so the description carries the burden of describing returns — and it does, enumerating source name, ingestion method, per-day trace counts, and top tools with shares. It stops short of mentioning result limits or paging, a minor gap for a list endpoint.

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 coverage on a single parameter, the schema already documents the workspace slug, defaults, and API-key behavior fully; the description adds nothing about parameters. 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+resource (list Caliper sources) and immediately defines what a 'source' is — an app sending traces via its own code, OpenTelemetry, or a published Workbench flow. This clearly distinguishes it from siblings like caliper_sources_over_time, caliper_source_feeds_list, and caliper_sources_to_dataset.

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 reach for it ('Start here when the user asks how their agent behaves on real traffic') and names the follow-on tool with its condition ('then caliper_sources_over_time for one source'). This is textbook routing guidance with an alternative 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 already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description usefully adds the shape of the aggregation and the meaning of latency values (p50/p95 as "answered within" bucket edges), which the annotations cannot convey. It omits any note on cost of computing 365-day windows, caching, or auth constraints beyond the 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?

Front-loaded with the resource, then the metrics, then the recommended workflow. The metric enumeration is dense and the parenthetical on p95 bucket edges is slightly awkward, but each clause carries real information about the return shape rather than 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 returns and does so thoroughly — metrics, per-tool breakdowns, share-of-traces, top documents, models — and tells the agent what to do next. Nothing essential for calling 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 sourceId, days (default 30, max 365) and workspace are already fully documented, putting the baseline at 3. The description adds no syntax or default information beyond the schema, though it does frame what the returned window represents.

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 — reading one Caliper source day by day — and enumerates exactly what is computed (traces, failures, tool calls, tokens, cost, latency percentiles, documents, models). This distinguishes it from listing tools like caliper_sources_list and from trace-level siblings such as caliper_traces_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 use case ("how often is it calling web search and is that changing") and a concrete analytic procedure (compare first/last weeks, name the day it moved), plus a follow-up route to caliper_traces_list. It does not state when NOT to use it or contrast it with a potentially overlapping analytics sibling like caliper_flow_performance.

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 a non-destructive, closed-world write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-derivable behavior: keepAdding turns the dataset into a live feed capped at 1,000 items, one-in-10/one-in-100 sampling, and that the call may return `needs_confirmation` with an approvalId follow-up. It omits any note about what happens to pre-existing dataset contents when adding, which is the one remaining gap for a mutating 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 scope, then layers purpose semantics, live-mode behavior, and the next step in a tight sequence with no filler. It is on the denser side for one paragraph, but every clause carries information an agent needs.

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 12 parameters, a 100% documented schema, and no output schema, the description covers the non-obvious flow (new vs existing dataset, live mode caps, confirmation handshake, follow-on tools) without needing to restate return shape. Minor gaps remain around workspace/token handling and interaction with existing dataset contents, both of which are partially covered in the schema itself.

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, but the description goes further by explaining what each `purpose` value actually retains (review = reply plus tool calls for rating; eval = reply becomes the expected answer; spec = questions only) and the meaning of datasetId vs newDatasetName and the sampling factor. This is real semantic value the bare enum cannot convey.

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 — saving the conversations behind a pick into a new or existing dataset — and immediately scopes it against the sibling narrowing tool caliper_traces_list, which it shares semantics with. An agent can distinguish this from caliper_datasets_add_items and caliper_datasets_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?

Explains the decision-relevant context: which purpose (review/eval/spec) fits which downstream intent, when to use a new dataset vs an existing datasetId, and explicitly names the follow-on step (caliper_evals_create or a Caliper review). It stops short of stating when not to use it, so it lands just under an explicit 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 non-read-only and non-destructive, and the description adds real substance beyond them: what gets created (user-owned, editable dataset + rubric), what is returned (both ids), and the exact permissions required (caliper:datasets:write, caliper:evals:write). Does not mention idempotency or what happens if the slug already exists.

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 tight sentences: the action and result come first, then the next step and prerequisites. Zero 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?

Covers the mutation, its outputs (both ids), the follow-up tool, and permission requirements, which is sufficient for a 3-param install tool with no output schema. Missing only edge-case behavior such as re-installing an existing slug.

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%, with the slug enum documented and sourced to caliper_starters_list, so the schema carries the burden. The description's mention of 'returns both ids' adds nothing about the workspace override or approvalId flow, so 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 (copies/installs) plus the concrete resources produced (a new dataset and a new rubric the user owns). An agent can distinguish this from caliper_starters_list (read-only listing) and caliper_datasets_create (blank dataset) 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?

Clearly frames the workflow: install a starter, then bind the returned ids via caliper_evals_create. It does not explicitly say when to choose this over caliper_datasets_create or caliper_rubrics_create, but the context is unambiguous for a starter-based workflow.

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 new framing: the items are public, the starter is a 'smoke test' and not a safety score, which materially shapes how the agent should present results. It does not discuss return format or ordering, but that is a minor gap.

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 inventory of starters is front-loaded and the guidance follows in a logical order. It runs a bit long and embeds an instruction about how to phrase the answer ('Say plainly...'), but every sentence conveys distinct, useful information rather than restating the name or 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?

There is no output schema, but the description does tell the agent what it will get back (the named starter sets with their dataset and rubric composition) and how to act on it. For a zero-parameter list tool backed by read-only annotations, this is essentially complete, with only return ordering/pagination left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema carries nothing for the description to complement. Baseline 4 applies; there is no parameter ambiguity to resolve.

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 enumerates what the tool surfaces (five named starter sets, each an original dataset paired with an anchored rubric) and distinguishes itself from the install sibling. It never uses an explicit verb like 'list', relying on the title for that, but the content is specific enough that an agent can tell it apart from caliper_datasets_list or caliper_rubrics_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?

It states the trigger ('when a user wants to check an assistant for these and has no cases yet'), names the follow-up action and its tool ('install with caliper_starters_install'), and implies the exclusion via 'has no cases yet' plus 'their own cases are where the real signal is.' That is explicit when, when-not, and alternative.

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, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: the enumeration of step types (model calls with tokens/cost, tool calls, lookups) and, most importantly, the 2,000-character truncation on long values. It omits any note on pagination, result size limits, or what happens with a stale/invalid traceId.

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 'One trace' and then the content inventory; the second and third sentences add the truncation caveat and the use case without padding. The middle enumeration is long but each item earns its place by telling the agent what to expect.

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 contents, and it does so thoroughly (steps, timing, status, truncation threshold). It is slightly incomplete on error/edge behavior for invalid ids and on whether very large traces are paginated.

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%, including the workspace override rules and where traceId/sourceId come from, so the schema does the heavy lifting. The description contributes no additional parameter meaning, 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?

The description states a specific verb+resource ('One trace: what came in, what went out') and enumerates exactly what the retrieval returns, so an agent can immediately distinguish it from the list-style sibling. It stops short of naming caliper_traces_list as the way to discover trace ids, so sibling differentiation is implicit rather than explicit.

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

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

It gives a clear use case — 'explain why one conversation went the way it did' — which tells the agent what question this tool answers. However, it offers no when-not guidance, no prerequisite chain (list first, then get), and never names an alternative 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 declare readOnlyHint and openWorldHint=false, so safety is settled. The description adds real behavioral context beyond that: newest-first ordering, 50-per-page batching, truncated Q/A text, and the fields returned (tools, time, tokens, cost, status). It doesn't state a total count or rate limits, keeping it just short of 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?

Two sentences, front-loaded with what is listed and how it is ordered, followed by filtering, paging, and the sibling handoff. Dense but every clause carries information; only the return-field enumeration is slightly list-like.

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 compensates by naming the returned fields and pagination contract, and it covers the filter and paging parameters. Nothing needed to call or interpret this tool 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 schema already documents all 7 parameters, including the workspace/token caveat and the YYYY-MM-DD pattern. The description echoes the filter set (day, tool, document, failures) without adding syntax 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?

States a specific verb and resource ('traces behind a point on a source's chart') plus ordering and page size, which distinguishes it from caliper_traces_get, the single-trace sibling. An agent knows exactly what this returns 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 narrowing dimensions (day, tool, document, failures), the paging protocol (`before` = nextBefore from last page), and explicitly routes to caliper_traces_get for a single trace. Both when-to-use and the alternative 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds value beyond that by disclosing a side effect annotations cannot express: mentioning users rings their notification bell, with an accompanying social caution. It omits permission/auth requirements for posting.

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 its two modes, then layers usage and mention etiquette compactly. Two sentences, minimal waste, though the trailing 'never mention someone who didn't ask' is advisory padding rather than invocation-critical information.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation with 43% schema coverage and no output schema, the description covers the social/mention dimension well but leaves the entity-targeting parameters and the undocumented approvalId unexplained, which an agent would need to call this reliably in all cases.

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 must compensate, and it partially does: rootId (reply target), mentionedUserIds (workspace member ids, notification behavior), and body are implied. However entityKind's 17-value enum, entityId, and especially approvalId are unexplained in both schema and description, leaving real gaps.

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 ('Posts a comment on a workspace entity') and distinguishes the two modes of operation: new thread vs. reply when rootId is given. It never names its closest siblings (comments_list, comments_resolve), so it stops just 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 concrete usage context ('leave findings where the discussion already lives') with two illustrative scenarios (eval result on a debated flow, summary on a long thread). It does not state when not to use it or point to a sibling alternative, so it lacks the explicit routing 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, so the safety profile is covered. The description adds genuinely new behavior: threads are returned open-before-resolved and include authors and timestamps, which shapes how an agent interprets output. It stops short of pagination or volume limits.

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 with the key facts front-loaded and no redundancy. The second sentence is motivational framing that carries mild value but is slightly softer than a hard routing rule.

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 read-only list tool with no output schema and a mostly documented schema, the description covers ordering, content, and the entity scoping needed to call it. Pagination/result-size behavior is the only notable 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 67%, and the schema itself handles the workspace slug nuances and the enum list. The description only says 'one workspace entity', adding little beyond the structured fields, 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 (lists) and resource (comment threads on one workspace entity), plus the ordering rule (open first, then resolved) and payload (authors, timestamps). This clearly separates it from comments_create and comments_resolve, which mutate rather than 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?

The second sentence gives a soft situational cue ('read this before weighing in on contested work'), which implies when the tool is useful. However it names no alternatives and gives no explicit when-not or prerequisite guidance, so usage remains inferred 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 destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the mutation/safety profile is covered. The description adds real behavioral context beyond that: the precondition (a reply explaining what settled the thread) and the reopen semantics. It doesn't clarify reversibility or how the state change affects existing replies, keeping it below 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?

Two tight sentences with no filler; the action and the primary precondition are front-loaded before the reopening clause. Every clause carries decision-relevant information.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a small toggle tool with no output schema, the description covers the action, the target, and the conditions well. It leaves approvalId and workspace behavior unexplained, which matters for a destructive write, but overall an agent has enough to act 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 only 25%, and the description compensates for rootId only (root comment id). 'resolved' is implied by resolve/reopen framing, but 'workspace' is documented only in the schema and 'approvalId' is explained nowhere — a notable gap for a mutation tool with an approval 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?

States a specific verb (sets resolved state) plus resource (comment thread), and covers both directions — resolve and reopen. The parenthetical 'rootId = the thread's root comment id' disambiguates the target, making it clearly distinct from comments_create/comments_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 gates the action: resolve ONLY when the human asked or the question is demonstrably settled, and reply first explaining what settled it; reopen is for new evidence. This is genuine when/when-not guidance with a required prior step.

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 (which only flag the write + destructive + closed-world profile): it discloses partial-update semantics ('omitted fields are left alone'), idempotency ('nothing duplicates'), per-item isolation ('a failed item doesn't stop the rest'), the 100-item cap, and the needs_confirmation approval flow where one approval covers the batch. This is unusually rich behavioral 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?

Dense but front-loaded — the core upsert action leads, followed by matching semantics, side effects, and confirmation behavior. Parenthetical and em-dash clauses pack multiple facts per sentence, which is efficient though slightly 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?

With no output schema, the description still explains the return shape (one result per item: created/updated with key, or failed with reason) and the confirmation path. For a batched mutation tool this covers everything an agent needs to call and interpret 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 67% and the description closes gaps: `url` is the match key mirroring a GitHub/Linear/Jira ticket, PR or doc; omitted fields are left untouched; statuses are referenced by name via compass_statuses_list. It does not explain `workspace` or `approvalId`, but those 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?

States a specific verb pair (create or update) and resource (changes), plus scope: up to 100 per call, each matched by `url`. The upsert-by-url framing is unambiguous and no sibling tool operates on changes, so an agent can select this 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 clear operational context: run again with the same urls to keep Compass in step, summarize before calling, and use compass_statuses_list for status names. It does not name a when-not-to-use case or an alternative tool, but no overlapping sibling exists, so the routing guidance is effectively complete.

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 a non-destructive write (readOnlyHint=false, destructiveHint=false), and the description adds meaningful behavioral context beyond them: no approval is required and why ('noting your own uncertainty isn't acting on the user's behalf'). It doesn't describe the returned record or any limits, but the auth/approval disclosure is genuinely additive.

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

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

Three front-loaded sentences that move from what to record, to why no gating is needed, to when to attach a subject. Dense but each sentence carries guidance; no filler or repetition of the schema.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-record write with no output schema and full schema coverage, the description supplies the missing 'why' and 'approval' context plus subject-attachment guidance. It leaves workspace selection entirely to the schema but otherwise covers what an agent needs 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 100%, so baseline is 3, and the description earns an increment by tying the fields to intent — the question, the WHY (rationale), and the resolution path (suggestedResolution) — plus the conditional semantics of subjectType/subjectId ('when it's ABOUT a specific page or person').

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 — recording an open question into the gap registry — and immediately distinguishes itself from siblings by describing the registry's role as working memory. An agent can separate it from compass_gaps_list/resolve/update 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 for when to use it ('while mapping or interviewing', 'use it liberally') and specifies the condition for attaching a subject ('when it's ABOUT a specific page or person'). It does not explicitly name the sibling tools it supersedes (gaps_update/resolve), so it stops short of full alternative 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the default-OPEN behavior and the pre-ask check habit, but says nothing about result volume, pagination, or ordering — modest added value 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?

Front-loaded with the core statement of what is listed and the default, followed by usage. The colloquial aside ('This is where you keep your head') costs a few words but does carry usage guidance, so little is wasted overall.

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 read-only list tool with four fully documented, all-optional parameters and no output schema, the description covers purpose, default filtering, and workflow integration adequately. Only pagination/return-shape behavior is left unstated, which 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 description coverage is 100%, so all four parameters (status enum, subjectId, subjectType, workspace) are already documented in the schema. The description only restates the OPEN default and the 'subject's open questions' notion, adding no syntax or semantics beyond what the schema provides. 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 ('Lists the workspace's open questions — the gap registry') and characterizes what a gap is ('what the map doesn't know yet'). This clearly distinguishes it from the sibling mutations compass_gaps_create/resolve/update without needing to open 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 concrete workflow triggers: check this before asking the user something already flagged, and use it to compose interview briefs from a subject's open questions. That is strong when-to-use guidance, though it names no explicit alternative or exclusion (e.g. vs. compass_inbox_list).

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 terminal-state safety profile is covered. The description adds genuinely new behavioral context: gaps you raised close without a card, while a person-written question requires their approval — an authorization workflow not encoded in the 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?

Three sentences, front-loaded with the core action and its two outcomes. The middle 'Keep the registry honest' sentence is mildly exhortative but carries the when-to-use guidance, so it earns its place; nothing dangles.

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 purpose, trigger conditions, status semantics, and the approval prerequisite. It does not describe the success response or reversibility, but the annotations plus 100% schema coverage leave the agent adequately equipped.

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 gapId, status, workspace, approvalId, and resolution are all documented in the schema. The description reinforces the ANSWERED-with-resolution relationship and the approvalId flow but adds little beyond what the schema already states, 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 verb (Closes/resolve) and resource (a gap = open question), and enumerates the two terminal outcomes ANSWERED and DISMISSED with their meanings. It clearly conveys the terminal-state nature, but never names the adjacent sibling compass_gaps_update, so an agent must infer the resolve-vs-update 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 says when to act — resolve gaps as their answers land, explicitly listing sources (interview, doc, or the user) and the DISMISSED case when it proves irrelevant. It lacks explicit 'instead of' routing to siblings, but the trigger conditions 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 and destructiveHint=true, so the safety profile is carried structurally. The description adds genuine context by disclosing the 'needs_confirmation' return path, but it never explains why an edit is destructive (e.g. what prior wording is overwritten) nor the approval requirement behind the destructive hint, which is the notable gap.

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

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

Three short sentences, front-loaded with purpose, then exclusions, then id provenance and the confirmation behavior. Every clause 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?

For a 6-param mutation with full schema coverage and annotations covering safety, the description covers purpose, alternative, id source, and the confirmation flow. It stops short of explaining the destructive nature of the edit or the workspace/token rules that the schema mentions, and with no output schema it only names 'needs_confirmation' rather than describing returns, but it is nearly 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 gapId, question, rationale, workspace, approvalId, and suggestedResolution are all documented in the schema. The description only reinforces the field set and the provenance of gapId, adding nothing on syntax or format beyond what the schema already provides, which is the expected baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Edits) and resource (an open question's wording, rationale, or suggested resolution), enumerating exactly which fields change. It names the sibling it is not (compass_gaps_resolve) so an agent can distinguish editing from closing 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 an explicit when-to-use ('for sharpening a vague question or fixing one you phrased badly') and an explicit when-not, routing closing to compass_gaps_resolve. It also tells the agent where the required gapId comes from (compass_gaps_list), 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the aggregate nature of the result, the state filter ('transcript in, not yet turned into pages'), and that approval cards are scoped to the caller. Pagination/limits are not mentioned, keeping it below 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 three inbox categories before the routing sentence, so the agent gets the core scope first. The colon-list and semicolon-chained next-moves sentence are dense but every clause carries information; 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 must describe what comes back, and it does: the three item categories and their pending states. Combined with annotations covering safety and the schema covering the sole parameter, an agent has enough 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 description coverage is 100% and there is a single optional workspace parameter, so the schema fully documents it. The description adds nothing about the workspace parameter (e.g., how it affects which inbox items appear), 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?

States a specific verb (list) and a precisely scoped resource (the Compass Inbox) and enumerates the three categories it aggregates: finished interviews awaiting review, AI-proposed opportunities awaiting accept/dismiss, and the caller's pending approval cards. This distinguishes it from the narrower siblings compass_interviews_list and compass_opportunities_list without the agent needing to open 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 positions itself as 'THE place to answer what needs me?' and gives concrete next moves that route to compass_interviews_get/compass_pages_create and compass_opportunities_accept/delete. It lacks an explicit when-not (e.g., pointing to compass_opportunities_list for a full unfiltered list), so it stops short of full alternative 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?

Goes well beyond the annotations: discloses the approval-card preview of subject+message before sending, the email is sent as the requesting user (replies route to them), a hard limit of one reminder, and that completion arrives as a notification rather than a polled response. 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 action, then packs voice, approval, limit, and completion into tight clauses with no filler. It is dense with several distinct concerns in one paragraph, but each 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?

No output schema exists, and the description compensates by explaining how the result surfaces (notification with draft-page counts, don't poll) plus the confirmation flow and send limits. An agent has everything needed to invoke and follow through 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 field descriptions already carry the load (baseline 3). The description adds authoring guidance beyond the schema — 'short, human, says why THEIR knowledge matters and that it takes ~15 minutes' — which shapes how `message` and `subject` should be written.

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.' The word 'existing' distinguishes it from compass_interviews_create, and the framing detail (from the requesting user) further narrows its purpose. An agent can place it without opening any sibling 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?

Says to use it for existing interviews and gives clear operational rules — invite plus ONE reminder, the third ask is the user's conversation, and don't poll. It implies but never explicitly names the sibling alternatives (create vs invite vs revoke), 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 declare openWorldHint=true and readOnlyHint=false; the description adds real context on top of that — the invite is a no-account guest link, the transcript returns as reviewable draft pages, and the call may return needs_confirmation requiring a user pause. It does not cover auth or rate-limit behavior, but the confirmation and side-effect profile is well disclosed.

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

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

Front-loaded with the core definition, then the usage rule, then the closing procedure. Dense but nearly every clause carries information; the final sentence is a slightly compressed run-on covering needs_confirmation and the user hand-off, but it is 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?

For a 6-param tool with no output schema, the description covers the important return behavior (needs_confirmation pause) and the downstream outcome (draft pages), and pairs naturally with approvalId in the schema. Enough for an agent to invoke and handle the response 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?

Even though schema coverage is 100% (baseline 3), the description adds guidance the schema lacks: focusPrompt should name SPECIFIC gaps and cite the eval run id, and interviewee should be the workflow owner when the map knows one. This meaningfully shapes how an agent fills the parameters rather than restating them.

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 ('mints a stakeholder-interview invite') and describes the concrete artifact produced: a no-account guest link, an interviewer agent briefed by focusPrompt, and a transcript flowing back as draft pages. It is clearly distinguishable from sibling compass_interview_invite, which is referenced as the send step rather than the mint step.

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 names when to use this over the obvious alternative: when caliper_flow_performance shows failures clustered on missing company facts, 'the fix is usually not a prompt edit — it's asking the human who actually knows.' It also prescribes the operational sequence (name gaps with eval run id, pick the workflow owner, hand over the link) and the needs_confirmation handling.

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 closed-world scope, so the safety profile is covered. The description adds genuinely useful behavioral context with no output schema: what the payload contains (metadata plus the actual transcript) and that downstream typing/splitting rules live in the compass skill.

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

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

Three short sentences, front-loaded with what the tool returns before the usage advice. The clause about the compass skill's typing/splitting rules is slightly tangential but still earns its place by explaining why the transcript matters.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource read with full schema coverage, covered annotations and no output schema, the description supplies what an agent needs: the return content, the id source, and the workflow context. It does not address failure modes (unknown id, missing workspace) but little more is required here.

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 would be 3. The description goes slightly beyond the schema by naming compass_inbox_list as an additional source of interviewId, which the schema's own description does not mention. It says nothing about the workspace parameter, so this is a modest lift, not a full one.

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 and resource: fetch one interview in full, including metadata and transcript. It is immediately distinguishable from compass_interviews_list (plural enumeration) and from the create/revoke siblings that mutate interview state.

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?

States the trigger condition explicitly ('read this before summarizing an interview or drafting pages from it') and tells the agent where the required id comes from (compass_interviews_list or compass_inbox_list). That is concrete routing guidance rather than implied usage.

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 real behavioral context beyond that: ordering (newest first), the status lifecycle values, and the fact that the invite URL is only present while the link is live. It does not mention pagination or result-size limits, which is the one remaining gap.

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 scope and ordering, then the returned-field inventory, then the usage trigger and the sibling pointer. The informal aside ('interview fatigue is real') is short and justifies the routing guidance rather than 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 enumerating the returned fields and their semantics. Combined with annotations covering the read-only/non-destructive nature and the explicit pointer to the detail tool, 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% and the single workspace parameter is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the workspace scoping or how default-workspace tokens behave, leaving all parameter meaning 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 and resource ('Every stakeholder interview in the workspace, newest first') and enumerates exactly what each record contains — invitee, status enum, focus, message count, documentPageId, invite URL. It is immediately distinguishable from compass_interviews_get, which it explicitly routes to for full detail.

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 ('Check this before inviting someone again') plus a concrete user question it answers ('who have we already asked?'), and names the alternative tool (compass_interviews_get) with the condition that selects it. 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?

Beyond the destructiveHint=true/readOnlyHint=false annotations, the description discloses idempotency, the exact user-visible consequence of revocation, and the `needs_confirmation` approval flow. These are meaningful behavioral traits an agent could not infer from the 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?

Three short sentences, front-loaded with the action and effect before usage triggers and edge behaviors. No filler; every clause adds information.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive single-object mutation with no output schema, the description covers effect, idempotency, id provenance, and the confirmation follow-up path. 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 interviewId, workspace, and approvalId are already documented. The description only restates the interviewId source already present in the schema, so with the schema carrying the load 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 specific verb and resource ('Kills an interview's invite link') plus the concrete effect ('the guest's next visit sees that the link is no longer active'). This clearly separates it from the sibling compass_interview_invite, which creates invites rather than revoking them.

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 trigger conditions: wrong recipient, changed mind, or leaked link. It covers when to use but does not name a contrasting alternative or state when-not to use (e.g., a different tool for regenerating vs. fully revoking).

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 safe read (readOnlyHint=true, destructiveHint=false), and the description adds substantial extra behavior: the ranking order (owns > involved_in > weaker edges), fatigue-avoidance skip logic for recent interviewees, and the empty-result recovery path. This is well beyond 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?

Front-loaded with the core action, then ranking order, then empty-result handling, then the sibling pointer. Dense but each sentence carries actionable information; minor length from parentheticals keeps it just short of ideal.

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 still explains what each target carries (contact email, role, latest interview), so an agent knows what it gets back. It also covers the failure mode, making it complete for a 2-param 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% and the schema already documents pageId and workspace semantics in detail. The description adds no syntax or format detail beyond 'a page', 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?

States a specific verb (ranks) and resource (PEOPLE who know about a page), with explicit scope and an ordered edge taxonomy. It is clearly distinguishable from siblings like compass_pages_get or compass_interviews_create.

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 'Use before compass_interviews_create to pick the interviewee', naming the sibling and the sequencing. It also prescribes what to do on an empty result (ask the user, create PERSON + owns link), covering the when and the when-not.

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 the basic safety profile (not read-only, not destructive, closed-world). The description adds real behavioral traits beyond that: idempotency keyed on (from, to, kind), the returned-existing-edge behavior, and the needs_confirmation → user approval → re-call with approvalId loop.

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 sentence one, followed by direction semantics, then idempotency, then the confirmation protocol — a deliberate and dense ordering with no filler sentences.

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 with no output schema, the description covers the create semantics, idempotency, and the approval round-trip. It omits error/failure behavior and permission requirements, but the schema already carries workspace/auth and provenance details.

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 goes further by enumerating canonical direction pairs for the `kind` parameter — semantics the schema's circular 'Edge type, in canonical direction' text does not supply. The approvalId and workspace behavior 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?

First sentence states a specific verb and resource — creates a typed, directed edge between two pages — plus a concrete metaphor for its role in the knowledge graph. It is clearly distinguishable from siblings like compass_links_update and compass_links_delete.

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 substantive when-to-use guidance via the canonical direction list (PERSON owns WORKFLOW, relates_to as fallback), which tells the agent how to pick the right invocation. It does not explicitly name when to prefer links_update over create, but the idempotency note covers the main overlap case.

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 genuinely non-obvious behavior: deleting is reversible ('Re-creating the same edge later revives it') and the call may return needs_confirmation, implying a gated approval flow. That is real context beyond the structured fields; it stops short of stating permission requirements or exactly what the confirmation response contains.

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

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

Three short sentences: the destructive scope first, the usage trigger second, the reversibility/confirmation caveat last. No filler, and the most decision-relevant fact (edges only, pages stay) is front-loaded.

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 flag the needs_confirmation outcome and its approval follow-up. Coverage is good for a single-edge delete; only details like idempotency on a stale linkId 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% — linkId sourcing, workspace rules and the approvalId flow are all documented in the schema. The description only echoes the linkId provenance already stated in the schema, so this is the baseline case where 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 ('Deletes one edge from the graph') and immediately scopes it against the obvious confusion — the pages themselves survive, which separates it from compass_pages_delete. An agent can distinguish it from compass_links_create/update and the page tools 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 an explicit when-to-use rationale with concrete triggers ('the system isn't used by that workflow, the person left the team') and points to compass_page_links_list as the source of ids. It does not name the sibling alternative (e.g., compass_links_update) or state when not to delete, 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 only declare the mutation/destructive profile; the description adds real behavioral content beyond that — the conflict failure mode when an identical reading already exists, the routing advice to delete instead, and the possibility of a 'needs_confirmation' response. It stops short of stating reversibility or permission requirements for a destructive edit.

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 purpose, then usage, then failure behavior in roughly four tight sentences with no filler. The ALL-CAPS emphasis and quoted example are slightly chatty but earn their space by disambiguating the correction use case.

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 returns and does mention the 'needs_confirmation' response and conflict failure, which are the two non-obvious outcomes. It is complete enough to call correctly, though it omits the ordinary success return shape and any permission prerequisites for this destructive edit.

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 five parameters including the kind enum and the 500-char note limit are already documented in the schema. The description's gloss of `kind` as 'how the two relate' adds only marginal meaning beyond the schema's 'New edge type, in canonical direction.'

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 existing edge between two pages') and enumerates the two mutable fields, kind and note. This cleanly separates it from compass_links_create and compass_links_delete without the agent needing to open 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 an explicit triggering scenario ('Use to CORRECT a connection typed wrongly') with a concrete example, names the prerequisite source for link ids (compass_page_links_list), and routes the agent to an alternative ('delete this one instead') when the new reading already exists.

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 establish that this is a safe read; the description goes well beyond them by disclosing what the non-image payload contains (page-type counts, link count, unconnected-page count, mapUrl) and, critically, an anti-pattern instruction: do NOT embed the image in a reply because the chat cannot render it. That is exactly the kind of behavioral guidance structured fields cannot carry.

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 usage trigger is front-loaded and the closing instructions are tight, but the long enumeration of every page type and its symbol, plus the full colour-ring legend, is bulky and would be needed only when interpreting a specific image. It earns most of its length but not all of it.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a single trivial parameter, the description carries the full burden and does so: it explains what the image depicts, what the text block returns, and how the agent should present the result. Nothing needed to call or act on this tool 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% with a single optional 'workspace' parameter, so the schema already documents the token/default-workspace semantics. The description adds nothing about the parameter, 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 states a specific verb+resource ('renders the workspace's visual map to an image and returns it') and the vivid type-to-shape mapping makes clear exactly what the artifact contains. No sibling tool renders a map, so it is trivially distinguishable from compass_pages_list, compass_page_links_list, and the rest.

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 an explicit when-to-use trigger ('when the user asks about the shape of their map, where the problems are, what connects to what, or anything spatial') and pairs it with presentation guidance ('link mapUrl... and describe what you saw'). The routing condition is unambiguous rather than inferred.

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 readOnly=false, so mutation semantics are covered. The description adds genuinely useful behavior beyond that: the not_proposed failure condition, the needs_confirmation round-trip with approvalId, and the status defaulting to NEW. It stops short of explaining what 'promote' does to the source proposal or any irreversibility, so not a 5.

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

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

Dense but front-loaded: the core action and sibling distinction lead, followed by parameter behavior, failure mode, and the confirmation caveat. Every sentence carries information, though the several clauses make it slightly heavy for a single-paragraph description.

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, yet the description covers the return-signal territory an agent needs (not_proposed failure, needs_confirmation handling, where ids originate). For a mutation tool with full annotation coverage, nothing essential 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. The description nonetheless adds real meaning: status chooses the lane in the same step with a stated default, and approvalId is tied to the two-step needs_confirmation flow (omit on first call). This goes beyond the schema's field-level 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 (promotes an AI-proposed opportunity into the workspace pipeline) and explicitly differentiates from compass_opportunities_set_status, which 'does NOT do this.' An agent can distinguish it from all 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?

Explicitly names the source of proposals (compass_opportunities_propose / opportunity scout), the alternative that won't work (set_status), and where ids come from (compass_inbox_list / compass_opportunities_list). When-to-use is fully covered with the counter-case named.

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