ZeroWidth Ledger

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 mark this as a non-read, non-destructive, closed-world write, so the description adds context beyond that: it discloses the conflict failure on superseded entries and that the call may return a needs_confirmation envelope. It does not spell out auth/permission requirements or idempotency, but for an annotated mutation tool this is solid behavioral disclosure.

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

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

It is front-loaded with the core action and each following sentence earns its place (routing to the metric-reading sibling, settlement rationale, conflict failure, id source, confirmation). It is dense and slightly long, but no sentence is 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-behavior burden and does reasonably: it discloses the conflict failure and the possible needs_confirmation response (which ties to the approvalId parameter). Combined with full schema coverage and annotations, an agent has enough to call it correctly, though a fuller picture of the confirmation flow would be ideal.

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

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

Schema description coverage is 100%, so the schema already documents every field including the kind enum defaults. The description still adds value by clarifying the provenance of entryId ('ids come from ledger_entries_list') and by grounding summary/kind usage in examples, which is slightly above the baseline-3 that pure schema coverage would justify.

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

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

The description names a precise verb and resource (records/attaches evidence against an open Ledger entry) and enumerates the concrete forms evidence takes (manual observation, implementation note, Caliper run reference). It explicitly separates itself from the metric-reading path by naming ledger_metrics_record_reading, so an agent can route correctly without opening sibling 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 states when to attach ('attach it as it arrives'), why ('evidence is what settlement later reads'), and an explicit when-not plus alternative ('metric readings attach themselves via ledger_metrics_record_reading — don't duplicate them here'). It also notes the conflict failure on superseded entries and that ids come from ledger_entries_list, 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?

Goes well beyond the sparse annotations by disclosing the pre-registration rule (prediction written now, never backfilled), the needs_confirmation response and summarize-and-wait behavior, the workspace-slug requirement for personal tokens, and the approvalId retry path. These are operational behaviors an agent must know and are not in the annotations.

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

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

Front-loads the title/body model and the three kinds before routing guidance, so the essentials come first. However it is a dense wall of prose with heavy ALL-CAPS emphasis and several long clauses that could be tighter; it earns most but not all of its length.

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

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

For an 8-parameter write tool with nested prediction objects and no output schema, the description covers the entry model, kind-specific requirements, alternative tools, the confirmation/approval return path, and page-linking. Nothing essential 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 100%, so the schema already documents fields, but the description adds real framing: TITLE vs BODY mapping for summary/rationale, the rule that prediction is decisions-only and must precede evidence, and compassPageIds as the linking target for future consult-before-acting. Meaningful but partly duplicative of the verbose 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?

Names a specific verb and resource ('Records a memory entry') and clearly delineates the three kinds (decision/lesson/observation) with what each means. It actively differentiates from siblings, stating ideas/pitches/plans are NOT entries and pointing to ledger_plan_add and Napkin docs instead.

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

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

Explicit routing: use ledger_entries_draft to propose meeting-note decisions for keep/drop, use this tool for an entry the user has asked to record, use ledger_plan_add for dated work, and Napkin for running lists. Covers both when-to-use and when-not-to-use with named alternatives.

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 say this is a non-read-only, non-destructive, non-open-world call. The description goes much further: entries remain drafts until a human confirms each one in the Drafts view, they read as low confidence because they were written after the fact, the caller should report how many drafts are waiting and where to review them, and the call 'may return needs_confirmation'.

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 what the tool produces before prescribing history conventions, and each sentence carries operational content. Some prescriptive prose ('say so plainly rather than overstating them') is stylistic guidance rather than tool semantics, but for a tool with 50 nested draft objects the length is defensible.

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

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

For a complex, nested, no-output-schema tool this covers the draft/confirmation model, the history workflow and the key field conventions well. The two auxiliary parameters (workspace, approvalId) and the shape of a normal success response beyond needs_confirmation remain unexplained.

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

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

Schema coverage is 50%, and the description compensates substantially: fromHistory's meaning, that landedAt should be the ship/launch date taken once from the source, that source URL should be attached, and that rollout stays 'full' unless the source says staged or held-out. workspace and approvalId are still unexplained in both places.

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

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

Opens with a specific verb and resource: writes up to 50 ledger entries as DRAFTS that stay out of the record until confirmed. That draft semantics is exactly what separates it from the sibling ledger_entries_create, so an agent can discriminate 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 a clear triggering condition — 'entries you found rather than were told', such as decisions in meeting notes or a team's past changes read from its tracker, PRs or launch posts — and ties it to the fromHistory flag. It never names ledger_entries_create as the alternative for direct writes, so the when-not is left implicit.

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

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

Annotations already declare this a safe, non-destructive, non-open-world read, so the bar is lowered. The description earns credit for disclosing return content beyond annotations: the six fields, the evidence attachments (Caliper runs, measurements, observations), and the bidirectional supersede chain. It does not cover failure modes (e.g. unknown entryId) or the workspace-token semantics, which the schema handles.

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

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

Front-loaded with the core purpose in one dense sentence; the em-dash list of evidence types is informative rather than padding. The second sentence about citing ids is a useful directive that earns its place, though 'full anatomy' is slightly decorative.

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-one-by-id tool with no output schema, the description is the only place return shape can be conveyed, and it does so concretely (fields, evidence, supersede chain). Combined with annotations covering safety and a fully documented two-parameter schema, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% with only two parameters, so the schema fully documents entryId and the workspace override rules. The description adds no syntax, format, or constraint detail beyond that, so the baseline of 3 applies.

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

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

The description makes clear this returns a single entry's full contents, enumerating the six fields, attached evidence, and the supersede chain in both directions. It never states the verb outright (the title carries 'Read'), and it does not explicitly differentiate itself from ledger_entries_list or ledger_entries_draft, but the singular scope is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g. ledger_entries_list for browsing). The only routing cue lives in the schema's entryId description '(from ledger_entries_list)', not in the description text. The closing sentence about citing ids governs how to relay the result, not when to call the tool.

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

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

Annotations already establish readOnly, non-destructive, closed-world behavior, so the description focuses on deeper semantics: that open entries carry a derived `lapsed` flag set from deadline passing. This is real behavioral context beyond structured fields, though it doesn't discuss response shape, ordering, or pagination beyond the cursor param.

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 opening sentence front-loads the resource definition, and the imperative "CONSULT BEFORE ACTING" follows immediately, which is well-structured. It is dense and somewhat run-on across a single long paragraph, but nearly every clause (species definitions, filter prescriptions, lapsed flag) carries usable information.

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

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

For a 7-parameter list tool with no output schema, the description covers the conceptual model, the high-value filters, and the primary consult-before-acting workflow, which is enough for correct invocation. It leaves the return shape and pagination behavior unstated, but annotations cover safety and the schema covers all parameters.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine interpretive meaning to key filters — compassPageId is reframed as "every decision touching that workflow / system / person" and status=open is tied to "unsettled expectations awaiting evidence." It does not add semantics for q, cursor, origin, or workspace beyond what the schema provides.

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

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

The description states what the resource is ("the workspace's memory") and enumerates its species — decisions, lessons, observations — so an agent knows it lists Ledger entries. It is specific about content but never contrasts itself with the sibling read tools (ledger_entries_get, ledger_plan_list) or states the listing/pagination nature, so sibling differentiation is only 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?

It gives explicit when-to-use guidance: "CONSULT BEFORE ACTING — before proposing a flow change, prompt edit, or process decision," and names the concrete filter to use (compassPageId). It further prescribes status=open for unsettled expectations and kind=lesson for settled team beliefs, with edge-case routing ("surface lapsed ones when the user asks what needs attention").

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the description carries a lower burden. It still adds real value: reversibility, full audit trail, a conflict failure on double-retract, and a possible `needs_confirmation` return. However it does not disclose the permission model or what 'reversible from Ledger' technically requires, so it is additive 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?

Five tight sentences, front-loaded with the primary use case before the exclusion, failure mode, id source, and return shape. Each sentence carries distinct information with no filler.

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

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

No output schema exists, so the description compensates by flagging the `needs_confirmation` envelope, which is exactly the return behavior an agent needs. Combined with the conflict-on-retract failure mode and id sourcing, nothing required to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it tells the agent where entryId comes from (ledger_entries_list) and links the `needs_confirmation` return to the approvalId parameter in the schema. That cross-reference is beyond what either the schema or annotations 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 and resource ('takes an entry out of the curated ledger') and immediately scopes it against siblings like ledger_entries_settle and ledger_entries_update by naming the exact error scenario it fixes. An agent can distinguish retract from settle/update without opening any schema.

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

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

Explicit when-to-use ('THE remedy when you recorded something wrong') with concrete examples, explicit when-not ('Not for overturning a settled claim the team once believed — a human supersedes that'), an urgency cue ('safe to offer as soon as the user says that's not right'), and the id source (ledger_entries_list). Every routing question is answered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: settlement is permanent, happens exactly once, requires citing evidence, and may return `needs_confirmation`. These are behavioral facts an agent needs and cannot infer from the annotations alone.

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

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

Front-loaded and compact at three sentences, each carrying real content (precondition, permanence, return signal). The opening 'The ritual moment: evidence has landed...' is atmospheric rather than strictly informative, a minor waste of words.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the key concerns: evidence prerequisite, required/permanent lesson, single-occurrence semantics, and the needs_confirmation return. Combined with 80% schema coverage, an agent has enough to call it correctly.

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

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

Schema description coverage is 80%, so the schema already documents entryId, verdict enum semantics, workspace, and lesson. The description reinforces that `lesson` is required and permanent, but adds little beyond what the schema states. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific action — settling (closing) an open Ledger entry/decision — with a clear verb+resource. The 'ritual moment' framing is stylized but it does convey the operation's role. It stops short of differentiating from all siblings by name, though it does point at ledger_entries_get as the prerequisite.

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

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

Gives an explicit precondition ('Only propose settlement when attached evidence actually answers the prediction') and names the alternative to check first ('check ledger_entries_get first'). It also discloses the one-shot constraint ('settlement happens exactly once'), which is important routing context. It doesn't mention retract/update fallbacks, keeping it from a 5.

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

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

Beyond the destructiveHint/readOnlyHint annotations, it discloses that edits fail with conflict on settled decisions, fail on superseded/retracted entries, that facet remains editable post-settlement, that null clears a prediction, and that a `needs_confirmation` envelope may be returned.

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, leading with the in-place correction and field list before constraints. Every clause carries information, though the prediction-parenthetical is tightly packed and slightly heavy.

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

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

For a mutation tool with no output schema, it covers what can be changed, what cannot, the conflict/confirmation behaviors, and id sourcing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it maps friendly names to fields (title→summary, body→rationale), clarifies that nulling prediction clears the expectation, and notes facet editability after settlement. It stops short of explaining workspace/approvalId beyond the schema.

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

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

States a specific verb and resource ('Corrects an entry in place') and enumerates the exact editable fields (summary, rationale, prediction, facet). It clearly differentiates from siblings like ledger_entries_settle, ledger_entries_retract, and ledger_entries_create by framing itself as in-place correction only.

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 ('fix a typo, swapped fields, or a misrecorded detail'), explicit exclusions ('Never edits kind or lesson', fails on settled/superseded/retracted), and it routes the agent to ledger_entries_list for ids. When-not conditions and failure modes are fully 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 only declare write/non-destructive/open-world, so the description carries the real behavioral load: idempotency ('overlapping ranges dedupe'), a size guardrail ('keep ranges to a few hundred points'), and a confirmation flow ('may return needs_confirmation'). This is meaningful context beyond the annotations, though it doesn't explain what is written or permission requirements.

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

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

Front-loads the core action and the when-to-use cue early, and each clause carries operational information. The 'a chart with a year behind it is worth far more' line is motivational padding, keeping it short of a 5.

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

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

For a 5-parameter mutation tool with no output schema and annotations covering only safety, the description is thorough: it explains idempotency, batching limits, series requirements, and the confirmation return. Only the meaning of approvalId and failure behavior remain 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 coverage is 80%, so the schema already documents id, from, to, and workspace. The description adds the 'past range' framing and hints at confirmation (relevant to the undocumented approvalId), but provides no syntax or format detail 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 states a specific action (run the frozen instruction over a past range) and a clear outcome (give a metric history rather than starting today), which is distinct from ledger_feeds_run and ledger_feeds_preview. It doesn't explicitly name sibling tools, but the historical-vs-current framing makes the role legible.

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 ('Offer this whenever you create a feed') and a meaningful precondition ('Works when the source returns a series; a source that only ever reports right now will write one point'). It lacks direct comparison to alternative feed tools, but the when-to-use guidance is clear.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context beyond that: the operation is model-free, an unknown slug silently starts tracking a new metric, and the call 'May return needs_confirmation'.

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, then flow, then return behavior in a compact block with no filler. Dense but efficient; each sentence carries information the 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 a 10-param tool with nested objects and no output schema, the description covers the essential behavioral surface (purpose, preview/backfill sequencing, needs_confirmation return). It leaves detailed nested structure (mapping/schedule) to the schema, which is acceptable since annotations carry the safety profile.

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 60%, so some params are documented but not all. The description meaningfully expands `metric` (accepts an id or snake_case slug; an unknown slug starts tracking), which the schema only partly conveys, but it says nothing about the other required/optional params (mapping, schedule, windowHours, approvalId, toolArgs).

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 ('Freeze a tool call as a metric's standing source') and immediately explains the mechanism ('runs on the cadence you give and records what it finds, with no model involved'). This clearly separates it from siblings like ledger_feeds_run (one-off) and ledger_feeds_preview (validate before creating).

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 two alternatives with explicit conditions: validate first with 'ledger_feeds_preview' and offer backfill afterwards with 'ledger_feeds_backfill'. This routes the agent through the correct setup sequence rather than leaving it 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 destructiveHint=true, so the safety profile is covered; the description adds real value beyond that by disclosing that already-written readings survive deletion (the series outlives the instruction) and that the call may return `needs_confirmation`. It still doesn't say whether the removal is reversible or what happens to scheduled future runs.

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

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

Three sentences, all earning their place: the action, the data-retention consequence, then the alternative route. The destructive consequence and the safer alternative are both front-loaded before any edge-case detail.

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

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

For a destructive, no-output-schema tool this covers the essentials an agent needs: what is destroyed, what survives, when to avoid it, and the confirmation possibility. Missing only secondary details such as permission requirements and effect on pending/scheduled feed runs.

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

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

Schema coverage is 67% and the description adds no parameter detail of its own. The mention of a `needs_confirmation` result loosely gestures at the otherwise-undocumented `approvalId` parameter, but syntax and usage for `workspace`/`approvalId` remain entirely on the schema side.

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 ('Remove a feed') and immediately differentiates itself from the neighboring mutation tool by naming `ledger_feeds_update` as the softer alternative. An agent can tell deletion from pausing without opening either schema, despite the somewhat softer title 'Stop a metric feed'.

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

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

It gives an explicit conditional alternative: 'Prefer pausing with ledger_feeds_update when the user might want it back,' which tells the agent when NOT to use this tool. It stops short of stating prerequisites (permissions, workspace scoping) or the inverse condition for choosing delete outright.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the feed's last-run result explains metric staleness. It doesn't state pagination behavior, cross-workspace visibility, or ordering, so a 3 is appropriate – useful additions but not comprehensive.

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 definition then usage triggers. No wasted words, no redundancy with the title or name.

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 goes beyond a bare return-value note to describe the shape of a feed (tool called, frequency, last-run outcome) – the essential information an agent needs. Given the readOnly annotations, safety is covered; minor gaps in workspace scoping and pagination keep it from a 5.

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

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

Schema description coverage is 100%, so the schema already defines both metricId (narrow to one) and workspace (omit to use pinned). The description implies filtering by metric and workspace through the 'which metric' framing. Baseline is 3 with high coverage; the description nudges to 4 by explaining the purpose of these filters (checking before proposing), which adds intent beyond the schema text.

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

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

States a specific resource ('standing instructions for how metrics' numbers arrive') and enumerates the exact contents (which tool each calls, how often, last run status). An agent can immediately distinguish it from sibling feeds tools like ledger_feeds_create, ledger_feeds_run, and ledger_feeds_preview.

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 two concrete when to use triggers: 'check before proposing a feed so you don't duplicate one' and 'consult when a user asks why a metric is stale'. This is strong contextual guidance. It stops short of describing limitations (e.g., scope, pagination) that would round it to a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral context: namespacing of downstream tools as `ext__<name>__<tool>`, the ability to invoke them directly to probe returns, and the fact that disabled servers are silently omitted from results. It stops short of describing result shape 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 what the tool returns and what feeds need from it, followed by the namespacing tip and the exclusion note. Every sentence carries information; no filler.

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

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

There is no output schema, so the description must carry the return semantics — it does so at a high level (servers plus the id a feed needs) but not the exact fields. For a read-only, annotation-covered list tool with a single well-documented optional parameter, this is close to sufficient.

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

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

Only one parameter exists and the schema documents it fully (workspace slug, omit to use the pinned workspace). The description adds nothing about the workspace argument, so it sits at the baseline of 3 for a fully-covered single-parameter 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 resource — connected servers exposed to this workspace, along with the id a feed requires — which is clearly distinct from sibling listers such as ledger_feeds_list or caliper_sources_list. The verb 'list' lives only in the title, so the action itself is inferred rather than stated, but the resource and its purpose (feeding a metric feed) are unambiguous.

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

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

It gives a concrete workflow hook ('call one directly to see what it returns before proposing a feed'), which tells the agent when to reach for this tool relative to creating a feed. It also states a when-not case (servers the workspace has switched off are not listed and cannot be fed from here), though no sibling is named as an alternative.

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

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

Annotations (destructiveHint=false, openWorldHint=true, readOnlyHint=false) cover the raw safety profile, and the description adds real context on top: nothing is persisted, no feed is created, and a `needs_confirmation` result is possible. One tension is unresolved — readOnlyHint=false implies possible side effects, yet the description flatly says 'nothing is written'; it never clarifies that the outward tool call to the connected server is why the tool is not marked read-only. That ambiguity keeps it from a 5.

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

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

Four sentences, front-loaded with the action, then the protocol, then the routing rule, then the possible return value. The rationale sentence about a metric filling up with the wrong number earns its place by motivating the ordering constraint; nothing is padding.

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

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

For a 7-parameter, nested-object tool with no output schema, the description covers the critical decision points: the mapping-optional two-phase flow and the `needs_confirmation` return. It is nearly complete, though `approvalId` and the workspace/windowHours interactions are left entirely to the schema, and no return shape is sketched since no output schema exists.

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 already 86% (baseline 3), and the description adds genuine semantics beyond the schema: the meaning of omitting `mapping` on the first call versus supplying one on the confirm pass, which the schema only hints at with 'Omit on the first look.' The `approvalId` parameter is documented in neither place, a minor residual gap.

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+scope: 'Call a connected server's tool once and see what a mapping would pull out of the response — nothing is written and no feed is created.' It explicitly separates itself from ledger_feeds_create and from the run/backfill siblings by making clear it creates nothing, so an agent can pick it without opening the schema.

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

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

Gives an explicit two-step protocol (send no `mapping` for a first look, then send a mapping to confirm), names the alternative workflow by ordering 'Always do this before ledger_feeds_create,' and states the consequence of skipping it. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that it does not move the schedule, that re-running is idempotent because readings dedupe per time bucket, and that it can return `empty` or `needs_confirmation`. It stops short of explaining what `needs_confirmation` means or how the `approvalId` parameter resolves it.

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

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

Four tight sentences, each earning its place: action, when to use, side-effect boundary, idempotency, possible return state. The core action is front-loaded and nothing is padded.

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 surfaces the two notable return states (`empty`, `needs_confirmation`) and the idempotency guarantee, which is enough to call the tool safely. The approval/confirmation flow around `approvalId` is the one unresolved piece an agent would still need.

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%; `id` and `workspace` are documented in-schema while `approvalId` is bare. The description adds no parameter-level meaning at all, and its mention of `needs_confirmation` never connects to `approvalId`, so it does not compensate for the coverage gap.

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 (run) plus resource (feed) plus scope ('immediately over its own window and record what it finds'). It is clearly distinguishable from ledger_feeds_backfill, ledger_feeds_preview and ledger_feeds_update 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 timing guidance ('right after creating one to prove the mapping works') and names ledger_feeds_update as the follow-up for a failed mapping. It does not, however, contrast with the sibling ledger_feeds_preview, which is the obvious alternative for a non-recording test run.

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, and the description adds substantive context beyond them: changing the mapping alters what the number means, and the call may return `needs_confirmation`. It does not cover permissions, reversibility, or rate behavior, so it stops 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?

Four tight sentences, front-loaded with the action and what changes, then the trigger and the caveat. Every sentence earns its place; the guarded phrasing ('say what you're changing and why') is guidance rather than filler.

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

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

For a destructive 10-parameter mutation with no output schema, the description covers the essential behavioral risks plus the `needs_confirmation` return signal. The main gap is that most parameters (toolName/toolArgs/windowHours/approvalId) remain unexplained anywhere.

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 only 30% across 10 parameters, so the description must carry more weight. It maps conceptually to mapping/schedule/enabled but adds no syntax, path format, or meaning for toolName, toolArgs, workspace, approvalId, or windowHours.

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?

A precise update verb on a specific resource, with the mutable surface enumerated (arguments, mapping, cadence, pause). It is distinguishable from siblings like ledger_feeds_run, ledger_feeds_preview, and ledger_feeds_delete 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 a concrete trigger: reach for it when a feed's last run reports `empty` (shape moved) or `error`. That is real when-to-use guidance, but it never names an alternative tool or a when-not (e.g., delete vs pause), so routing is not fully closed.

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 substantial behavior beyond the annotations (which only declare non-read-only, non-destructive, non-open-world). Discloses idempotent semantics (`already_present` on repeat), non-overwrite guarantee for renames and targets, empty starting state, and a possible `needs_confirmation` outcome — exactly the traits an agent needs to sequence the call correctly.

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

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

Front-loads the operation, then idempotency/non-overwrite, then adoption discipline, then next step. Four compact sentences, each earning 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?

Covers mutation semantics, idempotency, state after creation, and follow-on tools for a tool with no output schema. The only gap is that the `needs_confirmation`/approvalId flow and workspace-key interaction are not spelled out, though the schema covers the former.

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

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

Schema coverage is 67% and the schema documents slugs (source, min/max, maxItems 40) and workspace. The description implies a slug list ('named presets') but adds no new syntax or format guidance, and approvalId (linked to `needs_confirmation`) is left for the schema. Baseline 3 fits.

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 (creates/adopt) and resource (named presets as real metrics the workspace owns, tagged from the catalog). Clearly distinguishes itself from ledger_metric_presets_list (catalog browsing) and ledger_metric_starters_adopt / ledger_metrics_create by describing catalog-sourced adoption into owned metrics.

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 adoption guidance ('Adopt only what the user agreed to', anti-pattern warning about noise, 'eight thoughtful ones beat forty') and a next-step handoff to ledger_feeds_create or a first reading. Does not name when to prefer ledger_metric_starters_adopt or ledger_metrics_create instead, so full alternative routing is absent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: what each returned item contains, that these are starting points which can be renamed and retargeted afterwards, and an interaction norm (suggest 3-6, don't dump the catalog).

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 catalog is, then usage triggers, then filters, then interaction guidance. It is on the longer side, but nearly every clause carries actionable information; only the closing rename/retarget note is marginally soft.

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 correctly describes the shape of returned items (unit, cadence, good-direction, facet, tags). With usage conditions, filters, an adopt path and interaction norms all present, an agent has everything needed to call and apply this tool correctly.

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

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

Schema coverage is 100% with enum descriptions, so baseline is 3. The description adds semantic framing beyond the schema by explaining facet as 'where it lives in the business' and tag as 'what kind of number it is', clarifying how the two filters conceptually divide the catalog.

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 (ready-made metric presets) and enumerates the attributes each carries (unit, cadence, good-direction, facet, tags), so the agent knows exactly what is being browsed. It also distinguishes itself from the adopt sibling, which is the action tool, not this read tool.

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 three triggering conditions: a workspace with few/no metrics, someone asking what to measure, and a decision needing a number to settle against when none exists. It also routes the follow-up action to ledger_metric_presets_adopt by name.

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 context beyond the annotations: readings are retained, settled entries still read correctly, and a `needs_confirmation` envelope may be returned. This usefully clarifies the true (reversible) impact against the destructiveHint=true annotation rather than contradicting it. It doesn't cover auth/permission requirements or workspace-scoping behavior, keeping it below 5.

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

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

Three tight sentences, front-loaded with the core action and direction semantics, followed by impact and the confirmation caveat. No filler; every sentence carries information.

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

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

With no output schema, the description carries the return-value burden and partly discharges it by disclosing the possible `needs_confirmation` response. Combined with impact/reversibility notes and the id source, an agent has enough to invoke it correctly, though it doesn't describe the success payload.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description's notes on `metricId` accepting an id or slug and the true/false meaning of `archived` restate 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 (archive/unarchive) and resource (metric), and disambiguates the two directions via `archived: true`/`false`. An agent can tell this apart from siblings like ledger_metrics_update or ledger_metrics_list 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 usage context: 'the cleanup for a metric minted once and abandoned, or one the workspace stopped watching.' It also points to ledger_metrics_list as the source of valid ids. It stops short of naming an explicit alternative to use instead, so it doesn't reach 5.

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

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

Annotations only cover safety flags (non-read-only, non-destructive), which the description cannot improve on. The description adds real behavioral context beyond them: per-workspace name uniqueness and the possibility of a `needs_confirmation` response, which warns the agent that creation may not complete in one call.

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

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

Four compact sentences, front-loaded with the definition of a metric, then the constraint, then the trigger, then the caveat. No wasted prose, though the 'offer this' instruction is arguably guidance rather than description.

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

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

For an 8-parameter write tool with no output schema, the description covers the key operational facts an agent needs: uniqueness, confirmation behavior, and the user-intent trigger. It does not explain the approvalId parameter or what a successful response returns, leaving 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 description coverage is 88%, so the schema already documents name, icon, unit, level, drives, workspace, and description in detail. The description only reinforces the name-uniqueness constraint and adds no syntax or format guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a metric — a number the workspace watches') with concrete examples (triage time, weekly signups, cost per run). This clearly separates it from ledger_metrics_update, ledger_metrics_list, and ledger_metrics_archive in the sibling set.

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

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

Explicitly says to check ledger_metrics_list first and why (names are unique per workspace), and gives a trigger condition ('When a user says they want to track or measure something, offer this'). Both the prerequisite and the invocation context are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavior beyond that: readings returned newest first, decisions bound to the metric, labels ordered by largest total, and series summed per bucket. It stops short of disclosing limits, pagination, or error behavior.

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

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

Dense but front-loaded: the identity and return contents lead, followed by usage, then parameter guidance. Every sentence carries information, though the parameter clauses could be tightened slightly.

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

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

With no output schema, the description must carry return-value explanation, and it does (definition fields, readings, decisions, labels, series). A complex tool with a nested slice object is handled well; only edge behaviors like limits or error cases are absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further with worked examples for slice and by ('new users in DE', 'new users by country') and clarifies that either produces a series summed per bucket. That meaning is not fully derivable from the schema text 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 (read one Ledger metric) and enumerates what comes back: the definition fields, readings newest first, and bound open decisions. This is clearly distinguishable from the sibling ledger_metrics_list, which lists many metrics.

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 two concrete use contexts: before answering 'how is X trending?' and before recording a reading against it. It also points to ledger_metrics_list as the source of ids/slugs. No explicit when-not or exclusion cases are given, so it falls just short of the top band.

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 usefully discloses the returned fields (unit, latest reading, open-decision count), which matters since there is no output schema, but says nothing about pagination, ordering, or empty-state 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 tight sentences, front-loaded with what the resource is before the usage triggers. Slightly literary phrasing ('the numbers the workspace watches') costs a little precision but no real bloat.

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

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

With no output schema, the description carries the burden of describing the return shape and does so adequately (unit, latest reading, open-decision count). Combined with fully covered schema parameters and read-only annotations, an agent has enough to call it correctly; pagination/ordering details are the only real 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?

Schema coverage is 100% and the workspace parameter is thoroughly documented in the schema itself (default handling, API-key behavior). The description adds no parameter-level information, 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 characterizes the resource well (tracked metrics, each with unit, latest reading, and bound-decision count), which tells an agent what this returns. It is slightly indirect — it never uses a list verb and does not explicitly distinguish itself from ledger_metrics_get or ledger_metric_presets_list — but the title plus the payload description make the intent unambiguous.

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

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

Gives two concrete triggers: when a user mentions a number that sounds like a tracked metric, and before recording a reading (an implicit check-before-write rule). No alternatives are named, but the when-to-use conditions are specific and 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 only declare it is a non-read-only, non-destructive write. The description adds substantive behavior beyond that: the reading auto-lands as evidence on every open decision bound to the metric, unknown slugs produce not_found rather than silently creating a series, and the call may return needs_confirmation. These are the side effects an agent must anticipate.

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

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

Front-loaded with the core action, then resolution guidance, then the evidence/confirmation behavior. It is dense and parentheses-heavy but every sentence carries operational value; no filler or 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?

No output schema exists, yet the description covers the important return behaviors (evidence attachment, needs_confirmation). For a 9-parameter mutation with nested labels, this is near-complete, though it does not tell the agent what needs_confirmation means for a subsequent retry.

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 already 89%, so the baseline is 3. The description still adds real semantics over the schema: metricId accepts an id or a snake_case slug, createIfMissing mints a 'measure' metric (or 'event' when labels are present), and labels presence switches metric kind. That cross-parameter interaction is not evident from 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?

Specific verb ('Record one observation of a tracked metric') and clearly scoped resource, distinguishing it from ledger_metrics_create/list which it explicitly names for adjacent purposes. An agent immediately knows this writes a single data point rather than defining or reading a metric.

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

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

Explicit routing: use ledger_metrics_list to find a slug, ledger_metrics_create to mint one, or pass createIfMissing to do both, plus the not_found behavior on an unknown slug. It also states the trigger condition ('when a user reports a number ... offer to record it') and the event-metric near-alternative (omit value to count an occurrence).

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 substantial behavior beyond the annotations: idempotency ('safe to repeat and safe after a different starter'), non-destructive merge semantics ('metrics the workspace already has are left as they are'), the empty-start state, and a conditional return ('May return needs_confirmation'). These are exactly the mutation traits an agent needs and are not derivable from the schema or hints.

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

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

Front-loaded with the core action and dense with distinct facts (slugs filter, idempotency, empty state, next step, confirmation return). Every sentence earns its place; slightly list-like but no filler.

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

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

For a mutation tool with no output schema and 75% param coverage, it covers lifecycle, idempotency, and the confirmation return well. The only real gap is that approvalId (the confirmation path) is not tied to the 'needs_confirmation' mention, leaving that flow slightly under-explained.

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

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

Schema coverage is 75% and the schema already documents slugs ('The starter's metrics to keep. Omit for all of them') and starter. The description's 'Pass `slugs` to keep only some' largely restates that. The undocumented approvalId is never explained, so no real value is added over the schema.

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

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

States a specific verb and resource: 'Creates a starter's metrics at their levels and links them.' This is clearly distinct from ledger_metric_starters_list (read) and readable in the name. However it never explicitly contrasts itself with the closely related ledger_metric_presets_adopt, leaving the starter-vs-preset choice to inference.

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 operating context: 'Pass `slugs` to keep only some of its metrics' and 'Adopt only what the user agreed to', plus explicit next steps (connect a source via ledger_feeds_create). It does not state when NOT to use it or name the preset alternative, so it stops short of full routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the read-only safety profile is covered. The description adds that entries are non-persistent starters which adopt via ledger_metric_starters_adopt, but says nothing about output shape or response structure.

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 what the tool returns, then the usage trigger, then the adopt workflow. Slightly dense in the closing 'pick/describe/offer' instruction, but every clause carries actionable information.

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

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

For a no-param read tool with no output schema, the description tells the agent what the trees contain (metric levels, links) and how to act on the result including the adopt hand-off. Missing only a hint of how large/varied the starter catalog is.

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?

Zero parameters, so the baseline is 4; there is nothing for the schema to document and nothing for the description to compensate for. It correctly does not fabricate parameters.

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

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

States a specific verb-resource (starter metric trees by business shape) and screens off the likely-confused sibling ledger_metric_presets_list. An agent knows exactly what comes back: trees of metrics with levels and links.

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: 'Reach for this before ledger_metric_presets_list when a workspace has no metrics yet or asks how its numbers fit together.' It names the alternative, the ordering, and the qualifying condition — nothing 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 a write/destructive, closed-world operation, so the bar is lower — yet the description adds substantial behavior beyond them: partial-update semantics ("Only what you pass changes"), that readings are untouched, conflict-on-rename failure, and a possible needs_confirmation envelope. These are exactly the non-obvious traits an agent needs before invoking a 13-param mutation.

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

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

Front-loaded with the editable facets, then the operational constraints (readings untouched, partial update, slug locked, conflict, confirmation). Dense but every sentence carries distinct information; no filler.

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

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

For a 13-param mutation with no output schema, the description covers the critical gaps: partial update, non-editable slug, conflict behavior, and the needs_confirmation return signal. It does not explain the approvalId/confirmation round-trip in detail, which is the only remaining loose end.

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 85%, so the schema does most of the work (unit, kind, level, drives, target, cadence are all documented inline). The description still adds value by flagging the partial-update contract, the metricId provenance, and the non-editability of slug, which the schema does not 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?

Specific verb+resource ("Corrects a metric's definition") followed by the full list of editable facets, which pins down exactly what this tool mutates versus ledger_metrics_create/archive/record_reading. It also explicitly states what is NOT editable (the slug) and where metricId comes from, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives clear operating context: metricId must be sourced from ledger_metrics_list, the slug is out of scope here, and renames collide with live metrics. It stops short of explicit when-to-use-this-vs-create/archive routing, but the scope statements make the intended usage unambiguous.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond: it discloses that the tool fails with conflict once the decision is settled, may return a needs_confirmation envelope, and that repeatWeeklyUntil writes one row per week capped at 60, each movable.

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 primary alternative, and each sentence carries a distinct decision-relevant fact. It is dense and slightly run-on, but nearly 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?

No output schema exists, and the description supplies the important return signals (conflict on settled decisions, needs_confirmation with a matching approvalId param). For a 13-parameter mutation tool this is close to complete, though a brief note on the success return shape would close the gap.

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

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

Schema coverage is 85%, so the schema already documents most parameters. The description nonetheless adds cross-parameter semantics the schema names only individually: all-day by default unless startTime accompanies timeZone, and the per-week row behavior of repeatWeeklyUntil.

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 ('Adds a plan item to an OPEN decision') and immediately clarifies what a plan item is ('the work that carries it out: a post, a launch step, an email'). It distinguishes itself from ledger_entries_create by explaining when the same date should be recorded as a decision instead.

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

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

Gives explicit routing: use this for work, use ledger_entries_create if the date 'costs money or time and comes with an expectation'. It also names concrete conditions for omitting entryId, using repeatWeeklyUntil, and providing startTime/timeZone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: a conflict failure once the decision is settled, and the possibility of a needs_confirmation response envelope. It stops short of saying whether removal is reversible or what happens to the settled record.

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 short sentences, front-loaded with the action and scope before the alternative and failure modes. Efficient overall, though the alternative-tool sentence is slightly clause-heavy and could be tightened.

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

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

For a destructive mutation with no output schema, the description covers the main behavioral risks: the precondition (open decision), the failure mode, and the confirmation flow. It omits permissions requirements and whether the removal is permanent, but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 67%; workspace and approvalId carry their own descriptions, while itemId is undocumented in the schema. The description ties the needs_confirmation return to the approvalId flow, which adds some meaning, but it never clarifies the itemId format or what identifying a plan item entails. Baseline 3 for partial coverage with modest added value.

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 ('Removes one plan item') and immediately scopes it ('while its decision is open'), which separates it from ledger_plan_add, ledger_plan_list and ledger_plan_update. An agent can identify the operation without opening the schema.

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

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

Gives explicit when-to-use ('added by mistake or work that's no longer planned') and when-not, naming the alternative tool and argument ('prefer ledger_plan_update with status "skipped"') with the reason ('so settlement can see it'). This is a complete routing rule, not an implied one.

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, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds real behavioral context beyond that: the ~1-year maximum window between `from` and `to`, and the fact that results include decision spans and standalone dates with no decision. It does not mention result size or pagination, which matters for a year-wide window.

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

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

One dense block, but front-loaded with the mode-selection rule before the details, and every clause carries information (return shape, window limit, filter intent, exclusion). Slightly long and could be split for readability, but there is little dead weight.

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

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

With no output schema, the description does the work of explaining what comes back — decision spans and every dated item in the window — which is exactly what an agent needs to interpret results. The remaining gap is the absence of any note on result volume or pagination for a window that can span a year.

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 genuine meaning: it establishes that `entryId` and `from`/`to` are alternative modes, restates the YYYY-MM-DD format with the range constraint, and gives `ownerUserId` a purpose ('what's mine this week'). That is more than the schema's terse 'Only items owned by this member'.

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 Ledger calendar or a single decision's plan — and spells out exactly what the two query modes return (decision spans plus every dated item, including standalone dates). It is clearly the read counterpart to ledger_plan_add/update/delete, but it never names those siblings, so the differentiation is implicit rather than explicit.

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

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

Gives explicit routing between the two modes (`entryId` for one decision vs `from`+`to` for the calendar), names concrete situations it answers ('what's mine this week', 'find tomorrow's items to draft'), and adds a hard exclusion — never use it to compare or rank people's output. 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 destructiveHint=true and readOnlyHint=false, but the description adds real behavioral context beyond them: the conflict failure on settled decisions, the possible `needs_confirmation` envelope, and the null-clears semantics for owner. It does not detail permissions or what a partial update leaves untouched.

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, fully front-loaded: core operation first, then the guardrail, then the failure/confirmation behavior. 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 13-parameter destructive mutation with no output schema, the description covers the main edit semantics, the state gate, and the confirmation path, which is what an agent most needs. It stops short of explaining the time-zone/start-end time interaction and the note/tags fields, leaving a small gap.

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

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

Schema coverage is only 46%, so the description must compensate and does for several fields: it maps dueOn to move, title to rename, ownerUserId null to clearing, url to attaching a link, and lists the status enum. However it omits the timing trio (startTime/endTime/timeZone), note, and tags, so meaningful parameters remain undocumented in the description.

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

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

States a specific verb+resource ('Edits one plan item') and enumerates the exact edit operations (move via dueOn, rename, re-own, attach link, set status). This clearly separates it from the ledger_plan_add/delete/list siblings without needing to open their schemas.

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

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

Gives an explicit when ('while its decision is open'), a when-not with the failure mode ('Fails with conflict once the decision is settled'), and a strong operational rule ('Mark done only when the user says it shipped; a link alone doesn't mean done'). Little is left to inference.

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

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

Annotations already declare 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.