ZeroWidth Caliper

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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-annotation behavior: result ordering ('most-used first') and the fields returned in each mode (tag name + count; kind, id, title, path), but says nothing about result limits or pagination.

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 two modes that matter most before the usage advice. It is efficient, though 'the vocabulary the team already organizes by' is slight editorial padding for an agent-facing 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?

With no output schema, the description carries the return-shape burden and does so for both modes, which is the key gap an agent would otherwise face. It omits pagination/size limits, the only remaining incompleteness for a browse tool.

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

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

Schema coverage is 100%, so baseline is 3, and the schema already documents omitting the tag. The description goes beyond that by spelling out what each mode actually produces, which clarifies the semantics of the tag parameter's presence/absence rather than just restating it.

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

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

The description names the resource precisely and separates the two operating modes: no tag lists all workspace tags with usage counts, a tag expands to all items filed under it across every tool. That mode split makes it trivially distinguishable from entity_tags_get and entity_tags_set.

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

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

It gives concrete usage triggers: 'reuse existing labels instead of inventing near-duplicates' and answering 'show me everything about X' when X is a label. It stops short of naming alternatives (entity_tags_get, search_workspace) or stating when not to use it, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are batch-scoped to one entityKind and 'Entities the user can't see are omitted', i.e. permission-based filtering of results. It does not describe pagination or the shape of the returned tag set.

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 packed sentences, front-loaded with the return value before the usage guidance. The gloss 'the labels galleries organize by' earns its place by disambiguating 'tags' in this domain. Slightly dense but no filler sentences.

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

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

No output schema exists, so the description carries the burden of describing the return, which it does at a high level ('returns the tags on a batch of entities'). Combined with the permission-omission note and the id-sourcing guidance, an agent has enough to call it correctly, though the exact tag object shape remains unspecified.

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 and entityKind are documented in the schema, but ids is not. The description compensates by explaining where ids come from (the kind's list/get tool or search_workspace) and that they belong to a single kind, which is the key constraint linking ids and entityKind. It does not mention the 100-item batch ceiling, which the schema already enforces.

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 ('Returns the tags on a batch of entities of one kind') and immediately distinguishes itself from entity_tags_set, which it names explicitly. An agent can tell it apart from the sibling tag tools 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 strong context: ids come from the kind's list/get tool or from search_workspace, and it should be run before entity_tags_set so the full set is replaced knowingly. It also frames a concrete question it answers ('what is this filed under'). It stops short of naming when NOT to use it versus entity_tags_browse, so it is not a full when/when-not/alternative spec.

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 the crucial nuance annotations cannot: that this is a full replacement rather than an append, that an empty list clears tags, and how to avoid accidental data loss by reading first. It also discloses the tag format constraints and workspace-vocabulary preference, which are real behavioral characteristics.

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 destructive replacement semantic that matters most. Every sentence carries distinct, non-redundant information: replacement behavior, read-then-merge workflow, format/vocabulary rules, and id sourcing.

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

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

With no output schema, the description does not explain what the call returns (e.g. the resulting tag list), and it does not mention the needs_confirmation/approvalId flow that the schema implies for a destructive operation. Otherwise it is complete: mutation semantics, safety guidance, format constraints, and id sourcing are all covered.

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 40%, so the description must compensate, and it does so for the highest-risk parameter: tags format (lowercase/numbers/spaces/hyphens) and replace semantics. It also explains where entityId comes from. It does not explain entityKind's 20 enum values or workspace/approvalId semantics, which the schema carries on its own.

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

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

The opening clause 'Replaces the FULL tag set on one entity' gives an exact verb, resource, and scope, and the parenthetical '(an empty list clears it)' nails the edge case. It is clearly distinguished from the read-oriented siblings entity_tags_get and entity_tags_browse, which it names directly.

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

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

It explicitly states when and how to use it: read current tags with entity_tags_get first, merge, then pass the full list, and warns that the call is not additive. It also directs the agent to entity_tags_browse for vocabulary and to the kind's list/get tool or search_workspace for the id, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two things beyond that: the return payload is the 'full Markdown body' (valuable because there is no output schema) and that no authentication is required. It does not discuss rate limits or caching, 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?

Three short sentences with no filler; the core action is front-loaded and the sequencing hint and auth note each carry distinct information. Nothing could be removed without losing 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 single-parameter read tool with no output schema, the description supplies exactly the missing pieces: what is returned (full Markdown body), when to reach for it versus search, and the absence of an auth barrier. 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?

Only one parameter, and the schema documents it at 100% coverage including accepted slug formats ('compass/api', '/compass/api', 'docs/compass/api'). The description adds nothing about the slug beyond restating it, 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 (fetch) and resource (full Markdown body of a docs page) plus the retrieval key (slug). An agent can immediately distinguish this from search_docs (search) and list_docs (enumerate) without opening any schema.

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

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

Explicitly positions itself in a workflow: 'Use this after search_docs when the user needs the complete content of a page,' which names the alternative and the condition that selects this tool. It does not mention list_docs as the other plausible sibling, so it stops just short of exhaustive 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: 'No authentication required.' It stops short of describing pagination or result shape, but that gap is minor for a simple read.

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

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

Two sentences, no filler, and the scoping/workflow guidance is front-loaded before the operational note about authentication.

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

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

With no output schema, the description does tell the agent what it will get conceptually (available pages, their slugs) and how it fits with get_doc. It omits return fields and pagination behavior, which an agent might want, but nothing prevents correct invocation.

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

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

Schema description coverage is 100% and the single optional 'product' parameter is already documented with the same example values in the schema. The description repeats the filter semantics and examples rather than adding new meaning, 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 ('Enumerate all available docs pages') with scope and an optional filter named upfront. It is clearly distinguishable from sibling reads like get_doc, list_posts, and search_docs.

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 states the use case: 'discover what slugs exist before calling get_doc', which gives the agent a concrete workflow position. It names one downstream sibling but does not contrast against search_docs, which is the closest overlapping discovery tool.

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

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

Adds real value beyond the annotations by disclosing that no authentication is required and that the corpus is public — something readOnlyHint/openWorldHint do not convey. However, it says nothing about result ordering, pagination, or behavior when nothing matches, leaving meaningful behavioral gaps for a search 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 short sentences, front-loaded with what it does, then return shape, then when to use it, then the auth fact. Zero filler.

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

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

For a two-parameter read-only search with a fully described schema and annotations, this covers purpose, trigger conditions, return fields, and access requirements. Nothing an agent needs in order to call 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% and both parameters are documented inline, so the schema carries the load. The description adds no syntax, ranking, or limit guidance beyond what is already structured; 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 (search ZeroWidth product documentation) and scopes the corpus precisely — public product docs, not workspace content — which separates it from siblings like search_workspace, workbench_kb_search, and compass_pages_search without opening any schema.

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

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

Explicitly enumerates the triggering conditions: questions about a named ZeroWidth product, API behavior, or policy. It never names an alternative tool or a when-not-to-use 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?

Although annotations already declare readOnly/non-destructive/closed-world, the description adds substantial behavior the annotations cannot express: AND-of-words matching across name, tags, folder names and body text, best-first ranking, per-hit fields (id, kind, path, folderPath, tags, snippet), recursive folderId scoping, and permission-based result filtering ('only what the user can see, and only kinds this token may read').

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

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

Purpose and the 'use it FIRST' rule are front-loaded, and every later sentence adds either query semantics, return shape, or id-chaining guidance. The long enumeration of object kinds is the one place it runs heavy, though it doubles as scope documentation.

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 supplies what an agent needs about results (fields, ranking, snippet meaning, using folderPath to say where a thing lives) and how to chain ids into workspace_files_read or the kind's *_get tool. Permissions, empty-result handling, and workspace/scope limits are all covered.

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

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

Schema coverage is 80%, but the description still adds real meaning: it explains what the q words are matched against (name, tags, parent folder names, inner text) and gives worked examples ('northwind sow' finds the SOW in the Northwind folder). It also clarifies folderId is recursive, matching the schema, and leaves well-documented kinds/limit/workspace 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?

Opens with a specific verb and scope: 'Finds anything in the workspace in one call', then enumerates the object kinds covered (files, folders, flows, shims, knowledge bases, tasks, pages, datasets, evals, rubrics, reviews, specs, sources, Ledger entries, Napkin artifacts). This clearly separates it from focused siblings like compass_pages_search, search_docs, workbench_kb_search, and rooms_search, which each cover one kind.

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 trigger condition: 'Use it FIRST whenever the user mentions something without saying where it lives', backed by three concrete user-phrase examples. It also gives a recovery procedure when results are empty ('try fewer or different words before telling the user it doesn't exist'), which is when-to-use guidance beyond the happy path.

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