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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral context beyond them: selection is probabilistic, produces a probability distribution and a utility margin, and depends on active utility profiles. It does not explain how state_pack or utility_profile resolution affects determinism, which is the one remaining 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?

Three sentences, correctly front-loaded with the core action and the sibling-differentiation rule. The return values are stated twice ('with probability distribution and utility margin' and 'Returns selected option ID, probability distribution, and utility margin'), which is redundant but not damaging.

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

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

With no output schema, the description usefully enumerates return values, which is necessary. However, for a tool with nested objects and a 5-parameter signature involving an opaque 'StatePack' and 'utility_profile override', the description never explains what those are or how they influence the choice, leaving conceptual gaps for a non-obvious domain.

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 carries parameter meaning and the baseline is 3. The description restates the 16-option cap (already expressed as maxItems and in the schema text) and adds nothing further about 'project', 'state_pack', or 'utility_profile'.

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

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

States a specific verb and resource ('Select 1 option from a discrete set of alternatives') and adds the scope constraint 'N <= 16' plus what it produces. It explicitly distinguishes itself from the sibling 'classify' by contrasting decision-under-utility with entity categorization.

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

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

Gives an explicit selection rule: use ask_choice rather than classify 'when choosing the best action or alternative under active utility profiles rather than categorizing an entity.' That covers the most confusable sibling, but other decision-oriented siblings (ask_score, ask_noul, evaluate_situation) are not addressed, so the routing guidance is clear yet incomplete.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: the result is calibrated rather than a raw score, it carries abstain safeguards, and it includes a confidence probability. It does not say when abstention triggers or how the prior influences the result, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the action and scope, followed by the sibling-routing rule and the return shape. Every sentence carries distinct information with no repetition of the schema.

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

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

With no output schema, the description compensates by naming the return fields (boolean answer, confidence, abstain flag), and it covers the key sibling alternative. Minor gaps remain around how abstention is decided and how the optional explicit state_pack relates to the 'current' one, but nothing blocking 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%, so the schema already documents project, statement, prior and state_pack. The description adds only the notion of a 'current state pack' and nothing about the prior's role or the expected statement phrasing, so it sits at the baseline for a fully documented schema.

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

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

States a specific verb and resource: evaluating whether a proposition is true against the current state pack, with calibrated probability and abstain safeguards. It also differentiates itself from the sibling ask_score by naming the binary-vs-continuous distinction, so an agent can select correctly without opening either schema.

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

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

Explicitly names the alternative (ask_score) and the exact condition that selects this tool over it: binary truth/falsehood rather than scoring an entity on a continuous scale. That is a direct when-to-use routing rule, not an implied one.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable context beyond them by disclosing the return shape (normalized score within scale bounds, criterion breakdown, evaluation confidence), which matters since no output schema exists. It does not mention auth or rate-limit behavior, keeping it short of a 5.

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

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

Two well-formed sentences, with the core purpose front-loaded and the sibling comparison second. No filler, though the return-value sentence could be marginally tighter.

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

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

For a read-only evaluation tool with a rich 6-parameter schema and no output schema, the description covers purpose, routing, and return contents. Minor gaps remain around the optional state_pack and criteria weighting semantics, but nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%, so all six parameters are self-documented; the baseline is 3. The description reinforces 'weighted criteria' and 'scale bounds' conceptually but adds no syntax, format, or default details beyond what the schema already states.

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

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

States a specific verb (evaluate) and resource (entity, plan, or action) with the exact evaluation mode: a bounded continuous scale against weighted criteria. It explicitly names the sibling it differs from (ask_noul), so an agent can distinguish them without opening either schema.

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

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

Gives an explicit routing rule: use ask_score instead of ask_noul when the question is continuous numeric quality/fitness rather than binary truth. This is a when-to-use plus an alternative, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context: the assessment is computed 'against active utility weights' (a state dependency) and it returns a 0.0-1.0 score with threat breakdown and comparative ratings. It does not describe cost, latency, or what happens when no weights are set, so it stops short of a 5.

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

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

Three tightly packed sentences with the purpose and routing rule front-loaded. The parenthetical enumeration of modes is mildly redundant with the schema enum, but it aids scanning and costs little.

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 9-parameter analyzer with nested objects and no output schema, the description covers purpose, routing, state dependency, and the shape of the return value (score range, threat breakdown, comparative ratings). Only edge behaviors, such as missing utility weights or invalid trajectories, are unaddressed.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters including the mode enum, trajectory waypoints, and clearance_threshold default. The description's parenthetical mode list and mention of '3D spatial rollouts' restate the schema rather than adding format or constraint detail. Baseline 3 is correct.

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

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

States a specific verb+resource ('Compute quantitative risk and threat assessment') and scopes the accepted modes. It explicitly names the sibling it is not, so an agent can separate assess_risk from evaluate_situation without opening either schema.

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

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

Gives an explicit routing rule: 'Use assess_risk instead of evaluate_situation when estimating failure probability and threat exposure rather than ranking overall utility.' This names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds that the operation is deterministic (System One calculus) and specifies return values (top label, probability distribution, margin), which is valuable since no output schema exists. It does not cover error behavior or rate limits, but the annotation set carries the safety profile.

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

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

Three sentences, front-loaded with purpose, followed by routing guidance and return values. Every sentence contributes new information without repetition or filler.

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

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

For a tool with no output schema, the description usefully states what is returned (top class label, probability distribution, classification margin). Annotations cover safety and idempotency, and the schema covers parameters fully. Minor gaps around state_pack semantics and error handling remain, but the core needs are met.

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 itself documents all five parameters. The description mentions the target types broadly but adds no syntax, constraints, or meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb (assign semantic categorical labels) and resource scope (entity, visual_state, task, snapshot) and names the sibling tool it replaces (ask_choice). An agent can distinguish it from ask_choice and ask_score 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 gives an explicit when-to-use rule: assign predefined taxonomy labels rather than selecting among runtime decision alternatives, and names the alternative tool ask_choice. This is clear routing guidance with an implicit when-not condition.

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 readOnlyHint=false, idempotentHint=false, non-destructive and closed-world, so the safety profile is already supplied. The description adds useful return-shape context (ranked candidate actions, expected utility scores, top recommendation), but says nothing about what state is persisted or whether trace/session records are written, which matters for a non-read-only tool.

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

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

It is front-loaded with the core verb sequence, then the routing rule, then the return values, with no filler sentences. The utility/decision-theory terminology is dense but each sentence carries information.

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

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

For a 9-parameter tool with nested objects, an enum mode switch and no output schema, the description does cover the return values and the key routing decision. It leaves the role of trace_id, session_id and project unaddressed, but those are documented in the schema, so the gap 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 description coverage is 100% across 9 parameters, so the schema already explains action, snapshot, quick_context, lookahead_depth, utility_profile and candidate_actions. The description adds only the two enum mode names and the notion of scoring against active weights, which is marginal beyond the structured fields.

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 pipeline of verbs and resources: ingest a multi-modal snapshot, compute expected utilities against active weights, and output prioritized action recommendations, with the modes (snapshot, quick) called out. It also explicitly distinguishes itself from the sibling assess_risk, so an agent can route without opening either schema.

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

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

It states an explicit routing rule: use evaluate_situation rather than assess_risk when ranking candidate actions across multi-attribute utility dimensions instead of computing isolated threat probabilities. That is a genuine when-to-use/when-not rule, though it covers only one sibling out of many and gives no prerequisites or preconditions for the modes.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: this is a precondition gate whose approval produces a cryptographic HMAC token, and it returns a verdict plus risk evaluation. It stops short of saying what a rejection looks like to the caller or whether the token has a lifetime/one-time-use constraint, so it is not fully transparent.

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, roughly fifty words, with the core purpose front-loaded in the first clause and no filler. The return-value sentence earns its place because no output schema exists.

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

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

With no output schema, the description carries the return-value burden and does so adequately (verdict, risk evaluation, HMAC token). Given a five-parameter nested schema and a gating role in a behavior-dispatch pipeline, it could say more about rejection handling and token use, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters (project, state_pack, intention_id, context_goal_id, proposed_action and its nested fields) are already documented structurally. The description references the intention and proposed action conceptually but adds no syntax, format, or interaction detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb and resource ('Evaluate an intention before dispatching to behavior-mcp') plus the concrete output ('issue a cryptographic HMAC dispatch token if approved'). It also explicitly names the sibling it is not, manage_intentions, so an agent can separate the two without opening either schema.

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

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

Gives an explicit routing rule: 'Use gate_intention instead of manage_intentions when verifying precondition safety and issuing execution authorization rather than tracking intention state.' This names the alternative and the condition that selects it, which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value by enumerating the return structure (trace, utility breakdown, candidate rankings, explanation text), which matters since no output schema exists. It does not discuss filtering semantics or limits, keeping it short of a 5.

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

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

Two short sentences, purpose front-loaded and the sibling call-out second. The parenthetical action list duplicates the enum and the return enumeration slightly overlaps, but nothing is buried or wasted.

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

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

With no output schema, the description helpfully summarizes return values, and annotations carry the safety profile. What is missing is guidance on how action values interact with the other params (which params apply to get vs list), leaving a small gap for a 5-param tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the action enum. The description only restates the action values parenthetically and adds no syntax or interaction detail (e.g., trace_id required for get/explain), so baseline 3 is correct.

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

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

States a specific verb (Retrieve) and resource (decision trace) plus the payload it contains (chain-of-thought rationale, candidate utilities, risk assessment). It explicitly contrasts itself with query_knowledge, so an agent can distinguish it from siblings without schema inspection.

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

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

Names the alternative (query_knowledge) and the precise condition that selects this tool: deep forensic analysis of a specific historical decision. The action set (latest, get, list, explain) further signals usage modes.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real behavioral context beyond them: TTL expiration sweeps, exponential confidence decay, and category filtering, plus the shape of the return value. It still doesn't say what the destructive expire path actually removes or how update overwrites prior state, so it falls short of full disclosure.

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

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

Front-loads the capability and the sibling comparison, then closes with the return shapes. Two focused sentences with little waste; the return sentence earns its place because there is no output schema.

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

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

For a 16-parameter, five-action mutation tool with no output schema, the description compensates by listing return values (belief record, query matches, expired count, reconciliation report) and the action set. The remaining gap is that it never indicates which parameters are required by which action, which matters at this parameter count.

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

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

Schema description coverage is 100%, so all 16 parameters are already documented in the schema and the baseline is 3. The description adds the action vocabulary but no per-action parameter mapping or format detail (e.g., which fields reconcile_spatial requires) beyond what the schema states.

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

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

States a specific verb ("Maintain") and resource ("structured belief state") and enumerates the five supported actions, so the scope is unambiguous. It also explicitly distinguishes itself from the sibling query_knowledge, letting an agent route without opening either schema.

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

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

Explicitly names the alternative tool (query_knowledge) and the condition that selects this one instead (dynamic agent epistemic state vs static heuristic patterns). That is a direct when-to-use/when-not-to-use rule rather than implied 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the agent knows this is a non-destructive, non-idempotent mutation surface. The description adds the multi-action nature and the return categories, but does not disclose side effects of cancel/resolve, permission needs, or why the operation is non-idempotent despite having a client_request_id idempotency key.

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

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

Front-loaded with the action verbs and resource, followed by the routing rule and the return-value summary. Tight and well-ordered, with only slight redundancy between the action list in prose and the enum in the schema.

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

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

For a 13-parameter multi-action tool with nested objects and no output schema, the description covers purpose, routing, and return categories, and the fully-described schema fills in the per-action parameter requirements. Minor gap: it does not map which parameters apply to which action (e.g., intention_id for dispatch/get/cancel/resolve).

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 every parameter is already documented in the schema; the description adds no per-parameter meaning beyond what is structured. Baseline 3 is appropriate when the schema carries the 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?

States specific verbs (queue, dispatch, track, cancel, resolve) applied to a clear resource (behavior directives / intentions) and enumerates the six actions. It explicitly distinguishes itself from the sibling set_goal, so an agent can tell the two apart without opening either schema.

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

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

Names the alternative tool (set_goal) and the exact condition that selects this one instead: dispatching immediate execution instructions to runtime behaviors vs. managing abstract objectives. This is explicit 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered by structured data. The description adds useful return-shape context ('Returns database diagnostics, Merkle audit tree, snapshot metadata, or diff reports'), but never warns that 'restore' overwrites existing database state or that actions carry differing risk — information an agent would want beyond the blunt destructive flag.

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

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

Two tight sentences, front-loaded with the capability summary followed by routing and return information; no filler. The parenthetical action list is slightly redundant with the schema enum but keeps the definition self-contained.

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

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

With no output schema, the description compensates by stating what categories of results are returned, and annotations carry the safety profile. It is close to complete for a six-action multiplexed tool, though per-action behavior (especially restore semantics) remains unspecified.

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

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

Schema description coverage is 100% and the enum is fully documented in the schema, so the baseline is 3. The description only restates the action list and adds no syntax, format, or dependency details (e.g., that 'name'/'description' are only relevant to snapshot) beyond what the schema provides.

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

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

The description names a specific verb+resource ('Database maintenance, diagnostics, SHA-256 Merkle audit verification, and snapshot management') and enumerates the six concrete actions, so an agent knows exactly what domain this covers. It also explicitly contrasts itself with the sibling manage_beliefs, making it distinguishable without opening either schema.

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

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

It gives an explicit routing rule: 'Use manage_reasoning_db instead of manage_beliefs when performing SQLite storage integrity verification or database snapshot restore.' That is a clear when-to-use-this-vs-alternative condition. It stops short of covering the other actions (stats, diff, doctor) or any when-not/exclusion guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful return context by naming the kinds of matches returned (heuristics, anti-patterns, tactics, similarity scores) and the cross-session scope, though it does not discuss pagination or rate limits.

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 front-loaded with purpose and routing guidance, then states the return contents. Every sentence adds useful information without repetition or filler.

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

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

For a six-parameter read-only search tool with rich annotations, the description supplies purpose, usage routing, supported action modes, and the shape of returned results. With no output schema, the return summary is especially valuable and sufficient 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%, so all six parameters are already documented in the schema, including the action and pattern_type enums. The description repeats the action modes but adds no syntax, format, or interaction details beyond what the schema provides.

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

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

The description states a specific verb (Search) and resources (learned heuristic patterns, tactics, past decision traces) and names the supported actions. It also explicitly distinguishes the tool from get_decision_trace by contrasting generalized cross-session patterns with a single execution trace.

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

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

It gives explicit routing guidance: use query_knowledge instead of get_decision_trace when retrieving generalized patterns across sessions, rather than inspecting one execution trace. This covers when to use it, when to prefer an alternative, and the alternative itself.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is partly covered. The description adds real context beyond them by enumerating the trigger actions and describing what is produced/side-effected (replanned DAG, invalidated intentions, synthesized subgoals). It stops short of explaining permissions or whether invalidation is reversible, so not a 5.

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

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

Three front-loaded sentences with clear routing guidance and no filler. Repeating the action list is mildly redundant with the schema enum, which keeps it from a 5.

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

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

For a six-parameter mutation tool with no output schema, the description usefully names the return payload and the alternative tool, and annotations cover safety. It is nearly complete, lacking only error/precondition behavior for when replanning fails.

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

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

Schema description coverage is 100%, so all six parameters including the action enum are already documented in the schema. The description only restates the action values ('blocker, event, full') without adding semantics such as how 'full' differs from 'event'. Baseline 3 applies when the schema carries the load.

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 — 'Regenerate sub-task DAG and adjust intentions' — and explicitly scopes the trigger to 'unexpected obstacles or state changes'. It also names and contrasts against the sibling set_goal, so an agent can distinguish it without opening either schema.

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

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

It gives an explicit when-to-use rule plus the alternative: 'Use replan instead of set_goal when recovering from execution blockers or environment shifts rather than creating new goals.' The condition that selects this tool over the sibling is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is covered. The description adds an enumeration of return shapes (goal record, sub-goal hierarchy, progress, lists), which is useful since there is no output schema, but it says nothing about permissions, whether 'abandon' is reversible, or side effects of decompose. It adds some context but not rich behavioral disclosure.

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

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

The description is front-loaded with the action set and the sibling routing rule, then closes with a brief returns sentence. It is appropriately sized for a multi-action tool, with no filler, though the opening verb list is slightly dense.

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 15-parameter, nested-object, no-output-schema tool, the description covers the action space, sibling routing, and return shapes, which is most of what an agent needs. It stops short of per-action parameter guidance (e.g. which fields apply to decompose vs update), leaving a modest gap.

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

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

Schema description coverage is 100%, so every one of the 15 parameters is already documented, including which actions require `id` and the action enum. The description only restates the action names and does not enrich parameter meaning beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource (hierarchical goals and task DAGs) and enumerates the exact verb set (create, update, decompose, get, list, abandon), so an agent knows precisely what the tool does. It also distinguishes itself from the sibling manage_intentions, making it identifiable without opening a schema.

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

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

It gives an explicit routing rule: use set_goal rather than manage_intentions 'when formulating multi-step objectives and sub-goal DAGs rather than queueing concrete execution directives.' The alternative and the condition that selects it are both stated.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds the return surface (configured profile, active weight map, or profile directory), which is genuinely useful given no output schema exists, but says nothing about side effects of activate/nudge or auth requirements. Adequate, not rich.

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

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

Front-loaded with purpose and action list, then the routing rule, then returns — a sensible ordering with no filler sentences. The action list is restated from the enum, a minor redundancy that keeps it from a 5.

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

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

For a 7-parameter multi-action tool with nested objects and no output schema, the definition covers purpose, action routing, alternative selection, and the shape of returns. It is close to complete; the only gap is per-action behavioral detail for the mutating actions.

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 every parameter including the action enum is already documented in the schema; baseline 3 applies. The description adds no syntax, range, or interaction detail (e.g. how delta composes with weights) beyond what the schema states.

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

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

States a specific resource (multi-attribute utility weight profiles) with an explicit verb set and enumerates the five supported actions, so the agent knows exactly what operations this tool performs. It also names the sibling it must not be confused with (evaluate_situation) and the distinction between them, which is more than most definitions provide.

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 gives the selection rule: use this instead of evaluate_situation when defining decision preferences rather than evaluating actions. That is a clear when-to-use-vs-alternative statement. It does not, however, give per-action guidance (e.g. when to nudge vs configure), which keeps it short of a full 5.

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