continuity

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

The description discloses important behavioral semantics beyond the annotations: near-identical claims are skipped rather than duplicated, superseding archives the old claim instead of deleting it, frozen-claim contradictions are parked for human review, and the operation is append-only. This goes well beyond the annotations, which only indicate mutation and non-idempotence, and directly shapes how an agent should reason about effects.

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

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

The description is dense but every sentence adds operational value: purpose, usage guidance, reconciler semantics, safety guarantee, and prerequisite. It front-loads the core action and differentiator before explaining behavior. No filler undermines the message.

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

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

The description covers prerequisites, batching rationale, side-effect behavior, and safety boundaries, making the tool callable with good judgment. The main gap is that it does not describe the return/response shape, especially per-operation outcomes like applied, skipped, parked, or rejected. Given no output schema, a brief note about what the call returns would make it 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?

The input schema already covers all parameters at 100%, so the baseline is 3. The description adds useful context beyond the schema, such as the dedupe-skip behavior, the append-only guarantee, and the need to call resume_context first to resolve ids and frozen states. It does not repeat parameter syntax, which is appropriate given the schema's richness.

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 ('Apply a BATCH of claim operations'), a resource ('claim operations'), and a process ('through the reconciler'). It also distinguishes itself from sibling record_* calls by emphasizing batch scope. The title alone is vague, but the description resolves that ambiguity completely.

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

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

The description explicitly says to prefer this over several record_* calls when a turn produced more than one thing, giving a clear selection criterion. It also provides a prerequisite: call resume_context first so the agent knows existing ids and frozen claims. This is actionable, concrete 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 idempotentHint=true and destructiveHint=false, and the description adds concrete behavioral detail: what gets created (directory, initial git commit), that existing claims are untouched, and that the tool is not appropriate inside an existing git repo. This goes well beyond the annotations.

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

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

Three sentences with a clear progression: action/effect, safety behavior, usage constraint. Each sentence earns its place, though the idempotency statement is slightly expanded by rephrasing what the annotation already conveys.

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 create tool with good annotations and no output schema, the description covers the essential context: side effects, idempotency, mode restriction, and the alternative setup path. Minor gap: no explicit statement of what the tool returns or signals on success, but that is not critical for 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% — both parameters are well documented in the schema itself. The description does not add new parameter-level meaning but also does not need to; the baseline of 3 applies.

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

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

States a specific verb ('Create or initialize'), resource ('named project in the central store'), and concrete effects ('Creates a directory and an initial git commit'). Clearly distinguishable from sibling tools like list_projects or capture, which serve entirely different purposes.

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 limits usage to central mode ('hosts with no project directory') and names the alternative ('continuity init CLI') for git-repo contexts. Also explains that calling on an existing name is safe, removing ambiguity about idempotent re-invocation.

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

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

Beyond the idempotentHint annotation, the description reveals consequential behavior: freezing prevents autonomous capture from superseding the claim, routes contradicting claims to human review, and requires resolve_claim with unfreeze to override. These are meaningful behavioral details not inferable from the schema or 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?

The description is tight and every sentence carries weight: definition, strict usage guard, consequence, override path, and idempotence. It is front-loaded with the core purpose and no filler or repetitive 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 consequential mutation tool with no output schema, the description covers the full call decision: when to use it, what effect it has on future captures, how contradictions are handled, and how to reverse it. Combined with the complete schema, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already explains id and project, including the substring matching behavior for id. The description adds context about what a 'claim' is but does not add parameter-level guidance beyond what the schema provides, 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?

The description uses a specific verb and resource ('Mark a claim frozen') and defines what frozen means: an invariant that must never change. It also differentiates itself from siblings by calling this 'the one deliberate lock in the model' and referencing resolve_claim for unfreezing, so an agent can distinguish it from capture or record_constraint.

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 explicitly when to invoke the tool ('ONLY when the user explicitly asks for something to be locked') and when not to ('never on your own initiative'). It also points to the alternative for undoing the operation later: resolve_claim with unfreeze, which is also an explicit human decision.

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 idempotentHint=true, so the description's 'Read-only; writes nothing' is non-contradictory repetition. It adds useful behavioral context by clarifying the tool only inspects the central store and does not incorporate working-directory state, which is valuable beyond the annotations.

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

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

Three sentences, each earning its place: the first states the action and target, the second reinforces safety and when to use it, and the third scopes out the main alternative context. No filler or redundancy.

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

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

For a simple, parameterless list tool, the description fully covers what an agent needs: the source of data, the read-only safety profile, the conditions for invocation, and the context in which it should be avoided. The absence of an output schema is acceptable because the behavior 'List the named projects' sufficiently implies the return shape.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly avoids inventing parameter details and instead explains what the tool operates on, which is sufficient for a parameterless tool.

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

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

The description names a specific verb ('List'), a specific resource (named projects in the central store), and the exact location (~/.continuity/projects). It also distinguishes this tool from working-directory-based state, making its purpose unmistakable even among siblings.

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

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

Explicitly states when to use it: when the user names an unseen project or when checking whether central mode holds any state. It also states when it is usually irrelevant (inside a repo with .continuity/), giving clear guidance on when not to use it.

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 signal this is a non-read, non-idempotent operation, and the description adds concrete behavioral detail beyond that: 'one file, one commit, append-only.' This tells the agent what the side effect looks like without contradicting 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?

Three sentences with no filler. The core action is front-loaded, persistence behavior is stated compactly, and the sibling distinction is placed at the end. Every sentence earns its place.

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

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

For a 3-parameter tool with full schema coverage, the description provides the essential behavioral context and sibling guidance. It does not describe the return value, but there is no output schema and the tool's side-effect model is already clear enough for correct invocation.

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

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

Schema description coverage is 100%, and the schema already explains title, body, and project with meaningful guidance. The description does not repeat or add parameter-level semantics, so it earns the baseline score rather than higher.

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

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

The description opens with a specific verb and resource ('Append a constraint that future work must respect') and clearly distinguishes constraints from decisions by defining them as boundaries rather than choices. It also references freeze_claim as the closely related sibling, so an agent can disambiguate without opening other 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 gives an explicit routing instruction: 'Use freeze_claim only if the user wants it to become unchangeable.' It also positions the tool relative to record_decision via the persistence note, making the when-to-use call 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?

Discloses behavior beyond annotations: writes a markdown file plus a git commit, nothing is overwritten or removed, the decision appears in every future resume context, and no permission is needed. These details enrich the minimal readOnly/destructive hints without contradicting them.

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 with no filler. The primary action is front-loaded, and each sentence adds meaningful context: what it writes, safety properties, and usage criteria. Highly concise and well structured.

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

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

Covers the core aspects an agent needs: action, side effects, when to use, and correction mechanism. Missing some details like output format or error conditions, but with full schema coverage and no output schema, it is sufficiently complete for correct invocation.

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

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

The input schema fully describes all four parameters (100% coverage), so the baseline is 3. The tool description itself does not add extra parameter meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Append a decision the user has settled.' It clearly identifies the tool's function and distinguishes it from the record_* siblings by focusing on decisions, though it does not explicitly contrast with alternatives like record_constraint.

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

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

Provides explicit when-to-use guidance: 'Capture autonomously as you observe it — no permission needed — but only for things a future session could not re-derive; skip restatements and progress narration.' This tells an agent when to invoke it and what to avoid, though it does not name alternative tools for other record types.

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

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

Beyond the annotations, the description discloses key behaviors: creation if none exists, replacement requiring a reason, superseding rather than overwriting, archival of the previous mission as a claim, and no-op on identical text. These details are consistent with the idempotentHint=true and destructiveHint=false annotations, and they add meaningful behavioral context.

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

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

The description is dense but well organized: purpose, core behavior, edge cases, and routing to alternatives all appear in a logical order without redundant phrasing. Every sentence contributes either a behavioral rule or selection guidance.

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

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

For a tool with four parameters and no output schema, the description is complete: it covers the core operation, edge cases, required inputs for replacement, store/repo behavior, and sibling-tool selection. No critical information an agent needs 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?

Input schema coverage is 100% with solid per-parameter descriptions, so the baseline is 3. The description adds value by clarifying when reason is required, how the project parameter is resolved in a repo, and that the previous mission travels as a claim with the reason, which enriches the meaning of reason and project beyond 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?

The description opens with a specific verb and resource: 'Set or replace the project's mission', then defines exactly what the mission is (the single line at the top of every resume context). It clearly distinguishes this tool from siblings by naming capture and create_project as alternatives, so an agent can select it confidently.

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

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

The description gives explicit when-to-use guidance: use this rather than capture with type mission, and use create_project instead only when the project does not exist yet. It also states the required-reason rule for replacement and the project-omission rule inside a repo, leaving no ambiguity about invocation context.

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

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

Annotations declare destructiveHint=false, readOnlyHint=false, idempotentHint=false, and openWorldHint=false, which establishes this as a non-destructive non-idempotent write. The description adds valuable behavioral context beyond annotations: items persist with status 'open', a new next_action does not retire the old one, and body length is constrained because it renders in the resume header. It could mention the exact overwrite/supersession mechanics more explicitly, but the description meaningfully extends the annotation signal.

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

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

Three dense sentences with zero filler. The core purpose is front-loaded, behavioral constraints follow, and the supersede guidance is placed last. Every clause earns its place — the body-rendering note, the one-at-a-time display rule, the non-retirement warning, and the resolve_claim relationship all convey distinct, non-redundant information. Nothing could be cut without losing meaning.

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

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

Given that annotations already declare the write-operation profile and the schema covers 100% of parameters, the description covers the essential agent needs: what to record, how items behave over time, and what alternatives exist. It is slightly pessimistic to require more given no output schema exists and the tool is simple (4 flat params, no nesting). A small gap is that it doesn't state what the return value is or confirm success, but for a simple append-style tool this is minor.

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

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

Schema coverage is 100%, so the schema already documents all four parameters thoroughly, including the enum values and their meanings in the type property. The description adds marginal value by clarifying the body's rendering impact ('rendered in the resume header') and the next_action display behavior, but most parameter semantics are already in the schema. Baseline 3 is appropriate when the schema carries the weight.

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 precise verb and resource: 'Append an open question, risk, milestone or next action.' It enumerates the exact item types, clearly distinguishing this from sibling tools like record_decision, record_constraint, and record_rejection. The status 'open' semantics and relationship to resolve_claim are made explicit, so an agent can tell this tool apart from its siblings 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?

The description gives explicit usage context: these items keep surfacing in resume context until closed with resolve_claim, and it warns about the one-milestone/one-next-action display behavior. It also names the alternative approach ('supersede it via capture when direction changes') for retiring an old next_action, providing clear when-to-use and when-not-to-use guidance.

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

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

With no protective annotations, the description carries the burden and does well: it discloses append-only behavior, persistence across future resume contexts, and the permanent 'Do NOT revisit' classification. This goes beyond what annotations provide.

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 written sentences with no filler. The core action is front-loaded, and the behavioral consequence is explained in the second sentence.

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

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

For an append-only record tool without an output schema, the description covers what the tool does, its lasting effect, and how it groups with sibling record_* tools. Missing a note on return value or idempotency, but neither is critical for correct invocation.

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

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

Schema description coverage is 100%, and the schema already explains title, reason, and project in detail. The description restates the conceptual pairing of the rejection and reason but adds no new parameter-level meaning beyond the schema.

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

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

States a specific verb ('Append'), a distinct resource (an alternative that was considered and rejected), and the unique outcome (listed under 'Do NOT revisit'). The purpose is immediately clear and does not rely on the title.

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

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

The description gives clear context: use it for rejected alternatives so they are not re-proposed. It does not explicitly name record_decision or record_constraint as alternatives or state when not to use it, but the semantic boundaries are inferable from the stated purpose.

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?

Even though annotations already mark destructiveHint=true and readOnlyHint=false, the description adds substantial behavioral detail: 'Nothing is deleted; closing archives,' accept 'superseding whatever it conflicted with,' reject turns the claim into a guardrail 'so it is never re-proposed,' and accepting against a FROZEN claim is 'refused rather than silently overriding.' This goes well beyond what the annotations convey and clarifies the exact nature of the destructive action.

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

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

The description is dense but every sentence earns its place. It uses 'Two uses' as a clear structural marker, front-loads the core action, and then covers each call pattern, the mandatory reason, archival behavior, and the frozen-claim caveat without fluff. The length is justified by the tool's real complexity.

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

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

For a tool with two call patterns, a three-value enum, and a frozen-claim edge case, the description is complete. It covers accept, reject, and close, explains the mandatory reason, states that nothing is deleted, and specifies when unfreeze is required. Since all parameter details are in the schema and there is no output schema, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, with all five parameters already documented, so the baseline is 3. The description reinforces that reason is mandatory and that unfreeze requires explicit user consent, but it does not add parameter-level meaning beyond what the input schema already provides. It correctly emphasizes the reason's purpose for future sessions, but that is contextual rather than new parameter semantics.

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

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

The description opens with a specific verb and resource: 'Close a claim, recording WHY.' It then enumerates two distinct uses — parked claims (accept/reject) and open risks/questions/actions (close) — which clearly separates it from siblings like record_rejection, record_open, and freeze_claim. This is far beyond a tautology and gives an agent a precise mental model.

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

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

The description gives explicit when-to-use guidance: parked needs_review claims take accept or reject, while dealt-with open items take close. It also adds an exclusion ('accept applies only to a parked claim') and a frozen-claim precondition requiring the user's go-ahead. However, it never names sibling tools as alternatives, so an agent must infer when record_decision or record_rejection would be more appropriate.

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: determinism ('No model runs in this path, so the same state always yields the same text'), output budgeting (roughly 16KB with explicit trim notice), and 'Read-only; writes nothing' reinforcing readOnlyHint. No contradiction with the provided 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?

Dense but each sentence earns its place — purpose first, then safety/determinism guarantees, then usage authority, then budget behavior. Slightly long but tightly packed with non-redundant 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?

No output schema exists, so the description carries the return contract explicitly by enumerating every field in the projection and the trim behavior. For a single-optional-parameter read tool this is complete; nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents the optional project parameter including the .continuity/ discovery fallback. The description adds no param detail, which is fine since the schema carries the full burden; 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?

Specific verb ('Return') plus a clearly enumerated resource: project state as a deterministic projection listing mission, milestone, next step, frozen constraints, active decisions, rejected alternatives, parked conflicts, and open questions. This fully distinguishes it from the record_*/create_* mutation siblings without opening any schema.

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

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

Explicitly instructs 'Call this FIRST when starting work on an ongoing project' and gives authority rules ('frozen items and rejected alternatives are authoritative, not suggestions'). It doesn't name alternatives by exclusion, but the contrast with sibling write tools is implied clearly enough.

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 readOnlyHint and idempotentHint annotations, the description details the return sequence, the explicit 'supersedes nothing' behavior, the blank-result meaning, and the ambiguity/no-match handling. This is substantial behavioral disclosure that helps an agent interpret results 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?

The description is longer than minimal but every sentence adds value: purpose, return format, edge cases, input semantics, and usage context. It is front-loaded and well-organized, though a few clauses could be tightened without losing meaning.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values and failure modes. It covers current title/status, predecessor lines, closing reasons, empty-history semantics, lookup failure, and ambiguity. For a read-only lookup tool, nothing essential is missing.

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

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

The input schema already documents both parameters fully (100% coverage), and the description adds meaningful semantics: substring matching is case-insensitive, ambiguous substrings return candidate ids, and no match is reported explicitly. This goes beyond the schema and prevents incorrect assumptions.

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

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

The description opens with 'Explain a claim's history,' a specific verb and resource, and clarifies it is read-only. It clearly separates this tool from the write-oriented siblings like record_decision, freeze_claim, and resolve_claim, and from list_projects.

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

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

The description gives explicit guidance: 'Call it before re-opening anything that looks settled' and explains why the history matters. It does not name alternatives or state when not to use it, but the context is clear enough for an agent to route correctly.

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