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

With no annotations, the description carries the behavioral burden. It discloses that stale revisions are rejected as conflicts and that dependencies are validated against existing tasks. However, it does not mention side effects, permissions, or success/failure behavior beyond these points.

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

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

Three tight sentences, front-loaded with the purpose, then conflict behavior, then parameter shape. No filler or redundant restatement of the tool name.

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

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

Even with an output schema present, an 8-parameter mutation tool with zero annotations and zero schema descriptions needs more parameter context. The description covers only two parameters, leaving required fields like expected_revision and role under-specified.

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 useful meaning for task and dependencies, but leaves role, actor_id, expected_revision, plan_id, reason, and priority unexplained in both the schema and the description.

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

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

States a specific operation: appending a new task to an already-initialized Plan. The wording distinguishes it from initialize_project and from task-modification siblings like edit_task, update_task, or cancel_task.

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?

Clearly scopes usage to an already-initialized Plan and gives a precondition: dependency targets must already exist. It does not explicitly name alternatives or say when not to use it, but the context is clear.

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

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

With no annotations, the description carries the full burden. It discloses that cancellation is 'logical' rather than physical and that an audit Event is produced, which are useful behavioral signals. However, it does not explain failure conditions, reversibility, permissions, or the role of expected_revision, leaving important behavior undisclosed.

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, tightly worded sentence that front-loads the core action and adds only essential qualifiers. Every word contributes meaning, with no filler or redundancy.

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

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

For a mutation tool with six parameters, zero parameter documentation, and no annotations, the description is too thin. Even though an output schema exists, the agent lacks guidance on parameter semantics, expected_revision's concurrency role, valid task states, and the audit event's consequences. The description covers basic purpose but not enough for confident 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 for the six undocumented parameters. It adds no meaning for task_id, actor_id, role, expected_revision, plan_id, or reason. The phrase 'pending or owned in-progress' is contextual but not parameter-level 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 uses a specific verb ('cancel') and resource ('task'), and adds meaningful scope: 'pending or owned in-progress'. This distinguishes it clearly from siblings like edit_task, update_task, recover_task, or claim_task. The phrase 'with an audit Event' also signals a unique behavioral characteristic.

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 conveys clear usage context: it is for canceling tasks that are pending or owned/in-progress. It does not explicitly name alternatives or provide when-not-to-use guidance, but the state qualifiers give the agent a workable selection criterion among sibling task 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?

With no annotations, the description takes on the full burden of behavioral disclosure. It notes the atomicity of the operation, the rejection of stale revisions as conflicts, and that work_scope is recorded on the task_started Event but not enforced. This is substantial, though it does not describe other side effects like status changes on the task. Overall, it gives the agent important behavioral context beyond the schema.

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

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

The description is compact and front-loaded with the core purpose. The follow-up detail about work_scope is focused and includes a concrete example. Every sentence contributes meaningful information without redundancy, making it efficient 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?

The output schema is present, so return values are covered, and the description explains the key behavioral aspects and the work_scope parameter. However, it does not clarify how expected_revision should be obtained or the meaning of role, which are important for a concurrency-sensitive claim operation. This leaves modest but notable gaps in the guidance needed for correct invocation.

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

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

The schema description coverage is 0%, so the description must compensate, but it only explains work_scope. It provides an example and clarifies that work_scope is not enforced, which is helpful. However, the other five parameters (task_id, actor_id, role, expected_revision, plan_id) are unexplained, leaving the agent to rely on name inference. This is inadequate given the low coverage.

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 exactly what the tool does: atomically claim one executable task. The verb 'claim' and resource 'task' are specific and distinct from sibling tools like add_task, edit_task, and recover_task. The stale-revision conflict behavior further distinguishes it from other task lifecycle operations.

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 intended use is clear from the description, but there is no explicit guidance on when to use this tool instead of alternatives. It does not mention exclusions such as whether a task must already exist or whether a different tool should be used for recovery. Usage is implied by the tool name and purpose rather than explicitly spelled out.

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

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

With no annotations, the description carries the behavioral burden. It discloses revision-based optimistic concurrency, immutability of task IDs, and the empty-dependencies clearing behavior. It does not discuss authorization, reversibility, or error conditions, but the provided behavioral constraints are meaningful.

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. It front-loads the core operation and then adds compact, high-value constraints about immutability and dependency removal.

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

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

For a 10-parameter mutation tool with no annotations, the description is too thin. An agent cannot confidently determine how to populate required parameters like `expected_revision` and `actor_id`, or whether 'Role' refers to `role` or `task_role`. The existence of an output schema reduces return-value concerns, but invocation semantics remain under-specified.

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 clarifies `dependencies` and partially clarifies text and role, but leaves `expected_revision`, `actor_id`, `plan_id`, `priority`, `reason`, and the relationship between `role` and `task_role` unexplained.

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 ('Edit'), a resource ('a pending task'), and the editable aspects ('text, required Role, or dependencies') with a concurrency mechanism. It is clear enough, though it leaves ambiguity between the `role` and `task_role` parameters and does not distinguish itself from the sibling `update_task`.

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 intended context is implied: use this when modifying a pending task's text, role, or dependencies. It also gives a useful special case (`dependencies=[]` removes all dependencies), but it does not explicitly say when not to use it or how it differs from `update_task` or other task-related 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 provided, the description carries the full burden. It discloses a significant behavioral trait: the tool does not alter Plan state. However, it does not explain what 'append' entails (e.g., persistence, outbox behavior), potential side effects outside plan state, or error handling. This is a useful but not exhaustive 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 followed by a clarifying statement. It is extremely concise, front-loads the main action, and earns every word. There is no superfluous 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?

The tool is simple, has an output schema that likely describes return values, and the description covers the core purpose and a key constraint. The main gap is the absence of parameter semantics, but that is handled by the schema. The relationship to flush_event_outbox or read_event is not clarified, but it is not essential for basic usage.

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 description coverage is 0%, so the description must compensate, but it says nothing about event_type, actor_id, role, content, or task_id. While the parameter names are somewhat self-explanatory, the description adds no semantic meaning beyond what the parameter names already imply. This leaves the agent to infer the meaning of 'role' or 'content' without guidance.

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 ('Append') and a resource ('audit Event'), and immediately clarifies that it does not change Plan state. This differentiates it from the many plan-modifying sibling tools such as add_task, edit_task, and update_task. The purpose is unambiguous.

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

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

The phrase 'does not change Plan state' provides a clear context: use this tool when you need to record an audit event without affecting plan data. It doesn't explicitly name an alternative, but it gives a strong indication of when it is appropriate versus the plan-mutating tools in the 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 must fully disclose behavioral traits. It mentions the retry-after-failure context but does not state whether the operation is idempotent, what happens if there are no pending events, whether it can fail again, or what side effects occur (e.g., re-emitting events). This is a significant gap for a retry 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 concise sentence with no fluff, which is good for conciseness. However, it is under-specified; the brevity comes at the cost of missing critical information. It is front-loaded with the key action but lacks the necessary detail to be genuinely useful.

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?

Even though an output schema exists (not shown here), the description does not explain what the retry does in practice, what the response indicates, or how failures are handled. For a tool that involves retrying after a failure, the agent needs more context about retry semantics, potential partial success, or error conditions. The description is too sparse to be 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 descriptions coverage is 0%, so the description must explain the parameter. The description does not mention 'plan_id' at all, and the schema only provides a default value. The agent has no idea what this parameter controls or how to use it functionally, making the description completely unhelpful for parameter understanding.

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 (retry), the resource (pending Plan-generated Events), and the condition (after a previous Event write failure). It distinguishes itself from siblings like emit_event by focusing on retrying pending events rather than creating them. However, 'flush' is slightly ambiguous and could be interpreted as clearing rather than retrying, though 'retry' clarifies intent.

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 provided on when to use this tool versus alternatives. The description implies a retry scenario but does not explicitly state when an agent should call this over emit_event or read_event, nor does it mention any prerequisites or exclusions (e.g., 'use only after a failed write to the event outbox').

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 the non-obvious behavior that stdio connections keep their startup-time schema and explains that an old started_at/git_sha indicates a stale connection. This goes well beyond simply stating the tool's purpose.

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 core purpose is front-loaded in one short sentence. The second paragraph is longer but earns its place by providing essential troubleshooting context, with no filler or redundancy.

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

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

There are no parameters, the output schema covers return values, and the description supplies the key non-obvious context about connection staleness. For a zero-parameter introspection tool, this is 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 tool has zero parameters and an empty input schema, so there is nothing for the description to clarify. The baseline of 4 for no-parameter tools is appropriate here.

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 first sentence uses a specific verb ('Report') and names the exact returned resources: version, git SHA, start time, and Blackboard root. This is far more informative than a tautological restatement and clearly distinguishes the tool from the memory/plan/task/state siblings.

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

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

The description gives explicit when-to-use guidance: call this first when an expected tool seems missing, because a stale connection can hide newly added tools. It also tells the agent how to interpret the results, making the diagnostic workflow actionable.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the concrete side effect—creating directories and a Plan file—and notes that additional plans can be created with a new plan_id. However, it does not state whether calling with an existing plan_id overwrites, errors, or is a no-op, and it omits details about required permissions or failure modes.

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 compact, front-loaded with the tool's core function, and every sentence earns its place: what it does, who uses it, when to avoid it, and how to reuse it. No filler or redundancy.

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

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

Although an output schema exists and return format needs no explanation, the description is incomplete for a 5-parameter tool with 0% schema coverage. The missing semantics for tasks and dependencies—key inputs for initializing a project—prevent the description from being fully actionable.

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 adds meaning for plan_id ('new plan_id'). The fields project_id, title, tasks, and dependencies are not explained at all, leaving an agent unable to construct a correct call from the description alone.

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

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

The description clearly states a specific action ('Create the Blackboard directories and one named Plan file') and a specific resource (directories and a Plan file). It also distinguishes itself from all sibling tools by positioning itself as a bootstrap utility that a human uses to create a project, while LLM collaboration uses the core Blackboard tools listed above.

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

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

The description explicitly says when this tool is used ('by a human when creating a project') and when it is not ('LLM collaboration thereafter uses the core Blackboard tools above'). It also explains how to reuse it for additional plans ('calling this again with a new plan_id'). This is strong, explicit guidance.

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

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

With no annotations, the description carries the full burden. It discloses that the tool is an observation aid, that roles are self-declared, and that nothing is enforced. This effectively communicates side-effect-free read-only behavior without explicitly stating 'no side effects.' It could add details about authorization requirements or rate limits, but for a simple list tool the disclosure is sufficient.

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 sentences of clean, directly relevant text. The core purpose is front-loaded in the first sentence, and the second sentence adds a critical caveat. No filler or repetition.

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

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

For a zero-parameter tool with an output schema and a clear purpose, the description is complete. It explains what the tool does, when to use it, and what to be cautious about. Nothing an agent needs to select or invoke it correctly is missing.

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

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

The tool has zero parameters, so per the baseline the description does not need to add parameter-level detail. The description mentions actor_id in the output context, but since there are no inputs, no further semantic compensation is required. The baseline of 4 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 opens with a specific verb and resource: 'Report which roles each actor_id has claimed tasks under, across every Plan.' It clearly distinguishes this tool from siblings like list_memory or list_plans by focusing on actor-role mapping. No other sibling tool covers this functionality.

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 provides explicit usage context: use it to sanity check who has been active under which roles before trusting a Memory/Event entry from an unfamiliar actor_id. It also states what it is not (not authentication) and why (self-declared roles, nothing enforced), giving clear when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal two key behaviors: the list is in 'deterministic ID order' and it excludes 'full content.' However, it does not explicitly state that the operation is read-only/safe, nor does it describe any pagination, limits, or error handling. These are notable omissions for a tool with no annotation support.

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 that is concise and front-loaded. It states the action, the resource scope, and two important behavioral details (deterministic order, no content) with no wasted words. Every element earns its place.

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

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

For a simple, zero-parameter tool with an output schema, the description is nearly complete. It covers the main purpose and key behavioral traits. The main gap is the lack of explicit guidance on when to use this versus read_memory, but given the sibling names and the 'without full content' phrasing, the context is mostly sufficient. An output schema defines the return structure, so that is not a deficiency here.

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

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

The tool has zero parameters, so the empty input schema already documents all parameters. The baseline score for 0-param tools is 4. The description adds behavioral context but does not need to explain parameter semantics since none exist. No credit is lost for not adding parameter info beyond the schema.

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

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

The description clearly states a specific verb ('List'), a resource ('Memory metadata'), and a distinguishing characteristic ('without full content'). It differentiates from sibling tools like 'read_memory' (which likely returns full content) and 'list_plans' (which lists a different resource). The mention of 'deterministic ID order' adds clarity about the operation's behavior.

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 provides clear context for when to use this tool: when you need memory metadata but not full content. The phrase 'without full content' implies an alternative for full content (such as read_memory), but it does not explicitly name the alternative or state a when-not-to-use condition. This is more than merely implied but lacks explicit exclusionary guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool lists plans along with their in-progress tasks and surfaces claim ownership ('what is already claimed, by whom'), which goes beyond a bare 'list' statement. It does not explicitly state read-only behavior or auth requirements, but the described behavior is clear.

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 three sentences long, with the core purpose in the first sentence and usage context following. There is no redundancy or fluff; every sentence adds either functional scope or actionable guidance, and the structure front-loads the primary function.

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 zero-parameter list tool with an output schema, the description covers what it returns (named plans with in_progress tasks, claim ownership) and when it should be called (before claim work under concurrency). Nothing an agent needs to invoke or interpret the tool is missing.

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

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

The tool has zero parameters, and the schema shows 100% coverage by vacuity. As a result, there are no parameter semantics for the description to clarify, and the baseline score of 4 applies because the description is not required to add parameter detail.

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 a specific action ('List') and resource ('named Plans in this Blackboard root'), and specifies that each plan includes its in_progress tasks. This makes the tool's purpose obvious, though it does not explicitly differentiate from sibling tools like read_plan or get_server_info.

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 provides a concrete usage scenario: 'Check this before claiming work when multiple actors may be active.' It also explains what the tool reveals (what is claimed and by whom), which helps the agent decide when this tool is appropriate. However, it does not mention when not to use it or list alternative 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?

No annotations exist, so the description carries the full burden of behavioral disclosure. It does disclose two useful behaviors: deterministic ID ordering and metadata-only output. However, it never explicitly states the operation is read-only/safe, and says nothing about empty-state behavior or pagination, so disclosure is partial.

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 where every element earns its place: verb, resource, ordering behavior, and content exclusion. No wasted words, no filler, and the most decision-relevant constraint ('without full content') appears up front.

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?

Complexity is low (0 params) and an output schema is present, so the description only needs to establish scope and behavior. It does so with 'State metadata' and 'without full content'; the only nicety missing is an explicit pointer to read_state for full content, which is minor given the phrasing.

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

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

The tool has zero parameters, which sets the baseline at 4. The description adds no parameter syntax (none exists) but does clarify what the call returns — metadata, in deterministic ID order — which is the only semantics an agent needs for a parameterless call.

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

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

States a specific verb ('List') and resource ('State metadata'), and adds two scoping qualifiers — 'in deterministic ID order' and 'without full content' — that clearly differentiate it from the sibling read_state and write_state tools. The contrast with full-content retrieval is evident even though no sibling is named.

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 explicit when-to-use guidance and no named alternatives. The phrase 'without full content' implies the tool is for metadata-only needs and hints that full content lives elsewhere (read_state), but the description never states that condition, leaving the agent to infer the routing.

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

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

With no annotations provided, the description must carry the behavioral burden. 'List audit Events' indicates a non-mutating read operation and 'audit' adds useful context, but it does not disclose ordering, pagination, time-format semantics, or any restrictions/requirements. The behavior is not contradicted, but the disclosure is minimal.

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 that states the action, object, and optional filters with no filler. Every word earns its place, and the most important information appears first.

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 a simple read-only listing operation with all parameters optional and an output schema available, so the description is serviceable. Still, without annotations and with 0% schema coverage, the one-sentence description leaves gaps such as pagination/limit behavior and time-format expectations that an agent may need when invoking with filters.

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 five parameters. It maps event_type, task_id, and since/until through 'type, task, or created time range', which adds the 'created time' meaning to since/until. However, it does not clarify the expected string/time format or describe the limit parameter at all.

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 ('List') and resource ('audit Events') and names optional filtering dimensions, so an agent immediately knows what the tool does. It is clearly distinct from siblings like emit_event, which writes events rather than reading them.

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 'optionally filtered by type, task, or created time range' implies the appropriate use case for retrieving audit events with filters. However, it does not explicitly say when to prefer this over alternatives (e.g., emit_event or list_state) or mention any exclusions, so the guidance 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?

With no annotations, the description carries the full burden. 'Read' and 'persistent' signal a non-mutating lookup of durable data, but the description does not disclose behavior for missing ids, error responses, or any other edge cases. Some transparency is provided, but not rich context.

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

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

One short sentence with no filler, front-loading the action and resource. Every word earns its place, and the structure is appropriate for the tool's simplicity.

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 tool with an output schema, the description is mostly complete. It states what is read and by what key. The only notable gap is the lack of failure-behavior context, but this is minor for such a simple operation.

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 id' clarifies that the single id parameter identifies which Memory document to read, but it adds no format, constraint, or additional semantic detail. Adequate for a single self-evident parameter, but shallow.

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 ('Read'), a specific resource ('persistent Memory document'), and a selection mechanism ('by id'). This clearly distinguishes it from sibling tools like list_memory (listing) and write_memory (writing).

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 'by id' implies this tool is for reading a single known Memory document, which is useful context. However, it does not explicitly state when to choose this over list_memory or write_memory, nor does it mention any exclusions or prerequisites.

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 transparency burden. The verb 'Read' implies a non-mutating operation, but it does not explicitly state side effects, error behavior, permission requirements, or any conditional logic. It provides minimal behavioral context beyond the literal action, leaving assumptions to the agent.

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 waste, front-loading the action 'Read' and clearly stating the object and the optional modifier. It is appropriately sized for the tool's low complexity and conveys the core functionality 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 simple read tool with an output schema, the description is adequate. It tells the agent that one plan is read and optionally filtered by role, and the schema provides parameter defaults and return structure. Missing details like error handling are not critical for a typical read operation, and the output schema reduces the need for the description to explain return values.

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 clarifies that plan_id selects the plan and role is an optional filter, which maps to the two parameters. However, it does not explain the default values ('project' and null) or the exact effect of role on task filtering, leaving some ambiguity about how role influences the returned tasks.

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 (Read), the target (one Plan), and includes the nuanced detail of executable tasks, optionally filtered by Role. This distinguishes it from list_plans (which lists plans) and validate_plan (which checks validity), making the tool's specific purpose unambiguous.

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

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

The description implies the tool is used when you need details of a specific plan, but it does not explicitly discuss when to choose this over siblings like list_plans or validate_plan, nor does it list exclusions. An agent can infer usage from the purpose, but there is no direct comparison or contextual guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the stale_warning field behavior and clarifies that the tool never auto-rewrites State from Plan. This is valuable but does not address error handling or what happens when the id is not found; the output schema partially covers return 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?

Three short sentences with the main action front-loaded. The stale_warning note and the non-auto-rewrite clarification are relevant and earn their place without any fluff.

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

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

For a single-parameter read tool with an output schema, the description is nearly complete. It covers key behavioral quirks and side effects, but stops short of explicit usage guidance against sibling tools. The simplicity of the tool keeps this gap 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 0%, so the description must compensate for the id parameter. It says 'by id' but adds little beyond the schema's property name and type. No format, example, or guidance for obtaining a valid id is provided, leaving the semantics minimally explained.

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 states a specific verb ('Read'), resource ('State document'), and the identifying key ('by id'). The clarification that State is never auto-rewritten from Plan distinguishes it from plan-related siblings like read_plan, making the purpose unambiguous.

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

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

The description provides behavioral context—'read-time nudge only' and 'never auto-rewritten from Plan'—but does not explicitly say when to use read_state versus list_state, write_state, or read_plan. No alternatives or exclusion criteria are named, so usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the authorization requirement ('declared Role needs recover_task permission') and the state transition, but it does not explain concurrency behavior via expected_revision, failure modes, or whether recovery is idempotent.

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 sentence that front-loads the action and result, then adds permission context 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?

This is a five-parameter mutation with no annotations, and the description omits parameter meaning and concurrency/failure behavior, despite naming the state transition and permission. The output schema reduces the need to describe return shape, but invocation correctness is still under-specified.

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 'role' must hold recover_task permission. It does not clarify task_id, actor_id, plan_id, or expected_revision, leaving the agent without adequate parameter meaning for invocation.

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 state transition ('Recover a blocked task to pending') with a clear verb and resource, which distinguishes it from sibling task operations like edit_task, cancel_task, or claim_task even without naming them.

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 usage for blocked tasks that need to return to pending, but it does not explicitly state when not to use it or name alternatives. The permission requirement is useful but is not guidance about choosing this tool over 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 provided, the description carries the full burden and does a good job: it discloses CAS-based conditional updates, an audit Event side effect, and the advisory, non-blocking semantic. It could add failure behavior for CAS mismatches or permission requirements, but the core behavioral profile is clear.

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 three short, dense sentences with the main action front-loaded. The second sentence earns its place by clarifying the advisory nature and preventing misuse. There is no redundancy 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 7-parameter mutation tool with no annotations and no schema descriptions, the description explains the intent well but omits operational preconditions an agent needs, such as how to obtain expected_revision, what role values are valid, and how plan_id is scoped. The output schema helps with return values, but invocation details remain incomplete.

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 has 0% parameter description coverage, so the description must compensate. It adds useful semantics for priority (P0-P3), expected_revision (CAS), and task_id (pending task), but it leaves actor_id, role, reason, and plan_id to be inferred from names and the audit context. This is partial compensation, not complete.

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 and resource: 'Set a pending task's advisory P0-P3 priority'. It also states the two key mechanisms, CAS and an audit Event, and explicitly distinguishes this from work-control operations by saying it does not choose, claim, or block work for any LLM. This clearly differentiates it from siblings like claim_task, edit_task, and update_task.

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

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

The description gives clear usage context: it applies to pending tasks, is human-facing backlog guidance, and is not a mechanism for LLM work selection. It implies when not to use it by stating it does not claim or block work, though it does not explicitly name an alternative tool such as claim_task.

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 behavioral disclosure burden. It reveals that the Plan state is authoritative, that an audit Event is placed in the Plan Outbox, and that retries are idempotent on persistence failure. It does not detail failure modes such as revision mismatch, but the disclosed behavior is substantial.

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

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

Three tightly scoped sentences with the action summary first, then permission conditions, then persistence behavior. Every sentence earns its place with no filler or repetition.

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

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

This is a moderately complex mutation tool with no annotations and no parameter descriptions. The description covers purpose, permissions, and outbox behavior, but leaves required parameter semantics and sibling-tool boundaries ambiguous. The output schema covers return values, so that part is not needed.

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 explains semantics for status and role constraints, but says nothing about required parameters like expected_revision, task_id, actor_id, or plan_id. expected_revision is especially opaque and critical for correct invocation.

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 concrete actions (finish, block, cancel, recover) on a task and clarifies the supported status transitions. However, it does not differentiate this from sibling tools like cancel_task, recover_task, or edit_task, so the boundary is not explicitly established.

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

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

Provides explicit permission rules: claim owners may set done/blocked/cancelled on in_progress tasks, and roles with recover_task permission may set pending on blocked tasks. It does not give when-not guidance or name sibling alternatives, but the context is otherwise clear.

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

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

With no annotations, the description carries the full burden. It explicitly states 'without changing it', which is a key non-mutation behavioral trait. However, it does not disclose the output format, error behavior, or any other side effects, 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?

The description is a single, tightly packed sentence that front-loads the action ('Diagnose') and scope. It wastes no words and is immediately parseable by an agent.

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

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

The tool has an output schema, so return values are covered elsewhere. The description clearly states what is diagnosed and that nothing is changed. However, it omits usage context and parameter semantics, though the schema provides the latter. Overall, adequate for a simple one-parameter tool.

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

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

The schema has one parameter, plan_id, with 0% description coverage. The description never mentions plan_id or how to identify the plan to validate. Since schema coverage is low, the description should compensate, but it does not add any meaning beyond the parameter name itself.

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 'Diagnose' and enumerates concrete targets: 'Plan metadata, task audit fields, dependencies, and Outbox'. It also clarifies the tool does not modify anything, which distinguishes it clearly from mutating tools like add_task or edit_task and from read-only siblings like read_plan.

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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or comparisons with siblings like read_plan or list_plans, leaving the agent to infer usage from the tool's name and general purpose.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does disclose the optimistic-concurrency-like behavior (updates require revision), which is valuable and goes beyond the schema. However, it omits other behavioral details such as conflict handling, idempotency, permissions, or what happens on creation with an existing ID. This is partial disclosure but not comprehensive.

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

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

The description is a single sentence of 14 words, front-loading the main action ('Create or update Memory') and then adding the critical update requirement. There is no redundancy or filler. It is perfectly 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?

Given seven parameters and a create/update dual-mode, the description is incomplete. It addresses the update prerequisite but does not explain the distinction between create and update in terms of which parameters are needed, nor does it mention tags/importance defaults or conflict behavior. The output schema may cover return values, but the description lacks sufficient usage context for an agent to invoke the tool correctly without further inference.

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 description coverage is 0%, so the description must explain the parameters. It only indirectly references 'expected_revision' via the word 'revision,' leaving the other six parameters (id, content, actor_id, role, tags, importance) unexplained. The property names are somewhat self-explanatory, but the description adds minimal semantic value beyond the schema.

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

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

The description clearly states the tool's function: 'Create or update Memory.' This uses a specific verb and resource, and the resource name 'Memory' distinguishes it from sibling tools like read_memory and list_memory. An agent can easily understand what this tool does and how it differs from related 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 provides an explicit usage prerequisite: 'Updates require the revision returned by read_memory.' This tells the agent to call read_memory first when updating, which is a clear context for correct use. It does not explicitly name alternatives or exclusions, but the resource naming and the update requirement give sufficient guidance for choosing this tool over read/list operations.

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

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

No annotations exist, so the description must reveal behavioral traits on its own. The revision requirement discloses an optimistic-concurrency/overwrite-protection behavior beyond the bare action. It does not cover permissions, destructive overwrite semantics, or side effects, so some burden is unmet.

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, action first and the update prerequisite second. No filler, and the key constraint is front-loaded.

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

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

With 0% schema coverage and no annotations, a creation/update tool needs more context about what id, content, actor_id, role, and status mean and when to use write_state versus write_memory. Only the revision prerequisite and output schema fill part of the gap, so the description is not complete enough 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 for the 7 parameters. It only illuminates expected_revision ('revision returned by read_state'); the required id, content, actor_id, role, and status remain unexplained. This is minimal compensation.

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 ('Create or update') and resource ('current State'), and references read_state, which anchors it in the state domain. It is clear but does not explicitly contrast with sibling write_memory or emit_event, so it lacks full sibling differentiation.

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

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

It gives an explicit workflow condition: updates require the revision returned by read_state, telling the agent to call read_state first for updates. It lacks any 'when not to use' or alternative tool routing, but the read_state prerequisite is clear contextual guidance.

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