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

With no annotations, the description carries the full burden and does state the core behavior: promoting content to the canonical NEXT_STEP.md and requiring owner acknowledgment. However, it omits whether this overwrites existing canonical content or what happens if the optional content is not provided, leaving some behavioral ambiguity.

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

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

A single sentence packs the action, target, input flexibility, and required approvals with no wasted words. Important constraints are front-loaded after the action, making it easy for an agent to parse quickly.

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

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

The description is adequate for a simple approval/promotion action and the output schema removes the need to document return values. But with no annotations and no mention of project_path or the effect on existing NEXT_STEP.md content, the definition leaves notable gaps for an agent to infer.

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 0%, and the description partially compensates by clarifying that owner_ack must be true and reason is required, and by implying content can be provided or taken from an existing proposal. Project_path, however, is never explained, and no format or guidance is given for reason.

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 ('Promote') and a clear resource ('canonical NEXT_STEP.md'), and clarifies that it accepts either proposed or directly provided content. This distinguishes it from siblings like hai_propose_next_step and hai_get_next_step without needing to inspect those tools.

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 preconditions for use: owner_ack must be true and a reason must be supplied. It implies this is the approval/finalization step after content has been proposed, which provides usable context, though it does not explicitly name alternatives or state 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the lease is time-bounded and tied to a specific contract version, but omits side effects, permission requirements, failure modes, idempotency, and what happens on invalid inputs. This is only partial transparency.

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

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

The description is a single front-loaded sentence with no filler. It immediately states the core action and key constraints, which is appropriately concise, even though more detail is needed elsewhere.

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?

This is a 9-parameter, 8-required tool with zero schema parameter descriptions and no annotations, yet the description provides only a high-level summary. An agent cannot construct a correct call because most required parameters are semantically opaque and there is no guidance on expected results, criteria IDs, roles, or return value semantics.

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 0%, so the description must compensate. It adds context for mission_id and contract_version ('exact contract version'), and 'time-bounded' hints at duration_minutes, but it leaves the other seven parameters undocumented. An agent cannot infer the intended meaning of role, contribution, expected_result, criterion_ids, capabilities, or agent_identity.

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

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

The description clearly identifies the action ('Grant') and the resource ('a time-bounded session lease'), and ties it to mission ID and contract version. It is specific enough to distinguish the tool from most siblings, though it does not explicitly name or contrast any alternative.

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 implies it should be used when a session lease needs to be granted, but it gives no guidance on when to prefer this tool over related siblings like hai_open_mission, hai_mission_start, or hai_get_contract. There are no stated prerequisites, exclusions, or alternative 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?

With no annotations, the description must carry the behavioral disclosure burden, and it only reveals that classification is deterministic. It does not state whether the tool has side effects, whether it requires an authorized session, what constitutes valid activity_step values, or what the classification outcome looks like. This is a significant gap for a tool with eight parameters.

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 one short, front-loaded sentence with no wasted words, which satisfies basic conciseness. However, it is under-specified and lacks the structure needed to guide parameter selection or usage; it is concise to a fault rather than effectively condensed.

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?

This is a complex tool with eight parameters, no annotations, and zero schema coverage, yet the description provides no context about required inputs, output semantics, or operational constraints. The presence of an output schema only excuses return-value explanation, not the many other missing operational details. The description is far from complete.

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

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

Schema description coverage is 0%, so the description must compensate for the eight parameters, but it mentions none of them. The agent receives no explanation of session_id, activity_step, evidence, criterion_id, trace_events, or other inputs, making it impossible to invoke the tool correctly based on 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?

The description states a clear verb ('classify') and resource ('planned or observed activity against the mission contract'), which gives the agent a distinct sense of the tool's role. It does not explicitly name sibling differences, so it loses the fifth point, but it is far from tautological or vague.

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 guidance on when to use this tool versus alternatives such as hai_proof, hai_drift_check, or hai_checkpoint. The description implies it is for evaluating activity against a mission contract, but it provides no when-to-use, when-not-to-use, or prerequisite context, leaving the agent to guess.

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?

No annotations are provided, so the description carries the full burden. It discloses the output location and that a snapshot is created, but it does not say whether this is a safe read-only operation, whether ACTIVE_CONTEXT is modified, what happens to existing snapshots, or how project artifacts are selected. This is a significant gap for a tool that writes to disk.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the core action and destination efficiently, though it is terse enough to omit important behavioral and parameter details.

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 annotations, two undocumented parameters, and a write-oriented behavior, the description is incomplete. It leaves the agent to guess when to call it, what the parameters do, and what side effects to expect.

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 0% and neither parameter is explained in the description. 'project_path' is only weakly implied by 'optional project artifacts', and 'note' is completely unexplained. Since there are two parameters and no schema documentation, the description does not compensate.

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 ('Snapshot') and names the resource ('ACTIVE_CONTEXT' plus optional project artifacts) and the destination path. It distinguishes the tool from siblings like hai_park or hai_set_focus, though 'ACTIVE_CONTEXT' is not defined and adds some ambiguity.

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 no guidance on when to use this tool versus alternatives such as hai_park, hai_intake, or hai_distill. The word 'snapshot' implies a checkpointing use case, but there is no explicit context or exclusion criteria.

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 annotations, the description carries the full burden of behavioral disclosure. It reveals that completion requires verified evidence and abandonment requires owner_ack, but it does not disclose side effects, irreversibility, validation rules, or what happens to the mission after closure. This is a significant gap for a state-changing close operation.

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

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

The description is a single efficient sentence with no filler, and it front-loads the two closure modes. However, the extreme brevity creates ambiguity—'Complete' lacks an explicit object and 'reason' is not tied to a schema parameter—so the conciseness comes at the cost of necessary clarity.

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?

This is a 6-parameter tool with 4 required parameters, 0% schema description coverage, no annotations, and no parameter explanations. The description does not mention contract_version, mission_id, outcome_summary, closure values, or the format of evidence, and it provides no guidance for the substantial required inputs. It is not adequate for reliable 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 0%, so the description must compensate by explaining parameters. It does map 'evidence' to verified per-criterion evidence and 'owner_ack' to owner acknowledgement, but it mentions a 'reason' that does not correspond clearly to any parameter, and it ignores required fields like mission_id, contract_version, outcome_summary, and the closure value 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 conveys two distinct closure actions—completing with verified per-criterion evidence or abandoning with owner acknowledgement and reason—so an agent can infer that this tool finalizes a mission in one of two modes. It is clear enough, but it does not explicitly name the mission resource or meaningfully distinguish itself from siblings like hai_stop or hai_recover.

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 two internal closure paths but no guidance on when to use this tool instead of alternatives such as hai_recover, hai_park, or hai_stop. It does not state conditions that should lead an agent to choose another sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key side effect—that the server parks everything else—and emphasizes the exactness of the output. Still, it leaves unclear whether the operation is reversible, what happens to prior state, or which permissions are required.

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 one tight sentence with the key constraint front-loaded. 'EXACTLY' emphasizes the most critical behavioral rule. It is minimally worded but still conveys the tool's primary effect.

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 annotations, the description should provide enough context about parameter usage, side effects, and when to apply it. It discloses the parking side effect but leaves parameter semantics and usage boundaries unexplained, making it incomplete for an agent choosing among many siblings.

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 0%, so parameter meaning is entirely on the description. The description maps to decision and next_step contextually, and 'parks everything else' hints at parklist, but it never explicitly defines intake_id, parklist values, or how the parameters relate to the stated behavior.

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 begins with a specific verb-resource pairing, 'Reduce an intake', and sharpens the expected outcome to exactly one decision and one next step. It also distinguishes itself from sibling tools by noting that the server parks everything else, making its scope distinct from simple park or proposal tools.

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 implies when to use the tool: when an intake needs to be distilled down to a single decision and next step. However, it does not explicitly state when not to use it or compare it with alternatives like hai_park, hai_propose_next_step, or hai_accept_next_step.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It says 'lightweight' and 'thin wrapper', implying minimal behavior and delegation, but it never states whether the operation is read-only, what side effects occur, what the output contains, or what errors or edge cases exist.

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 text is short and front-loaded, but it is not effectively concise because it omits critical information and repeats the 'lightness' idea in two ways ('Lightweight' and 'thin wrapper'). The brevity reduces utility rather than supporting quick comprehension.

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 tool with no annotations and a 0% schema coverage, this description is severely incomplete. It does not explain the meaning of a drift check, the role of the inputs, the return behavior, prerequisites, or how it differs behaviorally from hai_check_activity, making correct invocation unlikely.

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 0% and the description mentions none of the 8 parameters. The agent is left to infer meaning purely from names like session_id and activity_step, with no explanation of criterion_id, trace_events, affected_paths, declares_blocker, or how they relate to the drift check.

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 action ('check against the mission contract') and identifies the tool as a 'thin wrapper' over hai_check_activity, giving agents a rough sense of its place. However, 'mismatch check' and 'drift' remain underspecified about exactly what is being compared and how.

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 only usage hint is 'thin wrapper over hai_check_activity', which hints at a relationship but does not explain when to prefer this tool over hai_check_activity or any of the other siblings. There is no explicit when-to-use, when-not-to-use, or alternative-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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It states that the result is exact and canonical rather than summarized, but it does not disclose whether the operation is read-only, idempotent, or what happens when the session lease is invalid or expired. The agent is left to infer important error and authorization semantics.

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

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

The description is a single, well-structured sentence with no filler. The most important information—what is returned and for which input—is front-loaded, and the contrast with a summary is placed prominently.

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

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

The tool is simple: one required parameter, an output schema exists, and there are no nested objects. The description supplies the essential purpose and the prerequisite of a valid session lease, while the output schema covers return-value details. The main omissions relate to usage alternatives and invalid-lease behavior, which are captured in other dimensions.

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

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

With 0% schema description coverage, the description must compensate. It adds the notion of a 'valid session lease', which helps the agent interpret session_id as a lease identifier that must be valid. However, it does not explain the expected format, how validity is determined, or how to obtain such a lease, so the compensation is partial.

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

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

The description clearly states the action ('Return') and the exact resource ('exact canonical mission contract'), and it distinguishes the result from a summary. It also scopes the call to 'a valid session lease', making the tool's purpose easy to identify among the sibling tools.

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 implicitly tells the agent that a valid session lease is required and warns that the result is not a summary. However, it does not explicitly name alternatives or state when to use another tool such as hai_status, hai_get_next_step, or hai_read_artifacts instead. The usage context is inferable but not fully explicit.

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

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

With no annotations provided, the description carries the full transparency burden. It does convey that this is a read operation and that the tool reports 'none' when no NEXT_STEP.md exists. However, it does not disclose potential side effects, permission requirements, or behavior when the project_path is invalid, so behavioral transparency is only partially addressed.

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

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

The description is a single, efficient sentence with no filler. The primary action and object are front-loaded, and the fallback behavior is included in a compact parenthetical.

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 read operation with one parameter and an output schema, the description is reasonably complete. However, the absence of annotations and parameter-level schema descriptions leaves some gaps around behavior with missing or invalid paths and around how this tool relates to next-step lifecycle siblings, so it is only minimally viable rather than fully complete.

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

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

Schema description coverage is 0%, and the description adds minimal parameter meaning beyond echoing the schema's 'project_path'. Saying 'for a project' does not clarify expected path format, whether it should be absolute or relative, or how the path relates to locating NEXT_STEP.md. The description does not compensate for the schema's lack of parameter documentation.

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

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

The description states a specific verb ('Read'), a specific resource ('the canonical NEXT_STEP.md'), and a scope ('for a project'), with an explicit fallback behavior ('or report none'). This makes its purpose clear and distinguishes it from write-oriented siblings like hai_propose_next_step and hai_accept_next_step.

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

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

The description implies the tool is for retrieving the current next step, but it gives no explicit guidance on when to use it versus alternatives, nor does it name any sibling or exclusion condition. The agent is left to infer usage context from the tool name and sibling list.

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

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

With no annotations, the description carries the burden of disclosing behavior. It directly states 'No model calls,' which meaningfully signals a non-model, likely read-only operation. It does not fully explain what 'project path usability' entails or whether any state is touched, but the health-check framing and explicit no-model-call statement provide solid transparency.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase earns its place: the action, the resource, the optional parameter role, and the key behavioral disclaimer 'No model calls.'

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 one optional parameter and an output schema, the description is mostly complete: it states purpose, safety behavior, and the parameter's role. The main gap is the lack of differentiation from the similarly named hai_status tool, but that is a sibling-selection issue rather than a functional completeness issue.

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 schema provides no parameter description, so the description must compensate. It adds that project_path is optional and tied to 'usability' checking, which is helpful. However, it does not explain what makes a path usable, expected formats, or how the path affects the health check.

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 action and resource ('Check HAI-MCP server health') and clarifies scope with 'No model calls.' It is clear, but because there is a sibling tool named hai_status, it does not explicitly differentiate this health check from the status check.

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 no guidance about when to use this tool versus alternatives such as hai_status or the other sibling tools. 'No model calls' implies a safe diagnostic use, but there are no explicit conditions, exclusions, or routing hints.

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 annotations, the description carries the full burden and answers the key behavioral questions: the write is immutable, the only return value is an intake id, and there are no side effects such as starting an agent. This goes well beyond what the raw schema alone conveys.

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

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

Two sentences with no filler, and the core behavior and boundaries are front-loaded. Every clause adds information: immutability, return shape, and non-actionability.

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

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

For a one-parameter intake tool with an output schema and no annotations, the description covers purpose, behavior, return shape, and side-effect boundaries. It could be slightly stronger by naming sibling alternatives, but nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must add meaning for the sole parameter. 'Capture a raw thought' clearly maps the required 'raw' field to the thought content, which is sufficient for a single string argument. It omits length or format constraints, but those are not essential for this simple intake.

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 identifies a specific action ('capture'), a specific object ('a raw thought'), and a defining property ('immutably'). It also explicitly disclaims actionability and agent startup, which distinguishes it from sibling tools like hai_propose_next_step or hai_mission_start.

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 clearly implies the use case: persist an unprocessed thought for later without triggering action. It includes when-not-to-use guidance ('never actionable, never starts an agent'), but it does not name alternative tools or state explicit conditions for choosing among siblings.

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

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

With no annotations, the description carries the full burden, and it discloses only that the tool is a thin wrapper over hai_open_mission. It does not state the side effects of starting a mission, any permissions needed, or reversibility, which is significant for a start 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?

Two short sentences with the core purpose front-loaded and zero filler. The compact size is appropriate for a simple wrapper tool.

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 tool with no parameter descriptions and no annotations, the description is too thin. It provides the key wrapper relationship but fails to cover required fields and behavioral effects, so an agent cannot reliably invoke it correctly from this text alone.

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 0%, so the description must compensate, but it only mentions problem, artifact, and time limit. It omits two required parameters (owner, done_criteria) and gives no semantics for non_goals or constraints, leaving agents undersupported.

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 (fast start of a mission) and precise inputs (problem, artifact, time limit), and explicitly distinguishes itself from hai_open_mission as a thin wrapper. An agent can tell this is the quick variant without opening the schema.

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

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

It frames when this tool is appropriate ('Fast start') and names hai_open_mission as the canonical contract it wraps, implying the alternative for full control. However, it does not explicitly state when to avoid this tool or switch to another sibling.

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 annotations, the description must carry the full behavioral burden. It discloses that only one active mission is allowed globally, which is useful, but it does not describe side effects, whether an existing mission is replaced or rejected, required prior states, or any mutation/safety implications of opening a mission.

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 very short and front-loaded, with no filler. The first sentence gives the core purpose and the second adds a critical constraint. It is concise without being wordy, though the jargon 'bounded mission' and 'versioned canonical contract' could be clarified without much added 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?

Given the number of parameters, the existence of an output schema, and many sibling lifecycle tools, the description is too thin to fully orient an agent. It does not cover parameter semantics, prerequisite states, conflict handling with the global mission constraint, or how this tool relates to close/park/recontract operations.

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 0%, and the description adds no meaning to any of the six parameters. Terms like 'objective,' 'artifact,' and 'done_criteria' are present only as names in the schema; the description does not clarify what 'artifact' means, how constraints or non_goals are used, or how the parameters relate to the 'versioned canonical contract.'

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

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

The description clearly states the action ('Open'), the resource ('a bounded mission with a versioned canonical contract'), and a key constraint ('One active mission globally'). This distinguishes it from many sibling tools at a high level, though it could more explicitly contrast with tools like hai_mission_start or hai_recontract.

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 no direct guidance on when to use this tool versus alternatives, no prerequisites, and no mention of what should happen if a mission is already active. The global-uniqueness statement implies a usage condition but does not explain how to proceed in that case.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key behavioral trait: the operation does not change ACTIVE lanes and parks the item in the inbox. However, it does not describe any other side effects, such as whether the item is appended, deduplicated, or returned, which leaves some transparency gaps.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes: the action, the destination, and the constraint are all communicated efficiently.

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 tool with an output schema, the description is adequate but minimal. It gives the core operation and a key constraint, but it omits usage conditions, sibling differentiation, and any description of the optional tags parameter. The presence of an output schema reduces the need to explain return values, but the behavioral and usage gaps remain.

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 0%, so the description must compensate for parameter meaning. It loosely maps the 'text' parameter by calling the item a 'thought/meta item', but it says nothing about the optional 'tags' parameter or how it should be used. This is partial compensation at best.

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 ('Park') with a clear resource ('a thought/meta item in HAI inbox') and adds a meaningful scope constraint ('without changing ACTIVE lanes'). It is clear, but it does not explicitly differentiate this tool from the similarly named sibling hai_park_item, so it misses the top score for sibling distinction.

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 phrase 'without changing ACTIVE lanes' implies when this tool is appropriate: when the agent wants to park an item without affecting active lanes. However, there is no explicit when/when-not guidance or mention of alternatives such as hai_park_item or hai_intake, so usage context is only implied.

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

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

Since no annotations are provided, the description carries the full burden. It discloses two key behavioral traits: 'Grants no execution right' and 'contract unchanged', which signal that the tool won't alter execution or contract state. However, it does not clarify persistence, authorization requirements, or what 'park' actually does beyond these constraints.

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

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

Two sentences with no redundancy, the primary action is front-loaded, and each sentence contributes necessary information. This is appropriately 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?

For a tool with 5 required parameters and no annotations, the description is too sparse. It does not explain parameter semantics, differentiate among siblings, or describe operational side effects beyond contract and execution, leaving the agent to guess how to correctly populate the call.

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 0% across 5 required parameters, and the description adds no parameter-level meaning. It mentions 'full context' but never explains what idea, rationale, mission_id, trigger_event, or origin_session_id should contain or how they relate.

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 ('Park') and a clear resource ('mission-linked idea') and adds the scope 'with full context'. It also differentiates from execution-oriented siblings by stating it grants no execution right, though it does not explicitly distinguish itself from the similarly-named hai_park sibling.

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

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

The description implies when to use it: to store a mission-linked idea with full context while intentionally avoiding execution or contract changes. However, it provides no explicit alternatives, exclusions, or comparison to siblings like hai_park, hai_intake, or hai_propose_next_step.

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

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

With no annotations provided, the description carries the full behavioral burden. It communicates that this is a wrapper and operates on a completed mission, but it does not disclose side effects, irreversibility, permission requirements, or what happens if evidence is missing. For a state-changing closing operation, this is a notable gap.

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

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

The description is two short sentences with no filler. The core action and condition are front-loaded, and the wrapper relationship is stated economically. 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?

The output schema exists, so return values do not need explanation. However, the tool has four required parameters, no annotations, and a nested evidence object, yet the description only vaguely covers evidence and mission closing. It omits guidance on contract_version and outcome_summary, and provides no safety or prerequisite context for a destructive closing action.

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 0%, so the description must compensate for parameter meaning. It adds some meaning by describing evidence as 'verified per-criterion' and implies mission_id through 'close a mission,' but it says nothing about contract_version or outcome_summary, leaving two required parameters semantically opaque.

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: 'Close a mission' with a precise condition, 'only against verified per-criterion evidence.' It also distinguishes itself from siblings by explicitly positioning itself as a thin wrapper over hai_close_mission, so an agent understands its specialized role.

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 phrase 'only against verified per-criterion evidence' gives a clear usage condition and implicitly warns not to use it without such evidence. It names the underlying alternative hai_close_mission, but does not explicitly spell out when to choose that alternative versus hai_proof.

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 annotations, the description carries the behavioral disclosure burden. It does reveal that the tool writes a proposed artifact and that the result is not canonical, which is useful. However, it does not disclose overwrite behavior, required permissions, or other side 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?

Two short sentences with no filler or repetition. The main action is front-loaded first, and the workflow pointer follows naturally, making the description easy to parse.

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

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

The tool is simple with only two parameters and an output schema, so return-value documentation is not necessary. Still, the absence of any parameter explanation and minimal behavioral detail leaves the description only minimally complete for an agent deciding how to invoke it safely and 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 0% and the description adds almost nothing about the two required parameters, project_path and content. The 'NEXT_STEP.proposed.md' filename only weakly implies that content is the file body and project_path is the write location, which is not enough to compensate for the missing schema documentation.

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

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

The description names a specific action, 'Write NEXT_STEP.proposed.md', and clarifies the artifact's non-canonical status, which distinguishes it from final/accept operations. It also references the sibling promotion tool, so an agent can tell this tool apart from hai_accept_next_step.

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

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

The description gives clear workflow context: propose first, then promote via hai_accept_next_step. The 'not canonical' note provides an implicit exclusion against using this as the final acceptance step, though it does not enumerate alternative tools such as hai_get_next_step.

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

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

The description explicitly states 'Read-only,' which is a meaningful behavioral guarantee especially since no annotations are provided. However, it does not disclose truncation behavior related to max_chars, access requirements, or failure behavior, so it only partially carries the transparency burden.

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 one concise sentence with no filler, and the read-only nature is front-loaded. It is appropriately compact, though additional useful guidance is missing elsewhere.

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 output schema may cover return shape, but the description leaves key selection and parameter semantics unstated. With a large sibling set and zero schema-level parameter descriptions, this is not enough for reliable invocation without further assumptions.

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 0% and the description does not explain project_path or max_chars beyond their names. 'project_path' is somewhat self-explanatory, but no description compensates for the complete lack of parameter documentation in the schema.

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

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

The description names a specific operation ('read-only summary') and a resource ('HAI Projek-Managment run-contract artifacts'), so an agent can infer the tool returns artifact summaries without opening the schema. It does not explicitly differentiate from siblings such as hai_get_contract, but it is still substantially clearer than a vague or tautological description.

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?

No when-to-use or alternative-selection guidance is provided. The description never mentions conditions for choosing hai_read_artifacts over hai_get_contract or other siblings, leaving the choice to inference despite the large sibling tool list.

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

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

With no annotations, the description carries the burden, and it discloses a major side effect ('revokes all leases') plus an authorization prerequisite (owner_ack=true). It does not mention irreversibility, failure behavior, or whether break_glass_marker bypasses the ack, but it is far more transparent than most tool descriptions.

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

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

Two sentences with no filler: the action is front-loaded, and the required condition and dominant side effect follow immediately. 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?

Given 7 parameters, 4 required, a nested changes object, and no annotations, the definition is too thin. It correctly highlights the main risk (lease revocation) but leaves break_glass_marker, mode, reason, and contract_version semantics unexplained, and offers no sequencing or alternative tool context.

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 0%, so the description must compensate, but it only clarifies owner_ack (must be true) and loosely implies changes is the diff. mission_id, contract_version, reason, mode, and break_glass_marker remain unexplained, which is a significant gap for a 7-parameter 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?

Description uses a specific verb ('Apply') and resource ('visible field-level contract diff'), and adds decisive constraints: owner_ack must be true and all leases are revoked. It reads as a mutation distinct from read-only siblings like hai_get_contract, though it does not name an alternative explicitly.

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

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

It implies the tool should be used when you need to apply a field-level contract diff, and it states a hard precondition (owner_ack=true). However, it gives no when-not-to-use guidance, no context about sequencing with sibling tools, and no discussion of the break_glass or park/checkpoint 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly labels the operation as 'read-only advice', which tells the agent it will not mutate state. It does not define what 'smallest' means or describe error behavior, but for a simple read-only tool this is a strong 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?

The description is a single sentence with no filler. The verb and primary object are front-loaded, and the parenthetical 'read-only advice' adds essential safety context without bloating the definition.

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

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

For a one-parameter read-only tool, the description covers the main action, source selection, and safety profile, and an output schema exists to define return values. Minor gaps remain around explicit null-to-latest behavior and the exact meaning of 'smallest', but these are not blocking.

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 0%, so the description must compensate. The phrase 'latest or named checkpoint' maps naturally to the optional checkpoint_id parameter: omit it for latest, supply it for a named checkpoint. The mapping is not stated explicitly, but it is strongly implied.

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: 'Return the smallest recovery next action' from 'latest or named checkpoint'. The 'recovery' qualifier and 'read-only advice' framing distinguish it clearly from sibling tools like hai_get_next_step or hai_propose_next_step.

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

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

The description implies the tool should be used when the agent needs recovery advice based on a checkpoint, and it clarifies the source as latest or named. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tools.

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?

The description discloses a key behavior beyond the schema: registering an ACTIVE lane is limited to 2, and a third request fails. However, with no annotations, it does not explain side effects, whether existing focus is replaced, or what 'lane' means operationally.

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 front-loaded sentence states the core operation and its critical constraint with no filler. Every word earns its place.

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

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

With three parameters, no annotations, and many lifecycle-focused siblings, the description omits when to call it, how active lanes are relinquished, and what happens to prior focus. The output schema may cover return values, but operational context remains thin.

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 0%, and the description does not explain focus_id, label, or project_path. The names are suggestive, but the description adds no parameter-specific meaning to compensate for the absent schema descriptions.

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

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

States a specific action—'Set focus'—and clarifies it also registers an ACTIVE lane with an explicit max of 2. The failure condition on a third ACTIVE request adds useful specificity, though it does not explicitly name or differentiate against sibling tools.

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?

No guidance is given on when to use this tool instead of sibling tools like hai_park, hai_recover, or hai_status. The max-2/failure statement is a behavioral constraint, not usage context or exclusion criteria.

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 annotations, the description carries the behavioral disclosure burden. It signals a read-oriented query ('Return'), indicates only ACTIVE lanes are included, and hints at optional project-specific behavior; however it does not state side effects, permissions, or null-handling 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?

A single front-loaded sentence with no filler. Every phrase ('ACTIVE', 'focus', 'inbox count', 'optional project next-step flags') carries semantic 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 simple status-read tool with an output schema and one optional parameter, the description covers the main return surface. It falls short on situating the tool among 22 siblings and on spelling out the effect of project_path, so it is only minimally 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 schema provides only a nullable project_path with a default of null. The description adds that this parameter is optional and related to project next-step flags, which is genuinely useful. It still does not explain path format or exactly how absent versus present values change the response.

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 ('Return') and concrete resource components ('ACTIVE lanes, focus, inbox count, and optional project next-step flags'), making the tool's purpose clear. It does not explicitly contrast with siblings such as hai_health or hai_get_next_step, so it misses the top-level differentiator.

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 guidance on when to call hai_status instead of one of its many siblings. The description implies a status-overview use case but never states conditions, exclusions, or alternatives, leaving routing 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?

With no annotations, the description carries the full behavioral burden, and it discloses the key observable effects: it records the answers, invalidates active leases, creates no next-day plan, and leaves missions open. This is specific and useful, though it could add details on prerequisites or reversibility.

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 short and front-loaded, with every clause adding a distinct fact. It sacrifices a little clarity for brevity, but it is efficiently 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?

Despite having an output schema, the tool still lacks enough context for correct invocation: the meaning of 'clearer' and 'agency_gained' and the expected content of the answers are unexplained. For a 4-parameter fully-required tool with no annotations, this is a significant gap.

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

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

Schema description coverage is 0%, and the description only hints that loop_closed, clearer, and agency_gained are 'the three answers' without defining them. An agent cannot reliably construct these arguments from the available text; the description does not compensate for the empty schema descriptions.

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

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

The description names a specific operation ('record the three answers', 'invalidate active leases') and clearly identifies it as the hard-day terminal action. It also distinguishes itself from siblings by stating 'no next-day plan' and 'Missions are not closed', which sets it apart from propose_next_step and close_mission.

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 phrase 'Hard day terminal' gives clear context for when this applies, and the exclusions ('no next-day plan', 'Missions are not closed') tell the agent what it does not do. It does not explicitly name sibling alternatives, but the boundaries are inferable from the tool's sibling set.

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