ZeroWidth

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

Annotations declare a non-read-only, non-destructive write. The description adds real value beyond them: appends are additive, existing items and their ratings are untouched, and the accepted item shapes ('same four shapes as caliper_datasets_create') are named. It doesn't state auth/approval behavior, though the schema's approvalId covers that.

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

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

Three short sentences with the core action and its key routing decision front-loaded. Every clause earns its place — the shape reference and the non-destructiveness note both carry 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?

For an append mutation with 4 params and no output schema, the definition covers action, alternatives, additivity, and item shapes. The only gap is what a successful call returns (e.g., new item ids), which the absence of an output schema leaves 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?

Schema description coverage is 100%, so the item-shape fields, datasetId, workspace and approvalId are already fully documented in structured data. The description's 'same four shapes' hint adds orientation but no per-parameter syntax or constraints beyond the schema. Baseline 3 applies.

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

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

States a precise verb+resource ('appends items to an existing dataset') and immediately distinguishes it from the parallel-dataset path (caliper_datasets_create). An agent can tell it apart from siblings like generate_items or update_item 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 a clear when-to-use rationale ('grow coverage — new edge cases, scenarios from a completed interview') and an implicit alternative via 'instead of creating a parallel dataset'. It does not, however, address other plausible routes such as caliper_datasets_generate_items or update_item, so the routing is not fully exhaustive.

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=false, destructive=false, openWorld=false, so the safety profile is covered; the description adds real behavioral context beyond them, notably that in CHAT items every assistant message is fixed and the flow writes only the next reply, and that SIMULATED items are Caliper-run evals only. It omits the approval/confirmation flow implied by the approvalId parameter.

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 purpose well, but the body is a dense wall of text heavy with capitalized emphasis and restatement of the shape semantics already present in the schema descriptions. Much of the length is informative yet redundant, so it is not tightly economical.

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 never says what a successful create returns (e.g., a dataset id needed for follow-up calls) nor explains the approvalId/needs_confirmation workflow. It is thorough on item shapes but leaves operational gaps for a mutation tool that seeds a downstream workflow.

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 beyond the per-field schema blurbs by explaining how parameters interrelate for each shape (messages built up by depth, turns answered one at a time with prior replies in front, disposition presets versus free text). That conceptual framing adds genuine value over the schema alone.

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

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

States a specific verb and resource ('Creates a dataset of test items') and frames it as 'THE FIRST STEP of setting up evaluation for a flow', which positions it ahead of add_items/generate siblings. It never names an alternative explicitly, so the distinction from caliper_datasets_add_items or caliper_datasets_generate_items is only implied.

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 on when each item shape applies ('Use sequences and simulated items for the slow attacks and for real customers with real needs') and where to source inputs (Compass pages the flow was built from). It stops short of stating when to use this tool versus the generate/generate_items alternatives or when not to use it at all.

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

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

Annotations already declare destructiveHint=true, so the safety profile is known; the description adds real value by naming the cascade (evals become non-runnable, binding shows datasetOk: false, reviews/specs lose their source) and warning that a needs_confirmation response is possible. It stops short of saying whether deletion is reversible or what the response payload looks like.

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

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

Two tight sentences, front-loading the action and then the side effects, with the prerequisite check and confirmation caveat in the second half. No filler, though the em-dash clause packs several consequences into one dense sentence.

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 only three schema-documented params, the description supplies what matters for a destructive tool: cascading effects, a required verification step against a sibling tool, and the possibility of a confirmation round-trip. Reversibility and return shape remain unstated, but those are the only meaningful gaps.

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

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

Schema coverage is 100%, so all three parameters (datasetId, workspace, approvalId) are already documented in the schema. The description only alludes to approvalId via 'needs_confirmation' and adds no syntax or format detail beyond that. Baseline 3 applies when the schema carries the parameter burden.

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 a dataset') and immediately scopes the blast radius to dependent evals and reviews/specs. An agent can distinguish it from caliper_datasets_create, update, and remove_item without opening any schema.

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

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

Gives an explicit pre-flight workflow: check caliper_evals_list for referencing evals and surface that before proposing the deletion. It names the alternative tool to consult but offers no when-not-to-use condition (e.g. prefer update/naming for trivial migrations).

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 readOnly/destructive/openWorld; the description adds the crucial cost trait ('SPENDS workspace inference credit (one generator call)'), the approval-gate behavior ('expect needs_confirmation'), and the required follow-up read via caliper_datasets_get. These are non-obvious side effects an agent must communicate to the user.

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 credit warning, and every clause carries information. It is fairly dense across multiple em-dash clauses, so a small amount of tightening is possible, but nothing reads as 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 13-param, no-output-schema mutation with spend, the description covers what it returns ('dataset summary'), the follow-up read, cost, and approval flow — the info an agent needs. Nothing material is missing given the schema carries all parameter detail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the flowId/description contract (description 'stands alone when there's no flow'), the generator's behavior of reading the flow's prompt/mode/schema, and the default shape. It does not add much for the enum params 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+resource ('Creates a NEW dataset of model-written items') and immediately distinguishes the output variants (Q&A, scripted sequences, simulated people via `shape`). It also names the sibling it is not (caliper_datasets_create) so an agent can route correctly 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?

Explicit when-to-use ('when the user wants test cases fast and has none') and when-not ('prefer caliper_datasets_create with hand-written items when real scenarios are already in hand — Compass pages, a transcript'). It further flags the approval-gate path and the expected needs_confirmation response, leaving little 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 annotations (readOnlyHint=false, destructiveHint=false), it discloses the cost model ('SPENDS workspace inference credit'), the approval gate and the requirement to tell the user, and the safety guarantee that existing items and ratings are untouched. These are material behaviors an agent cannot infer from structured fields.

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

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

Three dense sentences, front-loaded with the append-to-existing-dataset behavior, then routing, then cost. Every clause carries information, though the credit/approval sentence is slightly packed. No filler or repetition.

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

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

For a ten-parameter mutation tool with no output schema, the description covers behavior, sibling routing, cost, and non-destructiveness. It does not explain what a successful response returns or how approvalId round-trips, but the schema covers the confirmation flow and no output schema exists to explain.

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

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

Schema coverage is 100%, so the schema already documents all ten parameters and their enums; the baseline is 3. The description adds only the inheritance rule ('output shape matches theirs unless overridden') and the few-shot style hint, which lightly supplements rather than meaningfully extends 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') plus the mechanism (existing items are the few-shot examples). It explicitly distinguishes itself from the sibling caliper_datasets_add_items, so an agent can route without opening either schema.

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

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

Gives explicit trigger conditions ('more like these', 'add edge cases') and names the alternative with the condition that selects it ('write them by hand with caliper_datasets_add_items when the scenarios are known'). When-to-use and when-not are both 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=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: pagination semantics (limit/offset/total) and, importantly, that long fields are truncated at ~800 characters with a marker, which an agent would otherwise not expect from a read 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?

Three dense sentences, all front-loaded and each carrying distinct information (ordering rationale, pagination, truncation, id source). Packed but not padded; only minor cost is that several facts are compressed into the first sentence.

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 the returned shape: a page of items, the `total` count, and truncation of long fields. Combined with the schema's full parameter coverage, an agent has everything needed to call 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 limit, offset, datasetId and the workspace quirk are already documented at 100% fidelity in the schema. The description restates limit's default and offset semantics without adding format or edge-case detail, 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?

States a specific verb (read) and resource (one Caliper dataset with a page of its items), immediately distinguishing it from caliper_datasets_list, which returns datasets rather than items. An agent can pick between the two without opening either schema.

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

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

Explicit sequencing guidance: read this BEFORE editing items because caliper_datasets_update_item needs the item id, and before extending coverage to avoid adding duplicate cases. It also names caliper_datasets_list as the source of the required datasetId, which is the only prerequisite.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real behavioral value by declaring the exact return shape (id, name, item count) and the negative constraint that items are excluded, though it says nothing about pagination or result limits for a list operation.

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 with zero filler; scope comes first and the return-content constraint immediately follows. 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 a simple one-optional-parameter read tool, annotations covering safety, and a description that explains the return contents in lieu of an output schema, an agent has enough to call this correctly. Pagination/result-limit behavior for a list endpoint is the only notable omission.

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

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

The single 'workspace' parameter has 100% schema description coverage, including the personal-token vs workspace-API-key semantics, so the schema carries the burden. The description adds no parameter-level detail beyond the phrase 'active workspace', making the baseline 3 appropriate.

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

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

States a specific verb (Lists) and resource (datasets) scoped to the active workspace, and explicitly declares the return granularity ('summaries... items are not included'). That last clause implicitly separates it from caliper_datasets_get, but no sibling is named, so it stops short of full differentiation.

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 for enumerating datasets is clearly implied by 'Lists datasets in the active workspace', but there is no explicit when-to-use guidance and no routing to alternatives such as caliper_datasets_get for full item content or caliper_datasets_create for adding a dataset.

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 explaining the exact blast radius: ratings and run results keyed to the item are orphaned, kept in history but removed from the dataset. It also discloses the minimum-item constraint and the possibility of a needs_confirmation response, which the annotations do not 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 core action, then consequences, then the constraint and confirmation behavior. No filler; every sentence carries signal.

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 key risks (orphaned ratings/run results), the hard constraint (minimum one item), and the confirmation pathway. It could note permission or reversibility details, but the orphan/history distinction already answers the most important agent question.

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 token rules and approvalId) are already documented in the schema. The description's mention of 'May return needs_confirmation' lightly connects to the approvalId flow but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Drops one item') and scopes it to a single item, which sets it apart from bulk siblings like caliper_datasets_add_items or whole-dataset operations like caliper_datasets_delete. It never names a sibling explicitly, but the singular scope is clear enough for an agent to disambiguate.

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 precondition 'A dataset must keep at least one item' is a genuine usage constraint, but the description never states when to prefer this over caliper_datasets_update_item or how it interacts with the removal of multiple items. Usage is implied rather than guided.

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 give the generic readOnly=false / destructive=true profile; the description adds real behavioral context by disclosing the partial-update contract (untouched fields stay as-is) and the two-phase confirmation flow via 'May return `needs_confirmation`'. It stops short of stating permission requirements, but the schema's workspace field covers the auth nuance.

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 load-bearing: scope, partial-update rule plus sibling routing, and the confirmation caveat. No filler and the core mutation 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?

For a mutation tool with annotations covering the safety profile and no output schema, the definition covers scope, update semantics, and the confirmation round-trip. Minor gaps remain around visibility-change side effects (the 'granted afterwards' detail lives only in the schema).

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

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

Schema coverage is 100%, so baseline is 3, but the description contributes the patch semantics ('pass only what changes') that the schema does not express — the schema documents field meanings, not that omitted fields are preserved. That is a genuine addition rather than a restatement.

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 ('Changes a dataset's title, description, or visibility') and immediately scopes it away from item-level operations by naming the siblings that handle those (add_items / update_item / remove_item). An agent can distinguish it from caliper_datasets_update_item without opening either schema.

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

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

Explicitly instructs to 'pass only what changes; items are untouched' and routes item-related work to three named alternatives. The when-not condition is stated rather than 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?

Adds rich context beyond the annotations: the id is preserved so ratings and eval results stay attached, the item KIND is immutable across four shapes, certain item types are not editable, and it may return `needs_confirmation` (a real approval flow, tied to the approvalId param). This is materially more than destructiveHint alone conveys.

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

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

Four tight sentences, front-loaded with the core rewrite action, then preservation behavior, then constraints, then the confirmation signal. No filler and nothing redundant with structured fields.

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-item mutation with a fully described nested schema and no output schema, the description covers what changes, what is preserved, what is forbidden, and the confirmation flow. 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, but the description adds meaning: the `item` must be the same shape/kind read back, and the needs_confirmation response explains when to supply approvalId. That ties two parameters to concrete behavior the schema does not.

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 — "Rewrites one item's content" — and immediately distinguishes itself from sibling caliper_datasets_update by scoping to a single item while keeping its id. An agent can tell it apart from add_items/remove_item/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 operational context: read the item first from caliper_datasets_get and pass the same shape, plus two explicit exclusions (raw items and chat items with tool calls can't be edited here). It stops short of naming which sibling to use for the excluded cases, so it's clear but not fully 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 it a non-read-only, non-destructive write. The description adds real behavioral context beyond that: on an external eval the agent must return the eval id and instruct the user to mint a ci_evals API key in workspace settings because keys cannot be created here — a genuine auth prerequisite. It also explains that 'published' resolves the latest revision at run time unless pinned.

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

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

Front-loads the core purpose and the two target modes, and the em-dash setup framing is efficient. It is dense but every clause (external key handoff, flowStage semantics, rubric reuse) contributes, though it runs long enough that a couple of clauses could be trimmed.

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-parameter mutation with no output schema, the description covers the decisive paths: target selection, stage semantics, and the external-key follow-up. It stops short of describing the approvalId confirmation flow or visibility defaults at the level the schema does, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 92%, so the schema carries most parameter meaning and the baseline would be 3. The description still adds interpretation beyond the schema: flowStage draft vs published timing, the scenarioId-at-create vs run-time override relationship, and rubric reuse. This is a modest but real lift over an already well-described 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 precise verb+resource ('binds a dataset + rubric to something under test as a repeatable eval') and positions it as a setup step before scoring, which cleanly distinguishes it from caliper_evals_run and caliper_evals_list. It also names the two supported targets, so the agent knows the shape of what it creates.

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 branches on target ('workbench_flow' with flowId vs 'external' via public API/CI), states flowStage 'draft' for pre-publish iteration vs 'published' default, and routes to caliper_rubrics_list when a rubric already exists. When/when-not and alternatives are all present.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the schedule is stopped, run history survives but becomes unreachable, and the call may return needs_confirmation, signalling a two-step approval flow. It stops short of stating irreversibility explicitly.

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

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

Three tight sentences, front-loaded with the primary action and immediate side effect, then the data-retention caveat, then the response nuance. No filler.

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

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

For a destructive tool with no output schema, the description covers the schedule stop, the retention behavior, and the confirmation response. It could still note irreversibility or what happens to runs and references after deletion, but nothing essential for invoking it 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 evalId, workspace, and approvalId are already documented in the schema. The description only hints at the approvalId flow via 'needs_confirmation' and adds no formatting or sourcing detail beyond the schema. 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 (Deletes) and resource (an eval), plus the side effect on its schedule, which cleanly separates it from the sibling delete tools for datasets, rubrics, and flows. An agent can identify the target entity 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?

Usage is implied by the name and the destructive annotation, but the description never says when to delete versus archive or update, nor does it name any alternative tool. The only routing signal is the implicit confirmation flow referenced by 'needs_confirmation'.

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. The description goes beyond annotations by decoding the 'binding' health field and warning that false values mean a run would fail at resolution — actionable behavioral context you can't get from the schema. It does not describe rate limits or pagination, but for a bounded single-record read that is acceptable.

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?

Single dense sentence plus a short provenance sentence. The field list is long but each item is informative; no filler. Slightly front-loaded awkwardly because the opening 'One eval:' is terse before the payload, but overall efficient.

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, 2-parameter tool with no output schema, the description must convey what comes back — and it does enumerate the returned fields (target, dataset/rubric ids, criteria snapshot, schedule, run counts, latest score, binding health). It omits error/not-found behavior and pagination, but covers the essentials an agent needs to interpret 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%, so the schema already documents evalId and workspace. The description adds sourcing guidance for evalId (from caliper_evals_list or caliper_flow_performance) but no syntax or format details beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.

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 opens with a specific verb+resource ('One eval') and enumerates exactly what a single eval record contains: target (workbench flow + stage or external), dataset and rubric ids, rubric criteria snapshot, schedule settings, run counts, latest score, and binding health. This distinguishes it clearly from siblings like caliper_evals_list (list) and caliper_evals_run (execution).

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 tells the agent where to get the evalId (caliper_evals_list or caliper_flow_performance) and prescribes an action ('say so before proposing caliper_evals_run') when binding health is broken. It doesn't explicitly exclude any nearby tool, but the context is strong enough that an agent knows this is a single-item read.

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 that results are scoped to the active workspace and include target config, but says nothing about pagination, result limits, or empty-list 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?

Two sentences, no filler, and the most decision-relevant information (what is listed, what it contains) is front-loaded before the routing hint.

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 one-optional-parameter read-only list tool with no output schema, the description covers what is returned and why to call it. Minor gap: no indication of how many evals are returned or whether listing is 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 coverage is 100% and the single workspace parameter is fully documented in the schema, so baseline is 3. The phrase 'active workspace' loosely reinforces the workspace-scoping behavior but adds no syntax or override detail beyond the schema.

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

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

States a specific verb (lists) and resource (evals) with scope (active workspace) and even previews the payload (target config: Workbench flow, dataset/rubric). This makes it distinguishable from siblings like caliper_evals_get without opening either schema.

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

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

Explicitly names a downstream use case ('Use to find the evalId for caliper_evals_run'), which tells the agent when this tool is the right entry point. It stops short of naming an alternative (e.g. caliper_evals_get) or stating when not to use it, 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?

Goes well beyond the annotations: discloses async/long-running behavior with automatic callback into the same conversation, cost against workspace LLM budget, and the approval gate that may return `needs_confirmation`. This is exactly the kind of behavioral context annotations cannot convey, and it is consistent with readOnlyHint=false / destructiveHint=false.

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 pipeline, then workflow role, then async/cost/approval caveats — every sentence is load-bearing. It is dense and relies on emphasis formatting, but there is no redundancy.

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

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

For a mutating, asynchronous, cost-incurring tool with no output schema, the description covers what the agent cannot see elsewhere: return behavior (scores and delta, or a needs_confirmation envelope), the approval path, and follow-up expectations. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (label, evalId, workspace, approvalId, scenarioId) with examples. The description adds only indirect framing — the approvalId is implied by 'approval gate' — but no syntax or format detail beyond the schema. 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 ('Queues a new run of an eval') and even describes the internal pipeline — inference over the dataset, then LLM-judge scoring. This clearly distinguishes it from siblings like caliper_evals_runs_get, caliper_evals_runs_cancel, and caliper_evals_runs_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 positions the tool as 'THE VERIFY STEP of the improvement loop' and names the triggering precursor (after an approved workbench_flows_edit_text), plus the goal (report score delta vs previous run). It also gives concrete do/don't guidance for the async case: tell the user it's queued and follow up, never poll. 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?

Goes well beyond the destructiveHint/readOnlyHint annotations: the queue halts at once, an in-flight item runs to its own timeout, the run settles as FAILED with a 'cancelled' reason, completed items are retained, and finished runs return run_not_live. It also flags the possible needs_confirmation response, which no annotation conveys.

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

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

Four compact sentences, each carrying distinct information (state scope, motivation, queue behavior, terminal outcome). Well front-loaded, though several clauses are tightly packed.

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 terminal state (FAILED/cancelled), retention of completed items, and the two notable return codes (run_not_live, needs_confirmation). An agent has everything needed to call it correctly and anticipate 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 runId, evalId, workspace, and approvalId are already documented. The description lightly connects to approvalId via 'May return needs_confirmation' but adds no format or sourcing detail 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 (stops) and resource (an eval run), and scopes it precisely to runs in PENDING / RUNNING / SCORING. It is clearly distinguishable from siblings like caliper_evals_runs_get or caliper_evals_runs_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 explicit when-to-use context ('spending more than expected or was started by mistake') and the precondition that the run must still be live. It does not name an alternative tool, but no competing cancel tool exists in this namespace, so the guidance is functionally 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 cover the safety profile (readOnly, non-destructive, closed-world), yet the description adds real behavior: the default returns only the ten lowest-scoring items, works for both Caliper-run and CI-submitted runs (triggeredBy 'ci'), and the no-polling rule. This goes meaningfully beyond what the annotations declare.

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 shape before the motivational framing, and each sentence carries information. The emphatic 'THE ANSWER' phrasing is slightly promotional but not wasteful.

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

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

No output schema exists, and the description fully compensates by describing the returned fields (status, score, per-criterion scores, judge reasoning) and the item-selection modes. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the items enum and limit default. The description reinforces the items default ('by default the ten lowest-scoring items') but adds no syntax or format detail beyond the schema, 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 (read/get) and resource (one eval run) and enumerates the payload: status, overall score, per-criterion item scores, judge reasoning. An agent can distinguish it from caliper_evals_runs_list (listing) 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 explicit triggering context ('THE ANSWER to why did the score drop', 'read it when the user asks') and a when-not constraint ('Still no polling loops'). It does not name a sibling alternative like caliper_evals_runs_list for the opposite case, 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 already cover the read-only safety profile, but the description adds genuinely non-obvious behavior: external-eval items have no trace and return not_found, and steps are truncated for transport while the Caliper run page holds the full record. These caveats go beyond what readOnlyHint/destructiveHint/openWorldHint 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 returns, then the when-to-use trigger, then the parameter pitfall, then edge-case caveats. No filler sentences; each one carries distinct 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 no output schema, the description carries the full burden of describing the return shape (ordered steps, tool calls and arguments, tool results, final answer, status, duration, cost) and failure modes (not_found for external items, truncated steps). Nothing needed to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by stressing that `runItemId` must be the run item's `id` and NOT its `itemId`, a classic source of wrong-argument failures. The workspace parameter's default/override semantics are left to the schema, but the critical gotcha is surfaced.

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 — reads the execution trace (every step, tool call, arguments, tool result, final answer, plus status/duration/cost) for one run item. It is clearly distinguishable from caliper_evals_runs_get, which is cited as the source of the id rather than a competitor for this data.

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 — 'read this when a low score needs explaining beyond the judge's reasoning' — with the diagnostic rationale (wrong tool call or empty tool result). It also tells the agent where to obtain the required id (from caliper_evals_runs_get), 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 readOnly/no-destructive, so the safety bar is covered. Beyond that the description adds real behavior: newest-first ordering, that a score only appears once the run is DONE, and an anti-polling operating constraint. It does not disclose result limits or pagination, which 'Recent runs' hints at but never defines.

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 and returned fields are front-loaded, with behavioral guidance following. The capitalized 'THE CHECK-BACK' phrase for emphasis is slightly informal, but every sentence carries usable information and none 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 list tool with full annotation coverage but no output schema, the description compensates by describing the returned fields (status, score, label, timestamps) and their lifecycle. An agent has everything needed to call it and interpret the result 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 both evalId and workspace are already documented in the schema. The description's 'for one eval' aligns with evalId but adds no format, scope, or defaulting detail beyond what the schema provides. Baseline 3 is correct.

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

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

States a specific verb and resource ('Recent runs for one eval, newest first') and enumerates the returned fields including the full status lifecycle (PENDING/RUNNING/SCORING/DONE/FAILED). It clearly distinguishes itself from the run-triggering tool by calling itself 'THE CHECK-BACK for caliper_evals_run', though it leaves any contrast with the sibling caliper_evals_runs_get (single-run fetch) implicit.

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 selection condition ('when the user asks how the run went, read this') and ties the tool to a specific sibling. It also gives a negative guideline ('don't poll in a loop; check when the user asks or when reporting'), which is exactly the when-not-to-use guidance an agent needs.

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

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

With destructiveHint=true, the description adds rich context beyond annotations: it explains immutable fields, that scheduled/on-publish runs spend credit, that a 'needs_confirmation' response is possible, and the credit-cost implication of enabling schedulers. This goes well beyond what the annotation flags alone 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 description is a single, dense paragraph that front-loads the mutable fields, then immutable fields, then a behavioral note. Every sentence earns its place with no filler.

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

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

The tool has 13 parameters, no output schema, and annotations indicating destruction. The description covers the update scope, immutability, credit cost, and the needs_confirmation flow, which is nearly complete. It omits a note about the required evalId parameter, but the schema marks it required and describes 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 the schema already documents all 13 parameters in detail. The description reinforces the most important semantics (e.g., regressionThreshold scale, schedule interval meaning) but does not add new parameter-level information beyond the schema. Baseline 3 is appropriate.

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

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

The description names the specific verb (changes/updates) and enumerates the exact mutable fields (title, description, visibility, schedule, runOnPublish, regressionThreshold, scenarioId), which is precise. It does not explicitly distinguish itself from caliper_evals_create, though the phrase 'The dataset, rubric snapshot, and target are fixed at creation — create a new eval to change those' implicitly routes to the create sibling.

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

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

The description gives clear usage guidance: 'Pass only what changes' and delineates immutable fields with an explicit alternative ('create a new eval to change those'). It also states to communicate credit spend when turning on scheduled/on-publish runs. It doesn't distinguish itself from other update-like siblings (e.g., caliper_evals_run), but those are clearly distinct operations.

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, closed-world), so the bar is low, and the description adds substantive context: the exact contents of the report and how to interpret worst-scoring items diagnostically. It does not cover permissions, rate limits, or cost of the underlying eval runs. No contradiction with 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 core purpose and payload, and each of the three sentences carries distinct information (what you get, when to call it, how to read the diagnostics). The capitalized 'ACTUALLY' and 'with receipts' are stylistically chatty for a tool definition, but the paragraph stays compact.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values, which it does thoroughly for a read-only report. It is a bit light on ordering/recency semantics of 'recent runs' and any notion of time windowing, which the schema does not cover either.

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 description adds no parameter-level detail (no flowId format, no workspace behavior). With the schema fully documenting both params, baseline 3 applies; the description neither compensates nor degrades.

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

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

States a specific resource (a Workbench flow) and enumerates exactly what the tool reports: every targeting eval, recent runs with scores, per-criterion averages, delta vs previous run, and worst items with judge reasoning. That payload enumeration distinguishes it from raw siblings like caliper_evals_runs_list or caliper_evals_get. It lacks an explicit verb and never names a sibling, so it lands at 4 rather than 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 a clear trigger: use it BEFORE claiming a flow works or proposing changes, and cite runId + scores. It also prescribes a downstream action for clustered failures (propose a Compass interview for knowledge gaps rather than a prompt fix). No when-not condition or named alternative tool is given, so it stops short of 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, openWorldHint=false, so the safety profile is covered. The description adds domain behavior (the rubric is consumed by an LLM judge or by code checks) but says nothing about what happens on creation — returned id, whether it must be attached to an eval separately, or the approvalId confirmation path mentioned 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?

Three dense sentences with no filler, and the core verb+resource is front-loaded before the enum detail. The parenthetical enumeration of check types is long but each item is load-bearing; the closing style-guide sentence is the only part that leans toward advice rather than definition.

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 create tool with a nested criteria array and no output schema, the description covers the substance of the criteria model well and matches the annotations. It leaves the lifecycle gap — how the created rubric is linked to an eval and what the caller gets back — unexplained.

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

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

With 67% schema coverage, the description still meaningfully augments the schema: it explains that kind=check runs "in code with no judge" and enumerates the check types, which the schema lists without explanation. It does not add anything for workspace, approvalId, or the top-level description parameter, which carry thin or no 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 and resource ("Creates the scoring rubric") and immediately situates it in the domain ("an eval's LLM judge uses"), which cleanly separates it from sibling read/update/delete rubric tools. The elaboration of the three criterion kinds makes the purpose concrete rather than tautological.

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 useful content guidance ("Write criteria about the FLOW'S JOB ... not generic 'quality'"), which is real how-to-use advice, but never names when to choose this over caliper_rubrics_update, nor states prerequisites. Usage is implied by context (you create a rubric before an eval can judge) 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, but the description adds non-obvious consequences: existing evals retain a snapshot and keep running, while nothing new can bind to the rubric. It also discloses the needs_confirmation response state. It stops short of permissions or 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?

Three short, front-loaded sentences; the primary action comes first, followed by blast-radius and confirmation flow. No filler.

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

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

For a destructive tool with no output schema, the description covers the key things an agent needs: what is deleted, what survives, and the confirmation path. Missing only auth/permission caveats and reversibility, which are minor given the annotations.

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 clear descriptions for rubricId, workspace, and approvalId, so the schema carries the parameter burden. The 'needs_confirmation' mention loosely ties to approvalId but adds no syntax or format detail beyond the schema.

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

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

States a specific verb ('Deletes') and resource ('a rubric'), which cleanly disambiguates it from caliper_rubrics_create/update/get/list. No ambiguity about what the tool does.

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

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

Usage is implied by the required rubricId (from caliper_rubrics_list) and the destructive verb, and the needs_confirmation note hints at the confirmation workflow. However, it never states when to delete versus update/retire a rubric, or any preconditions.

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 the agent knows this is a contained safe read. The description adds useful context about what the read returns (criterion names, judge focus, score scale). Beyond that it does not describe pagination, caching, or error behavior, and with annotations carrying the safety profile the description's added value is moderate.

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 is returned, why to read it, and where the id comes from. The purpose is front-loaded and the guidance follows naturally.

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 two-parameter read tool with annotations covering safety and no output schema, the description covers the resource, its contents, and the id source adequately. The minor gap is that workspace behavior is left entirely to the schema, but that is reasonable given 100% schema coverage.

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

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

Schema coverage is 100% — the schema itself documents rubricId and workspace. The description reinforces where to obtain the rubricId, which is helpful routing but not syntax or format information beyond the schema. Baseline 3 applies because the schema already 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?

The description specifies the verb (read), resource (a single rubric), and the exact contents returned — criteria with their names, the judge's focus, and the score scale. It is clearly distinguishable from siblings like caliper_rubrics_list and caliper_rubrics_update.

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

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

It gives two concrete when-to-use conditions (to explain a score and before updating) and names the source for the required rubricId. Exclusions are implicit but the alternative list tool is referenced for retrieval.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the result shape (id, name, description, criterion count) and that results are scoped to the active workspace. It stops short of describing pagination or list size limits, so not a full 5.

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

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

Purpose is front-loaded in the first clause, followed by conditional routing and a follow-up pointer. Three compact sentences, no filler, every clause is actionable.

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 listing the returned fields. Combined with annotations covering the safety profile and clear routing to sibling tools, 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 is 3. The description's 'active workspace' phrasing aligns with the parameter but adds no new syntax or format detail beyond the schema.

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

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

States a specific verb (Lists) and resource (rubrics in the active workspace) and even enumerates the returned fields (id, name, description, criterion count). It explicitly names the sibling tools caliper_rubrics_create and caliper_rubrics_get, so an agent can distinguish it from neighbors without opening any schema.

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

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

Gives explicit sequencing ('Check here BEFORE caliper_rubrics_create'), a concrete reason (reuse an existing rubric's id in caliper_evals_create), and routes the agent to caliper_rubrics_get for criteria. When-to-use and alternatives are both stated, 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 flag it as a destructive write, and the description adds material behavior the annotations don't: criteria get fresh ids on replacement, existing evals are immutable snapshots that keep scoring with their original criteria, and the call may return `needs_confirmation`. This is exactly the kind of context an agent needs before mutating a shared object.

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 tightly-scoped sentences, front-loaded with the core mutation and followed by the snapshot caveat. The meta-instruction ('say so, and offer to create a new eval') is slightly directive for a description but still earns its place as agent 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?

For a 7-parameter mutation tool with no output schema, it covers the destructive-path semantics, the confirmation flow, and the downstream eval implications. It relies on the schema for workspace/approvalId details, which is reasonable given full schema coverage, leaving only minor 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, but the description adds value beyond the schema by emphasizing passing the FULL criteria list and noting that criteria receive fresh ids — behavior the schema doesn't state.

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) on a specific resource (rubric) and enumerates the affected fields (title, description, visibility, criteria). It also clarifies the criteria semantics as a wholesale replacement rather than a diff, distinguishing it from a partial-update mental model.

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 workflow context: criteria edits replace everything, evals snapshot at creation, and the agent should surface that and offer to create a new eval when criteria change materially. It doesn't explicitly contrast against update-vs-create or other rubric siblings, but the in-context guidance is actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false; the description adds useful domain context by enumerating observable fields (pick, sampling, landed count, running state). This goes beyond the annotations but doesn't cover auth/permission nuances or output 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?

Single long sentence with a colon list that crams many concepts (dataset, purpose, pick, sampling, count, state) into one clause. Front-loaded with the key subject but the density slightly hurts scannability.

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 a small, fully documented 2-param schema and no output schema, the description gives a rich picture of what items contain. It omits pagination/limit behavior, but that's a minor gap given no such params exist.

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 fully documents sourceId and workspace. The description adds no parameter-level hints beyond confirming that this tool is scoped to a source, making the baseline 3 appropriate.

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

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

States a specific resource (datasets a source keeps adding to) with clear scope. It distinguishes itself from the broad caliper_datasets_list by anchoring to a source and 'live/ongoing' nature, though it doesn't explicitly name the sibling alt.

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

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

Usage context is implied through 'datasets this source keeps adding to' but there is no explicit when-to-use or when-to-use-alternative guidance. An agent must infer from the required sourceId that this is source-scoped listing.

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 genuinely useful non-obvious context: that stopping is non-retroactive ('What it already added stays') and that a `needs_confirmation` response is possible. It does not describe reversibility or how to restart ingestion, 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 short sentences, front-loaded with the core action and its scope caveat, then the prerequisite and the possible response state. No filler and nothing 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?

No output schema exists, so the description carries the return-value burden and does mention the possible `needs_confirmation` state. Combined with 100% schema coverage for the four parameters, an agent has enough to call it correctly, though the restart/recovery path remains 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?

Schema description coverage is 100%, so all four parameters (including workspace and approvalId) are already documented in the schema, which is the baseline-3 case. The description reinforces the feedId provenance and references the confirmation flow, but adds no syntax or constraints 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?

The description states a specific verb and resource ('Stops a source from adding new conversations to a dataset') and immediately scopes the effect ('What it already added stays'), which distinguishes it from a destructive delete. It also names the sibling used to obtain the required id, so an agent can route correctly 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 implies the usage context (halting a live feed) and points to caliper_source_feeds_list for the feedId, but never states when-not to use it or names the counterpart tool (e.g., caliper_sources_to_dataset) that would re-enable ingestion. The guidance is implied rather than explicit.

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 real behavioral context beyond that: results are ordered busiest first and scoped to the last 14 days with per-day counts plus top tools by trace share. It stops short of describing error/auth edge behavior, so not a 5.

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

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

Front-loads the purpose, then enumerates the returned fields (which compensates for the absent output schema), then routes to the sibling. Every clause carries information; there is no filler.

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

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

With no output schema, the description carries the return-value burden and does so — name, send method, 14-day per-day trace counts, and top tools with share. For a single-param read-only list tool with annotations covering safety, 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% and the single workspace parameter is fully documented in the schema, including the token/default-workspace rule. The description adds no parameter guidance, so the baseline 3 is correct — 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+resource (list Caliper sources) and immediately defines what a source is — apps sending agent traces via own code, OpenTelemetry, or a Workbench flow. It explicitly distinguishes itself from the sibling caliper_sources_over_time, so an agent can tell them apart 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?

Provides explicit when-to-use ("Start here when the user asks how their agent behaves on real traffic") and names the follow-on alternative with its condition ("then caliper_sources_over_time for one source"). 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 safety is covered. The description goes further by explaining metric semantics that the schema cannot: p50/p95 are defined as 'answered within' bucket edges and empty-result lookups are surfaced. It does not disclose aggregation granularity, result size, or any limits beyond the schema's days maximum.

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 verb and the returned metrics, followed by a usage example and a chaining instruction; each sentence carries information. The opening enumeration is dense with semicolons and parentheticals, which slightly taxes readability, but nothing is padding given the absence of an output 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?

With no output schema, the description correctly carries the return-shape burden by cataloguing the metrics and their meaning, and it closes the loop with a follow-up tool for drill-down. It leaves out aggregation granularity, response size/paging, and how the days window interacts with the reported daily buckets, which keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents sourceId, days (default 30) and workspace. The description only loosely touches parameters ('compare the first and last weeks' implies a window but gives no syntax for days) and says nothing about workspace selection. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Read a Caliper source over time'), then enumerates the exact payload an agent gets: traces, failures, tool calls, empty lookups, tokens, cost, speed buckets, per-tool shares, documents, and models. It also implicitly distinguishes itself from caliper_traces_list by positioning that sibling as the drill-down for a single day/tool. An agent can tell what this returns without opening a schema.

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

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

Gives a concrete use case ('how often is it calling web search and is that changing — compare the first and last weeks and name the day it moved') and names the follow-up tool (caliper_traces_list on that day or tool). It stops short of stating when NOT to use it or how it compares to caliper_flow_performance, so no explicit exclusion is provided.

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 ordering (newest first up to limit), the live keepAdding behavior with sampling ratios and the 1,000 cap, the effect of each purpose mode on item contents, and the needs_confirmation return path. Annotations (readOnlyHint=false, destructiveHint=false) match the additive create semantics.

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 leads, then purpose semantics, then live-mode behavior and next steps. Every sentence carries information, though the paragraph is long and could be broken into clearer chunks.

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-parameter mutation with no output schema, it covers the confirmation flow, ordering, caps, and follow-on actions needed to invoke and continue correctly. Nothing an agent would need before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it translates the terse 'review | eval | spec' enum into what each item keeps, and elaborates keepAdding as every-one or 1-in-10/1-in-100. It leaves workspace and approvalId handling 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 ('Saves the conversations... into a new dataset or an existing one') and pins the scope by reference to caliper_traces_list's same narrowing (day, tool, document, failures). An agent can tell it apart from caliper_datasets_create or caliper_datasets_add_items without opening any schema.

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

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

Gives clear selection logic between newDatasetName and datasetId, explains when to set keepAdding to make it live, and routes the agent to the next step (caliper_evals_create). It does not explicitly compare against sibling routing like caliper_datasets_add_items, so it stops short of full 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 already establish readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the required scopes (caliper:datasets:write and caliper:evals:write), that the resulting artifacts are user-owned and editable, and what is returned (both ids). It stops short of saying whether a re-run duplicates artifacts or how the approvalId confirmation flow behaves.

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

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

Three tight sentences with no filler: what it does first, then the return value and next step, then the permission requirement. Every sentence earns its place and the core action 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?

For a mutation tool with no output schema, the description supplies the missing pieces an agent needs: the shape of the result (both ids), the required scopes, and the natural continuation (caliper_evals_create). Nothing essential to invoking it correctly is 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 description coverage is 100%, so slug, workspace, and approvalId are already documented in the schema, including the enum and the 'omit on first call' note for approvalId. The description adds no parameter-level syntax or format detail beyond what the schema provides, 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 with concrete outcome: copies one starter into the workspace as a new dataset and a new rubric the user owns and can edit. This clearly distinguishes it from the sibling caliper_starters_list (which only enumerates starters) and from caliper_datasets_create / caliper_rubrics_create (which create one artifact, not both).

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

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

Names the follow-up step explicitly (caliper_evals_create binding the dataset and rubric to a flow or to 'external'), and the slug enum in the schema points back to caliper_starters_list as the source of valid input. It does not state when NOT to use it (e.g. preferring caliper_datasets_create when the user wants a blank dataset), so it falls 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 already declare readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description adds genuinely non-structural context: the items are public, a starter is a smoke test rather than a safety score, and the user's own cases carry the real signal. It stops short of describing the list's shape or pagination, hence not a 5.

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

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

Front-loads the enumeration of starter sets, then usage guidance, then the caveat. Every sentence carries content, though the parenthetical about single vs multi-turn build-ups is dense and slightly slows scanning.

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

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

No output schema exists, and the description compensates by naming what each starter contains (dataset plus anchored rubric). It never explicitly says the call returns a list of these entries, but the title and first sentence make that inferable. Complete enough for a zero-arg 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. Score held at 4 because the description adds no parameter-relevant confusion either.

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

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

States a concrete verb+resource ('The starter sets Caliper ships') and enumerates the actual contents (prompt injection, system-prompt leaking, over-refusal, personal-data handling, bias under ambiguity), so an agent knows exactly what this returns. It also distinguishes itself from caliper_starters_install by name.

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

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

Gives an explicit trigger condition ('Suggest one when a user wants to check an assistant for these and has no cases yet') and names the follow-up tool (caliper_starters_install) with the action verb 'install'. Both when-to-use and the next step are 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds genuinely useful behavior: the shape of the returned step list and the 2,000-character truncation limit on long values. It omits error behavior for a missing trace, but the truncation disclosure is real added value beyond the annotations.

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

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

Content is front-loaded ("One trace: what came in, what went out, and every step in order"), with truncation and intended use following. The middle clause is dense with parentheticals, but each earns its place by telling the agent what fields 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 return-value burden and does so well by enumerating call types and their fields plus the truncation limit; the annotations handle safety and the schema handles input routing. Only the failure mode for an unknown traceId is unaddressed, 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%, and the schema already documents all three parameters including the workspace/token default rules and where traceId and sourceId come from. The description adds no parameter 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?

The description makes clear this retrieves a single trace and enumerates exactly what it contains (model calls, tool calls, lookups, timing, status), which implicitly contrasts with the sibling caliper_traces_list. It never states a plain verb like 'retrieve one trace by id', but the resource and scope are unmistakable.

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

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

"Use it to explain why one conversation went the way it did" gives one concrete debugging scenario, and the schema's traceId note points back to caliper_traces_list as the source of ids. However there is no explicit when-not guidance or statement of the list-then-get workflow in the description itself.

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, and the description adds genuinely useful behavior beyond them: newest-first ordering, a fixed 50-per-page size, truncated question/answer fields, and the paging cursor contract. It stops short of noting any rate limits or result caps, so it is strong but not exhaustive.

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

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

Two dense sentences, front-loaded with the resource and return shape, then filters and paging. Every clause adds information; there is no filler or repetition of structured fields.

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 usefully sketches the returned record fields, paging, and the natural follow-up tool. It omits nothing critical for invocation, though the workspace-scoping caveat is left entirely to the schema.

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

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

Schema coverage is 100%, so every parameter including `before`, `day`, `tool`, and `document` is already documented. The description reinforces the filter semantics and the paging cursor, but adds no syntax or format detail beyond what the schema carries, 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 resource (the traces behind a point on a source's chart) and even enumerates what each record contains (question/answer, tools, time, tokens, cost, status). It clearly distinguishes itself from caliper_traces_get, which it names for single-record retrieval.

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

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

Explicitly tells the agent how to narrow the list (day, tool, document, failures), how to page (`before` with the nextBefore from the last page), and routes to caliper_traces_get for opening one. Nothing about when to use vs. the sibling 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 write, non-destructive, closed-world behavior, so the baseline is set. The description adds genuine behavioral context: the mention path 'rings their notification bell', which is a side effect an agent should know about, plus the thread-vs-reply branching. It stops short of noting auth requirements or idempotency.

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

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

Three sentences, front-loaded with the core action and mode selection before the usage example. The closing etiquette line ('never mention someone who didn't ask') is editorializing but arguably still useful guardrail content.

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

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

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

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

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

Schema coverage is only 43%, so the description is expected to compensate. It meaningfully explains mentionedUserIds (workspace member ids) and rootId (reply target), but leaves approvalId, workspace, entityKind semantics, and body constraints unexplained. Partial compensation warrants a baseline 3.

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

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

States a specific verb+resource ('Posts a comment on a workspace entity') and clarifies the two modes — new thread vs reply when rootId is given. An agent can immediately tell what this does without opening the schema.

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

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

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

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

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

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

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

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

Two sentences, front-loaded with the operative fact (what is listed, in what order) before the advisory second sentence. The second sentence is slightly rhetorical ("where disagreement lives before it becomes a decision") but it does convey routing intent, so little is wasted.

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

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

With no output schema, the description compensates by naming the returned content (threads, authors, timestamps, ordering), which is the key information an agent needs. It remains silent on result size/pagination and on empty-result behavior, so it is strong but not fully complete.

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

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

Schema coverage is 67%: workspace is well documented in the schema, entityKind has only a terse "What the thread hangs on" description, and entityId has none. The description says only "one workspace entity," adding no format, valid-value, or relationship detail beyond the schema enum, so a baseline 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

Two dense sentences with the mechanical fact (what rootId is) front-loaded, followed by the policy. No filler, no restatement of the title.

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

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

For a 4-parameter mutation tool with no output schema, the description covers purpose, when-to-use, and the key parameter. The gaps are approvalId (never explained) and workspace/auth expectations, which matter for a destructive operation, but the core agent decision-making path is well served.

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

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

Schema coverage is only 25%, so the description must carry more weight. It usefully defines rootId (the thread's root comment id) and implies resolved=true/false via 'resolve or reopen', but says nothing about workspace (which the schema does describe) or approvalId (undocumented in both places). Partial compensation for a low-coverage schema.

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

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

The description states a specific verb (sets the resolved state) and resource (a comment thread), and clarifies the ambiguous rootId by equating it to the thread's root comment id. It clearly covers both directions of the operation (resolve and reopen). It does not explicitly distinguish itself from comments_create/comments_list, though the reply-first instruction implies a division of labor.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Opens with a specific verb+resource ('Replace a change's effects') and immediately distinguishes itself by naming the sibling that supplies inputs (compass_workflow_steps) and the sibling that consumes the result (compass_workflow_rollup changeIds). An agent can tell this apart from compass_transformations_* and compass_changes_upsert without opening a schema.

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

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

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

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

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

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

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

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

Front-loaded with the core create-or-update rule and matching key, then layers merge semantics, idempotency, results, and confirmation. Dense but every sentence carries operational information; slightly long, though nothing is padding.

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

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

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

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

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

Schema coverage is 67%, and the description compensates by explaining the `url` match semantics (creates vs updates), that `statusName` is by name with a pointer to compass_statuses_list, and that omitted fields are preserved. It does not clarify the remaining nested item fields (tags, experiment, workflowPageId) beyond schema, but adds real meaning over the raw schema.

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

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

States a specific verb and resource ('Create or update up to 100 changes in one call'), names the matching key (`url`), and defines the upsert rule against it. An agent can distinguish this batch upsert from siblings like compass_links_create or compass_pages_create without opening a schema.

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

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

Gives concrete usage context: rerun with identical urls to stay in sync, statuses come by name via compass_statuses_list, and 'Summarize what you're about to bring in before calling.' It does not explicitly name when to prefer this over other creation paths, so it stops short of full when/when-not guidance.

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

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

Annotations mark this as a non-destructive, non-readOnly, closed-world write. The description adds genuinely useful context beyond that: 'No approval needed — noting your own uncertainty isn't acting on the user's behalf', which explains why an agent may write freely, plus 'the gap registry is your working memory'. It doesn't cover rate limits or response shape, but the approval-free rationale is substantive added value.

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

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

Front-loaded with the core purpose and the guidance to use it liberally, then moves to required content and the subject attachment. It's appropriately sized, though the question/rationale/resolution sentences partially restate the schema, adding mild redundancy.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra: it maps the required 'question' to a framing rule ('one clear question'), ties 'rationale' to 'what answering it unblocks', and — critically for the thin schema entries — explains subjectType/subjectId as the mechanism for tying a gap to a specific page or person. That last point adds meaning not present in the schema text.

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

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

States a specific verb and resource — 'Records something you don't yet know' against the 'gap registry' — and reframes the resource as 'open question (gap)', so an agent knows this is the create side of the compass_gaps_* family. The framing is distinguishable from compass_gaps_list/resolve/update without opening the schema.

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

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

Gives concrete when-to-use context: 'use it liberally while mapping or interviewing', and conditions the subject attachment on whether the gap is ABOUT a specific page or person. It stops short of naming alternatives explicitly (e.g., compass_gaps_update to amend, compass_gaps_resolve to close), so it's clear context but not full routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the default-to-OPEN filtering behavior and the registry framing, but says nothing about result size, pagination, or workspace/auth scoping beyond what the schema states. Adequate but not rich.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Gives real usage context: 'check it before asking the user something you may already have flagged, and compose interview briefs from a subject's open questions.' That tells the agent when to reach for it. It does not name an alternative tool or state exclusions, so no 5.

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

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

Annotations already declare a destructive, non-read-only mutation, and the description adds genuinely non-obvious behavior on top: gaps the agent raised close without a card, while a person-authored question requires their approval (matching the approvalId re-call flow). It stops short of saying whether a resolution can be undone or corrected later.

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

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

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

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

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

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

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

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

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

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

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

The description names a specific verb and resource ('Closes a gap') and enumerates the two terminal states (ANSWERED with resolution, DISMISSED), which lets an agent distinguish it from compass_gaps_create and compass_gaps_list. It never states, however, how it differs from the sibling compass_gaps_update, which overlaps conceptually with 'resolve'.

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

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

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

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

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

Annotations already declare destructiveHint=true/readOnlyHint=false, so the mutation risk is covered. The description adds real behavioral context beyond that by flagging the two-phase confirmation flow ('May return `needs_confirmation`'), which changes how an agent must sequence calls. It stops short of saying whether prior wording is recoverable or what permissions are needed.

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

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

Two sentences, front-loaded with the action, then the alternative and prerequisite, then the return caveat. Every clause carries information and there is no filler.

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

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

For a mutation tool with no output schema, it covers purpose, routing, id sourcing, and the needs_confirmation return path with annotations carrying the safety profile. Minor gaps remain around permission requirements and partial-update behavior, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the workspace and approvalId mechanics. The description only restates which content fields are editable (wording/rationale/resolution) already implied by the schema, adding little new meaning. Baseline 3 applies.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable semantics the annotations cannot: the exact composition of the inbox, that fillIn is excluded from total, and that offsetting cards are pending approvals. It does not describe pagination or ordering, so not a 5.

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

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

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

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

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

There is no output schema, and the description compensates by naming the three inbox categories, the uncounted fillIn set, and the recommended follow-up tools for each category. Missing only explicit pagination/ordering and what a total counts, which is minor for a read-only overview tool.

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

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

Schema coverage is 100% and the single workspace parameter is fully documented, so the baseline is high. The description adds no parameter detail but does not need to, and it clarifies the return shape and the fillIn/total relationship which supports interpretation of results.

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

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

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

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

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

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

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

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

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

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

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

Front-loads the core action and framing in the first clause, then layers operational constraints. It is a dense single paragraph and reads as slightly run-on, but nearly every clause carries distinct information, so almost nothing is wasted.

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

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

For a tool that sends real outbound email through an approval flow with no output schema, the description covers the full lifecycle: message authoring, approval gating, rate limit, and async completion signal. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds content guidance for `message` beyond the schema — short, human, explains why THEIR knowledge matters, ~15 minutes, no account needed — which tells the agent what to actually write, not just where it goes.

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

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

States a specific verb and resource ('Emails the guest link for an existing interview') and pins the framing ('from the REQUESTING USER'). The word 'existing' cleanly separates it from compass_interviews_create, so an agent can distinguish it from siblings without opening a schema.

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

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

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

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

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

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

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

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

Front-loaded with the core definition in sentence one, then usage, then mechanics, then the approval caveat — a sensible descending-priority order. Dense rather than padded, though the all-caps 'THE KNOWLEDGE-GAP MOVE' framing and stacked parentheticals add a little rhetorical weight.

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

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

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

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real selection guidance: focusPrompt should name the SPECIFIC gaps and cite the eval run id, and interviewee should be the owner of the relevant workflow when the map knows one. It doesn't add much for workspace or contextPageIds, which the schema already explains.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so both parameters are documented there and 3 is the baseline. The description adds one small piece the schema lacks — that ids may also come from compass_inbox_list, not only compass_interviews_list — but does not otherwise elaborate on parameter meaning.

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

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

The description gives a specific verb and resource ('One interview in full — metadata plus the transcript') and states the scope that distinguishes it from compass_interviews_list: this returns the full record including transcript, not a list. An agent can immediately tell what it fetches without opening the schema.

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

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

It states a clear use condition ('Read this before summarizing an interview or drafting pages from it') and routes the agent to where ids come from (compass_interviews_list, compass_inbox_list). There is no explicit when-not or note about how this relates to bulk retrieval, so it stops short of full routing guidance.

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

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

Annotations only cover the safety profile (readOnlyHint, openWorldHint=false, destructiveHint=false); the description adds substantive context beyond that: result ordering, the status lifecycle values, that transcript review is signalled by documentPageId being set, and that invite URLs are only present while the link is live. For a no-output-schema tool this is exactly the behavioral disclosure an agent needs.

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

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

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

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly: fields, status values, ordering, and liveness caveat. Combined with annotations covering the safety profile and a fully documented single parameter, nothing an agent needs to call this correctly is missing.

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

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

There is a single 'workspace' parameter with 100% schema description coverage, so the schema already explains slug/default/API-key semantics fully. The description only implies workspace scoping and adds no format or defaulting detail for the parameter, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (list stakeholder interviews) and immediately enumerates scope: workspace-wide, newest first, with the exact fields returned. It explicitly distinguishes itself from compass_interviews_get, so an agent can choose between them without opening either schema.

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

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

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

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

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

Annotations already flag destructiveHint=true, and the description builds on that by disclosing idempotency, the exact user-visible consequence (link becomes inactive), and the two-step confirmation flow ('May return needs_confirmation'), which pairs with the approvalId parameter. This is behavior an agent cannot infer from annotations alone.

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

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

Front-loaded with the core effect, then triggers, then operational notes (idempotency, id source, confirmation). Every sentence carries distinct information with no filler.

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

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

For a destructive revoke tool with no output schema, the description covers the effect, the trigger cases, idempotency, where ids come from, and the confirmation round-trip. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three fields; the baseline would be 3. The description adds useful provenance for interviewId ('Ids come from compass_interviews_list') and ties the needs_confirmation return to the approvalId field, giving extra value over the schema.

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

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

States a specific verb and resource ('Kills an interview's invite link') and even describes the observable effect ('the guest's next visit sees that the link is no longer active'). An agent can distinguish this from the invite-creating sibling without opening any schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so pageId and workspace are already documented in the schema. The description implies pageId means 'the page the knowledge gap is about' but adds no format or syntax detail beyond that. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource — ranks the PEOPLE the map says know about a page — and immediately narrows the domain (workflow, system, pain point). The ranking rule (owns first, then involved_in, then weaker edges) makes it unmistakable versus siblings like compass_interviews_create or compass_step_claims_list.

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

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

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

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

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

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

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

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

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

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

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

For an 11-parameter mutation tool with no output schema, the description covers the domain rules (canonical directions, one-parent constraints on PRIORITY and UNIT, idempotency) and the return-side confirmation behavior, leaving no material gap an agent needs before calling it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: it explains the semantic direction of each `kind` enum value (e.g. PERSON owns WORKFLOW, PAIN_POINT affects WORKFLOW), the purpose of validFrom/validTo, and the sourceKind/sourceId pairing. This lifts it above baseline.

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

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

The opening sentence gives a specific verb and resource — 'Creates a typed, directed edge between two pages' — and frames it as the graph's connective tissue. This is immediately distinguishable from the sibling mutation/read tools (compass_links_update, compass_links_delete, compass_page_links_list).

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

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

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

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

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

Annotations already declare destructiveHint=true, but the description adds materially important behavior beyond them: the delete is edge-only (pages survive), the edge can be revived by re-creating it, and the call may return `needs_confirmation` (matching the approvalId flow in the schema). Reversibility and the confirmation gate are exactly the traits an agent needs before invoking a destructive tool.

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

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

Front-loads the core action and scope, then the decision rule, then the id source and reversibility note. Every sentence carries distinct, actionable information with no padding.

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

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

For a destructive, 3-param tool with full schema coverage, destructive annotations, and no output schema, the description covers the decision criteria, the confirmation/approval path, and reversibility. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so all three parameters (linkId, workspace, approvalId) are already fully documented in the schema. The description only restates that link ids come from compass_page_links_list, which the schema already says — baseline 3 applies.

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

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

States a precise verb and resource — 'Deletes one edge from the graph' — and immediately disambiguates scope with '(the pages stay)'. It is clearly distinguishable from its siblings compass_links_create, compass_links_update, and compass_page_links_list.

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

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

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

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

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

Goes well beyond the annotations by disclosing that history is preserved (the old edge stays as history), that a conflict error is raised when the new reading already exists, and that the call may return needs_confirmation. This is meaningful mutation/error/approval context for a destructive write tool.

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

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

Front-loaded with the core action and dense with useful detail; every clause is actionable. It is on the long side with two inline examples, but no sentence is redundant.

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

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

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

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic meaning: it frames kind as a correction mechanism and validTo as a relationship terminator with an example. It does not, however, clarify validFrom or the approvalId/workspace plumbing beyond what the schema already documents.

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

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

States a specific verb (Edits) and resource (an existing edge between two pages) and enumerates the mutable aspects (kind, note, validFrom/validTo). It is clearly distinguished from siblings compass_links_create and compass_links_delete, which handle the creation and removal ends of the lifecycle.

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

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

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

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